com.safenetinc.luna

Class LunaTokenObject

java.lang.Object

com.safenetinc.luna.LunaTokenObject

public class LunaTokenObject
extends Object

An instance of this class represents an object stored on a Luna token. This proprietary class is used extensively under the hood of the LunaProvider framework and should be used very cautiously outside of that framework. For examples using this object please refer to the installed LunaProvider(JSP) samples...MiscObjectModDemo.java in particular.

The LunaTokenObject encapsulates the token object handle and implements a number of methods for accessing the object.

Method Summary

Modifier and Type	Method and Description
static void	clearDeriveTemplate() remove all elements from derive template
void	DestroyObject() Destroys the object on the HSM.
String	GetAlias() Returns the alias of the HSM object wrapped by this object.
boolean	GetBooleanAttribute(long attribute) Gets the boolean value of the given attribute.
long[]	GetClassAndType() Returns the PKCS11 key class (CKO_PUBLIC_KEY, CKO_PRIVATE_KEY, etc) and type (CKK_AES, CKK_RSA, etc) for the HSM object wrapped by this object.
Date	GetDateMadePersistent() Gets the date and time that the HSM object wrapped by this object was made persistent.
static LunaCKAttribute[]	getDeriveTemplate()
byte[]	GetFingerprint() Returns the fingerprint of the HSM object wrapped by this object.
int	GetHandle() Returns the handle of the HSM object wrapped by this object.
byte[]	GetLargeAttribute(long attribute) Returns the value of the requested attribute as a byte array.
LunaSession	getSession() Returns a session on the slot this HSM object lives in
int	getSlot() Returns the slot number of the HSM object wrapped by this object
long	GetSmallAttribute(long attribute) Returns the requested attribute value of the given key, interpreted as a PKCS CK_ULONG.
boolean	IsObjectPersistent() Checks if the HSM object wrapped by this object is persistent.
static LunaTokenObject	LocateKeyByAlias(String alias) Finds a key in the default slot by its alias.
static LunaTokenObject	LocateKeyByAlias(String alias, int slot) Finds a persistent key in the given slot by its alias.
static LunaTokenObject	LocateObjectByAlias(String alias) Finds a persistent object in the default slot by its alias.
static LunaTokenObject	LocateObjectByAlias(String alias, int slot) Finds a persistent object in the given slot by its alias.
static LunaTokenObject	LocateObjectByFingerprint(byte[] fingerprint) Finds a persistent object in the default slot by its fingerprint.
static LunaTokenObject	LocateObjectByFingerprint(byte[] fingerprint, int slot) Finds a persistent object in the given slot by its fingerprint.
static LunaTokenObject	LocateObjectByHandle(int handle) Finds an object in the default slot by its object handle.
static LunaTokenObject	LocateObjectByHandle(int handle, int slot) Finds an object in the given slot by its object handle.
static LunaTokenObject	LocateObjectByHandle(int handle, int slot, Map<Long,Object> sessionParameters) Finds an object in the given slot by its object handle.
void	MakePersistent(String alias) If this object is currently a session object, it is persisted with the given alias.
long	SetBooleanAttribute(long attribute, boolean value) Sets the value of the given boolean attribute.
static void	setDeriveTemplate(LunaCKAttribute[] aInTempl) set the desired derive template
long	SetLargeAttribute(long attribute, byte[] value) Sets the value of a large attribute.
long	SetSmallAttribute(long attribute, long value) Sets the value of the given attribute, as a PKCS CK_ULONG.
long	setUsageCount(long value) Sets the usage count for this object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

clearDeriveTemplate

public static void clearDeriveTemplate()

remove all elements from derive template

setDeriveTemplate

public static void setDeriveTemplate(LunaCKAttribute[] aInTempl)

set the desired derive template

Parameters:

aInTempl - derive template

getDeriveTemplate

public static LunaCKAttribute[] getDeriveTemplate()

Returns:

the derive template

LocateObjectByAlias

public static LunaTokenObject LocateObjectByAlias(String alias)

Finds a persistent object in the default slot by its alias. If multiple objects exist with the same alias, the first one found is returned.

Parameters:

alias - The alias for the object to find

Returns:

A persistent object with the given alias. If no objects with the given alias exist, null is returned

LocateObjectByAlias

