LunaTokenObject (Luna Java Security Provider API)

java.lang.Object
- com.safenetinc.luna.LunaTokenObject

```
public class LunaTokenObject
extends java.lang.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

Methods
Modifier and Type	Method and Description
`void`	`assign()` assigns this object.
`void`	`authorize(java.lang.String value, boolean override)` authorizes this object.
`void`	`cacheAuthorizedSession(LunaSession session)` caches authorized session on the slot this HSM object lives in
`static void`	`clearDeriveTemplate()` remove all elements from derive template
`void`	`deleteCachedAuthorizedSession()` delete the cached authorized session for this object
`void`	`DestroyObject()` Destroys the object on the HSM.
`java.lang.String`	`GetAlias()` Returns the alias of the HSM object wrapped by this object.
`LunaSession`	`getAuthorizedSession()`
`boolean`	`GetBooleanAttribute(long attribute)` Gets the boolean value of the given attribute.
`LunaSession`	`getCachedAuthorizedSession()` Returns a cached authorized session on the slot this HSM object lives in
`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.
`java.util.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.
`byte[]`	`GetOUID()` Returns the CKA_OUID of the object in the HSM.
`LunaSession`	`getSession()` Returns a session on the slot this HSM object lives in
`LunaSession`	`getSessionForAuthorization()` Returns a session for authorization 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.
`void`	`incrementFailedAuthCount()` increment the failed auth attempt count for this object.
`boolean`	`isInitialized()`
`boolean`	`IsObjectPersistent()` Checks if the HSM object wrapped by this object is persistent.
`static LunaTokenObject`	`LocateCertByAlias(java.lang.String alias, int slot)` Finds a persistent cert in the given slot by its alias.
`static LunaTokenObject`	`LocateKeyByAlias(java.lang.String alias)` Finds a key in the default slot by its alias.
`static LunaTokenObject`	`LocateKeyByAlias(java.lang.String alias, int slot)` Finds a persistent key in the given slot by its alias.
`static LunaTokenObject`	`LocateObjectByAlias(java.lang.String alias)` Finds a persistent object in the default slot by its alias.
`static LunaTokenObject`	`LocateObjectByAlias(java.lang.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, java.util.Map<java.lang.Long,java.lang.Object> sessionParameters)` Finds an object in the given slot by its object handle.
`static LunaTokenObject`	`LocateObjectByOUID(byte[] ouid, int slot)` Finds an object in the given slot by its CKA_OUID.
`void`	`MakePersistent(java.lang.String alias)` If this object is currently a session object, it is persisted with the given alias.
`void`	`resetAuthorizationData(java.lang.String newValue)` resets the auth data this object.
`void`	`resetAuthorizedSession()`
`void`	`setAuthorizationData(java.lang.String oldValue, java.lang.String newValue)` Sets the auth data this object.
`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(java.lang.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(java.lang.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
  - LocateCertByAlias
```
public static LunaTokenObject LocateCertByAlias(java.lang.String alias,
                                int slot)
```
    Finds a persistent cert in the given slot by its alias. If multiple certs exist with the same alias, the first one found is returned.
    
    Parameters:
    alias - The alias for the cert to find
    slot - The slot to search
    
    Returns:
    A persistent cert with the given alias. If no certs with the given alias exists, 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,
                                   java.util.Map<java.lang.Long,java.lang.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(java.lang.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(java.lang.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
  - LocateObjectByOUID
```
public static LunaTokenObject LocateObjectByOUID(byte[] ouid,
                                 int slot)
```
    Finds an object in the given slot by its CKA_OUID.
    
    Parameters:
    ouid - The ouid of the object to find
    slot - The slot to search
    
    Returns:
    An object with the given ouid. If no object with the ouid 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
  - GetOUID
```
public byte[] GetOUID()
```
    Returns the CKA_OUID of the object in the HSM.
    
    Returns:
    The OUID as a byte array
  - MakePersistent
```
public void MakePersistent(java.lang.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 java.lang.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 java.util.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
  - getSessionForAuthorization
```
public LunaSession getSessionForAuthorization()
```
    Returns a session for authorization 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
  - getAuthorizedSession
```
public LunaSession getAuthorizedSession()
```
  - resetAuthorizedSession
```
public void resetAuthorizedSession()
```
  - cacheAuthorizedSession
```
public void cacheAuthorizedSession(LunaSession session)
```
    caches authorized session on the slot this HSM object lives in
    
    Parameters:
    session - the session object to cache
    
    Throws:
    
    LunaException - If there are no users currently logged in to the slot of this object
  - getCachedAuthorizedSession
```
public LunaSession getCachedAuthorizedSession()
```
    Returns a cached authorized 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
  - deleteCachedAuthorizedSession
```
public void deleteCachedAuthorizedSession()
```
    delete the cached authorized session for 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
  - isInitialized
```
public boolean isInitialized()
```
  - setAuthorizationData
```
public void setAuthorizationData(java.lang.String oldValue,
                        java.lang.String newValue)
```
    Sets the auth data this object.
    
    Parameters:
    oldValue - old auth data
    newValue - new auth data
  - resetAuthorizationData
```
public void resetAuthorizationData(java.lang.String newValue)
```
    resets the auth data this object.
    
    Parameters:
    newValue - new auth data
  - authorize
```
public void authorize(java.lang.String value,
             boolean override)
```
    authorizes this object.
    
    Parameters:
    value - auth data
    override - get a new session from the HSM regardless as to whether we've already got one
  - assign
```
public void assign()
```
    assigns this object.
  - incrementFailedAuthCount
```
public void incrementFailedAuthCount()
```
    increment the failed auth attempt count for this object.

Class LunaTokenObject

Method Summary

Methods inherited from class java.lang.Object

Method Detail

clearDeriveTemplate

setDeriveTemplate

getDeriveTemplate

LocateObjectByAlias

LocateObjectByAlias

LocateCertByAlias

LocateObjectByFingerprint

LocateObjectByFingerprint

LocateObjectByHandle

LocateObjectByHandle

LocateObjectByHandle

LocateKeyByAlias

LocateKeyByAlias

LocateObjectByOUID

GetHandle

GetClassAndType

GetLargeAttribute

SetLargeAttribute

GetSmallAttribute

SetSmallAttribute

GetBooleanAttribute

SetBooleanAttribute

setUsageCount

GetFingerprint

GetOUID

MakePersistent

GetAlias

DestroyObject

GetDateMadePersistent

IsObjectPersistent

getSession

getSessionForAuthorization

getAuthorizedSession

resetAuthorizedSession

cacheAuthorizedSession

getCachedAuthorizedSession

deleteCachedAuthorizedSession

getSlot

isInitialized

setAuthorizationData

resetAuthorizationData

authorize

assign

incrementFailedAuthCount