public static LunaTokenObject LocateObjectByAlias(String alias,
                                                  int slot)

Finds a persistent object in the given slot by its alias. If multiple objects exist with the same alias, the first one found is returned.

Parameters:

alias - The alias for the object to find

slot - The slot to search

Returns:

A persistent object with the given alias. If no objects with the given alias exist, null is returned

LocateObjectByFingerprint

public static LunaTokenObject LocateObjectByFingerprint(byte[] fingerprint)

Finds a persistent object in the default slot by its fingerprint. If multiple objects exist with the same fingerprint (typically this will only happen for copied objects), the first one found is returned.

Parameters:

fingerprint - The SHA-1 fingerprint of the object to find

Returns:

A persistent object with the given fingerprint. If no objects with the given fingerprint exist, null is returned

LocateObjectByFingerprint

public static LunaTokenObject LocateObjectByFingerprint(byte[] fingerprint,
                                                        int slot)

Finds a persistent object in the given slot by its fingerprint. If multiple objects exist with the same fingerprint (typically this will only happen for copied objects), the first one found is returned.

Parameters:

fingerprint - The SHA-1 fingerprint of the object to find

slot - The slot to search

Returns:

A persistent object with the given fingerprint. If no objects with the given fingerprint exist, null is returned

LocateObjectByHandle

public static LunaTokenObject LocateObjectByHandle(int handle)

Finds an object in the default slot by its object handle.

Parameters:

handle - The object handle of the object to find

Returns:

An object with the given handle. If no objects with the given handle exist, null is returned

LocateObjectByHandle

public static LunaTokenObject LocateObjectByHandle(int handle,
                                                   int slot)

Finds an object in the given slot by its object handle.

Parameters:

handle - The object handle of the object to find

slot - The slot to search

Returns:

An object with the given handle. If no objects with the given handle exist, null is returned

LocateObjectByHandle

public static LunaTokenObject LocateObjectByHandle(int handle,
                                                   int slot,
                                                   Map<Long,Object> sessionParameters)

Finds an object in the given slot by its object handle.

Parameters:

handle - The object handle of the object to find

slot - The slot to search

sessionParameters - parameters which will eliminate attribute call to the HSM.

Returns:

An object with the given handle. If no objects with the given handle exist, null is returned

LocateKeyByAlias

public static LunaTokenObject LocateKeyByAlias(String alias)

Finds a key in the default slot by its alias. Unlike LocateObjectByAlias this method only matches on private and secret keys.

Parameters:

alias - The alias of the object to find

Returns:

A key with the given alias. If multiple keys exist with the same alias, the first one found is returned. If no key with the alias is found, null is returned

LocateKeyByAlias

public static LunaTokenObject LocateKeyByAlias(String alias,
                                               int slot)

Finds a persistent key in the given slot by its alias. Unlike LocateObjectByAlias this method only matches on private and secret keys.

Parameters:

alias - The alias of the key to find

slot - The slot to search

Returns:

A persistent key with the given alias. If multiple keys exist with the same alias, the first one found is returned. If no key with the alias is found, null is returned

GetHandle

public int GetHandle()

Returns the handle of the HSM object wrapped by this object.

Returns:

The handle of the HSM object wrapped by this object

GetClassAndType

public long[] GetClassAndType()

Returns the PKCS11 key class (CKO_PUBLIC_KEY, CKO_PRIVATE_KEY, etc) and type (CKK_AES, CKK_RSA, etc) for the HSM object wrapped by this object.

Returns:

The object key class and type (in that order), as two long values in an array

Throws:

LunaException - If this object is uninitialized

GetLargeAttribute

public byte[] GetLargeAttribute(long attribute)

Returns the value of the requested attribute as a byte array. This is useful for data such as large primes. The data is returned as it is stored on the HSM, so if this method is used to retrieve CK_ULONG values they will need to be converted from little-endian to big-endian in order to be interpreted properly as numbers. In that case use of the GetSmallAttribute method is preferred.

Parameters:

attribute - The PKCS11 CKA_* id of the attribute

Returns:

The attribute value as a byte array

Throws:

LunaException - If this object is uninitialized

SetLargeAttribute

public long SetLargeAttribute(long attribute,
                              byte[] value)

Sets the value of a large attribute. This is useful for data such as large primes.

Parameters:

attribute - The PKCS11 CKA_* id of the attribute

value - The value to assign to the given attribute

Returns:

The PKCS11 CKR return code

Throws:

LunaException - If this object is uninitialized

GetSmallAttribute

public long GetSmallAttribute(long attribute)

Returns the requested attribute value of the given key, interpreted as a PKCS CK_ULONG. The HSM uses 4 bytes to store a CK_ULONG, so the most-significant 4 bytes of the long returned by this method will be unused.

If the attribute being requested is not actually a CK_ULONG on the HSM, then this method will return a numerical interpretation of the first 4 bytes of the attribute.

Parameters:

attribute - The PKCS11 CKA_* id of the attribute

Returns:

The attribute value as a long value

Throws:

LunaException - If this object is uninitialized

SetSmallAttribute

public long SetSmallAttribute(long attribute,
                              long value)

Sets the value of the given attribute, as a PKCS CK_ULONG. The HSM uses 4 bytes to store a CK_ULONG, so only the least-significant 4 bytes of the data supplied to this method will be used.

Parameters:

attribute - The PKCS11 CKA_* id of the attribute

value - The value to assign to the given attribute

Returns:

The PKCS11 CKR return code of the operation

Throws:

LunaException - If this object is uninitialized

GetBooleanAttribute

public boolean GetBooleanAttribute(long attribute)

Gets the boolean value of the given attribute. If the attribute is not actually a boolean on the HSM (i.e. not a CK_BOOL attribute), then this method will return a boolean interpretation of the first byte of the attribute -- false if it is 0x00, true otherwise.

Parameters:

attribute - The PKCS11 CKA_* id of the attribute

Returns:

The PKCS11 CKR return code of the operation

Throws:

LunaException - If this object is uninitialized

SetBooleanAttribute

public long SetBooleanAttribute(long attribute,
                                boolean value)

Sets the value of the given boolean attribute.

Parameters:

attribute - The PKCS11 CKA_* id of the attribute

value - The value to assign to the given attribute

Returns:

The PKCS11 CKR return code of the operation

Throws:

LunaException - If this object is uninitialized

setUsageCount

public long setUsageCount(long value)

Sets the usage count for this object. This method is only valid on key objects; all other object types will result in an exception.

Parameters:

value - The new usage count

Returns:

The PKCS11 CKR return code of the operation

GetFingerprint

public byte[] GetFingerprint()

Returns the fingerprint of the HSM object wrapped by this object. The fingerprint is a byte array that contains a SHA-1 hash of various attributes of the object. It is exceedingly unlikely that any two objects will share a fingerprint unless the objects are true duplicates of each other.

Returns:

The fingerprint as a byte array

MakePersistent

public void MakePersistent(String alias)

If this object is currently a session object, it is persisted with the given alias. Duplicate aliases are allowed on the HSM. If this method is called on an object that is already persistent, one of two things will happen:

• If the new alias is the same as the old alias, nothing is changed
• If the new alias is different from the old alias, the object is duplicated. This instance of LunaTokenObject is changed to point to the new object on the HSM. The old object is not removed from the HSM

Parameters:

alias - The alias to assign to the HSM object

Throws:

LunaException - if the LunaTokenObject object is uninitialized, if alias is null, or if alias points to a non-existent key

LunaPartitionFullException - if the HSM partition does not have enough storage space to create the new token object

GetAlias

public String GetAlias()

Returns the alias of the HSM object wrapped by this object.

Returns:

The alias of the HSM object wrapped by this object

DestroyObject

public void DestroyObject()

Destroys the object on the HSM. This method applies to persistent (token) and non-persistent (session) objects alike.

GetDateMadePersistent

public Date GetDateMadePersistent()

Gets the date and time that the HSM object wrapped by this object was made persistent.

Returns:

A Date object representing the time that this HSM object was made persistent, or null if this object is not persistent

IsObjectPersistent

public boolean IsObjectPersistent()

Checks if the HSM object wrapped by this object is persistent.

Returns:

true if the HSM object is persistent

getSession

public LunaSession getSession()

Returns a session on the slot this HSM object lives in

Returns:

A new session on the slot of this object

Throws:

LunaException - If there are no users currently logged in to the slot of this object

getSlot

public int getSlot()

Returns the slot number of the HSM object wrapped by this object

Returns:

The slot number of the HSM object wrapped by this object