com.safenetinc.luna

Class LunaSlotManager

java.lang.Object

com.safenetinc.luna.LunaSlotManager

public final class LunaSlotManager
extends Object

This class is used to manage access to Gemalto SafeNet Luna hardware security modules (HSMs). It handles logins, logouts, session and slot management for all available slots(HSM partitions).

The JCA API is not adequate for dealing with all the interfaces available with Luna HSMs. LunaSlotManager methods provide additional proprietary and custom functionality where necessary.

When the application starts up, LunaSlotManager attempts to find already-logged-in slots. If any are detected, it sets up the login state internally so the user doesn't have to log in again. These initial logged-in slots could be authenticated as SECURITY_OFFICER(RW only) or CRYPTO_USER(RW or RO).

If a login was done external to LunaSlotManager with a non- default application id, setApplicationId should be used to set LunaSlotManager's application id to that value. This means that this application does not need to login as the application ID establishes an application context for all applications accessing the HSM partition with the given application ID.

The first logged-in slot is used as the default slot for all crypto operations where a slot is not explicitly specified (this includes all JCA/JCE crypto operations). This default can be changed with setDefaultSlot if more slots are logged in to later. If the default slot is changed while the application is running, the value will change across all threads. ALthough the operation of changing the default slot is thread-safe, one should not do this unless all on the fly operations are complete so as to not get confusing results.

Method Summary

Modifier and Type	Method and Description
boolean	areSecretKeysExtractable() Checks if newly-generated secret keys are extractable.
void	clrReconnectRequired() Clear the reinit flag in LunaSlotManager
void	detectTokenConnectionProblem(int slot) Check for token presence but, unlike isTokenPresent, throw an exception if there is no token as we know there should be one.
void	disableReconnect()
void	enableReconnect()
int	findSlotFromLabel(String tokenLabel) Searches the currently present slots for one with a label matching the one we're given.
int	getCurrentObjectCount() Returns the current persistent object count for the token at the current default slot.
int	getCurrentObjectCount(int slot) Returns the current persistent object count for the token at the specified slot.
int	getCurrentTotalObjectCount() Returns the current persistent object count all logged-in tokens.
int	getDefaultSlot() Gets the current default slot number.
LunaHAStatus	getHAStatus() Gets the HA Status for the default slot.
LunaHAStatus	getHAStatus(int slot) Gets the HA Status for the specified slot.
static LunaSlotManager	getInstance() Returns the only instance of the singleton LunaSlotManager class.
LunaAPI	getLunaAPI() Returns a reference to the LunaAPI object.
int	getNumberOfSlots() Determines how many slots are present in the system.
boolean	getReconnectEnabled() Get the reconnect enabled flag in LunaSlotManager
boolean	getReconnectRequired() Get the reinit flag in LunaSlotManager
int[]	getSlotList() Returns a list of slots that have tokens present.
Long[]	getTokenFirmwareVersion(int slot) Reads the serial number of the token contained in the given slot.
String	getTokenLabel(int slot) Reads the label of the token contained in the given slot.
String	getTokenSerialNumber(int slot) Reads the serial number of the token contained in the given slot.
byte[]	getWrappingKeyBytesToo(int slot) Returns wrapping key bytes for DeriveKeyAndWrapEcDh feature.
int	getWrappingKeyHandle(int slot) Returns the handle for the wrapping key for a given slot.
int	getWrappingKeyHandleToo(int slot) Returns the wrapping key handle for DeriveKeyAndWrapEcDh feature.
boolean	isAttributeCachingEnabled() Checks if PKCS attribute caching is enabled.
boolean	isFIPSEnabled() Returns the FIPS-enabled status of the provider, as shown below.
boolean	isLoggedIn() Checks if the application is logged in to at least one token.
boolean	isShuttingDown() Return true if the application's shutdown hook has been called, false otherwise.
boolean	isTokenPresent(int slot) Tests a slot to see if a token is present at the given slot.
void	logExternal(int slot, String logMsg) Sends a log message to the token at the specified slot.
void	logExternal(String logMsg) Sends a log message to the token at the specified slot.
boolean	login(int slot, String password) Logs in to a slot as a normal user role with the specified password.
boolean	login(int slot, UserRole userType, String password) Logs in to a slot with the specified user role and password.
int	login(String password) Logs in to the current default slot as a normal user, using the given password.
boolean	login(String tokenLabel, String password) Logs in to the token with the given label as a normal user, with the given password.
void	logout() Logs out from the current default slot.
void	logout(int slotNum) Logs out from the specified slot.
boolean	querySecretKeysDeriveFlag() Checks if newly-generated secret keys can derive other keys.
void	reinitialize() Re-initializes the connection to the HSM.
void	releaseKey(LunaTokenObject lto) Releases a reference to a session key.
void	setApplicationId(int majorId, int minorId) Sets the major and minor application IDs.
void	setAttributeCaching(boolean enabled) Enables or disables attribute caching.
boolean	setDefaultSlot(int slotNum) Sets the default slot to the given slot.
void	setReconnectRequired(long rc) Set the reinit flag in LunaSlotManager iff required
void	setSecretKeysDeriveFlag(boolean deriveFlag) Determines whether newly-generated secret keys will be created with the derive flag set.
void	setSecretKeysExtractable(boolean extractable) Determines whether newly-generated secret keys will be created with the extractable flag set.
void	setThreadLocalDefaultSlot(boolean threadLocal) Determines if the default slot will be global or thread-local.
void	setTokenObjectType(boolean aInTokenObjectType)

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static LunaSlotManager getInstance()

Returns the only instance of the singleton LunaSlotManager class.

Returns:

A reference to the LunaSlotManager object.

getLunaAPI

public LunaAPI getLunaAPI()

Returns a reference to the LunaAPI object. Generally this should not be used by user applications.

Returns:

The LunaAPI object

getDefaultSlot

public int getDefaultSlot()

Gets the current default slot number. This slot will be used by the Java crypto provider implementation, as there is no way to specify a specific slot to in the provider API.

Returns:

The slot number of the currently active slot. If there is no logged in slot, returns -1

enableReconnect

public void enableReconnect()

disableReconnect

public void disableReconnect()

getReconnectEnabled

public boolean getReconnectEnabled()

Get the reconnect enabled flag in LunaSlotManager

Returns:

is the reconnect flag enabled or not

setReconnectRequired

public void setReconnectRequired(long rc)

Set the reinit flag in LunaSlotManager iff required

Parameters:

rc - return code from cryptoki lib

getReconnectRequired

public boolean getReconnectRequired()

Get the reinit flag in LunaSlotManager

Returns:

is a connect re-attempt needed

clrReconnectRequired

public void clrReconnectRequired()

Clear the reinit flag in LunaSlotManager

setDefaultSlot

public boolean setDefaultSlot(int slotNum)

Sets the default slot to the given slot. If thread-local default slots are enabled, this default slot value is only valid for the thread that calls this method. If they are disabled, the default slot set here will take effect globally.

Parameters:

slotNum - The slot to make the default. This must be a logged-in slot

Returns:

true if the default slot was changed, false otherwise

isFIPSEnabled

public boolean isFIPSEnabled()

Returns the FIPS-enabled status of the provider, as shown below.

Returns:

true if the provider is in FIPS mode false if the provider is in non-FIPS mode

areSecretKeysExtractable

public boolean areSecretKeysExtractable()

Checks if newly-generated secret keys are extractable. A value of true does not imply that all secret keys are extractable, only that any secret keys generated by the Luna provider from this point on will have the extractable flag set.

The default value is false.

Returns:

true If secret keys will be generated with the extractable flag set to true

setSecretKeysExtractable

public void setSecretKeysExtractable(boolean extractable)

Determines whether newly-generated secret keys will be created with the extractable flag set. If a key is not extractable, it cannot be wrapped off the token. Using this method will override the default configuration.

Parameters:

extractable - The extractable setting.

querySecretKeysDeriveFlag

public boolean querySecretKeysDeriveFlag()

Checks if newly-generated secret keys can derive other keys. Any secret keys generated by the Luna provider from this point on will have the derive flag set.

The default value is false.

Returns:

true If secret keys will be generated with the derive flag set to true

setSecretKeysDeriveFlag

public void setSecretKeysDeriveFlag(boolean deriveFlag)

Determines whether newly-generated secret keys will be created with the derive flag set.

Parameters:

deriveFlag - The derive setting.

isAttributeCachingEnabled

public boolean isAttributeCachingEnabled()

Checks if PKCS attribute caching is enabled. If it is enabled, the provider will cache PKCS attributes for each object as they are read, and will use that cache for future reads. If it is disabled, the provider will go to the HSM for every attribute read.

The caching behaviour for provider objects is dynamic. If this attribute is changed from true to false, all existing provider objects will access the HSM directly for their next attribute read. Note: in this scenario objects will clear their entire cache the first time an attribute is requested after this setting has been changed.

Caching is enabled by default to enhance performance. To ensure data consistency, it should be disabled if another application is accessing the same HSM objects, or if LunaAPI is being used to manipulate the objects directly.

Returns:

true if attribute caching is enabled, false otherwise

setAttributeCaching

public void setAttributeCaching(boolean enabled)

Enables or disables attribute caching. See isAttributeCachingEnabled for more discussion of the consequences.

Attribute caching is enabled by default.

Parameters:

enabled - the new value of the attribute caching parameter

setThreadLocalDefaultSlot

public void setThreadLocalDefaultSlot(boolean threadLocal)

Determines if the default slot will be global or thread-local.

If thread-local default slots are enabled while there are multiple threads, the default slot for each thread is initially set to the value of the global default slot at that time. If thread-local default slots are disabled while the application is running, the last slot set using setDefaultSlot will become the global default slot.

Parameters:

threadLocal - If true, the default slot will be thread-local. If false, the default slot will be global.

isShuttingDown

public boolean isShuttingDown()

Return true if the application's shutdown hook has been called, false otherwise. If the application is shutting down, the connection to the HSM is about to die. Various LunaAPI calls may fail if this connection is dead.

Returns:

true if the application's shutdown hook has been called

getWrappingKeyHandle

public int getWrappingKeyHandle(int slot)

Returns the handle for the wrapping key for a given slot. This key is used internally to inject keys into the HSM and to extract secret keys from the HSM. This key is a session object that is regenerated after every new login to the slot.

This method is for internal use only.

Parameters:

slot - the slot to get the wrapping key for

Returns:

the handle of the wrapping key, or -1 if none could be obtained

getWrappingKeyHandleToo

public int getWrappingKeyHandleToo(int slot)

Returns the wrapping key handle for DeriveKeyAndWrapEcDh feature. If the key doesn't exist then generate it (synchronized to avoid race condition).

Parameters:

slot - desired slot number

Returns:

the handle of the cached wrapping key, otherwise -1.

getWrappingKeyBytesToo

public byte[] getWrappingKeyBytesToo(int slot)

Returns wrapping key bytes for DeriveKeyAndWrapEcDh feature. Normally, the method getWrappingKeyHandleToo() is called first to extract the bytes.

Parameters:

slot - desired slot number

Returns:

the key bytes.

getCurrentObjectCount

public int getCurrentObjectCount(int slot)
                          throws LunaException

Returns the current persistent object count for the token at the specified slot.

Parameters:

slot - The slot to check

Returns:

The number of persistent objects at the specified slot

Throws:

LunaException - If the slot is uninitialized

getCurrentObjectCount

public int getCurrentObjectCount()
                          throws LunaException

Returns the current persistent object count for the token at the current default slot.

Returns:

The number of persistent objects at the default slot

Throws:

LunaException - If there is no default slot

logExternal

public void logExternal(int slot,
                        String logMsg)
                 throws LunaException

Sends a log message to the token at the specified slot.

Parameters:

slot - The slot to send the log msg to

logMsg - log msg string

Throws:

LunaException - If the slot is uninitialized

logExternal

public void logExternal(String logMsg)
                 throws LunaException

Sends a log message to the token at the specified slot.

Parameters:

logMsg - log msg string

Throws:

LunaException - If there is no default slot

detectTokenConnectionProblem

public void detectTokenConnectionProblem(int slot)

Check for token presence but, unlike isTokenPresent, throw an exception if there is no token as we know there should be one.

Parameters:

slot - slot number

setTokenObjectType

public void setTokenObjectType(boolean aInTokenObjectType)

Parameters:

aInTokenObjectType - 1 for token object, 0 for session object

getCurrentTotalObjectCount

public int getCurrentTotalObjectCount()

Returns the current persistent object count all logged-in tokens.

Returns:

The total number of persistent objects available to the application

getNumberOfSlots

public int getNumberOfSlots()

Determines how many slots are present in the system. These slots do not necessarily have tokens present.

Returns:

The number of slots

getSlotList

public int[] getSlotList()

Returns a list of slots that have tokens present.

Returns:

A list of slot numbers that have a token present

isTokenPresent

public boolean isTokenPresent(int slot)

Tests a slot to see if a token is present at the given slot.

Parameters:

slot - The number of the slot to test

Returns:

true if a token is present in the slot

getTokenLabel

public String getTokenLabel(int slot)
                     throws LunaCryptokiException

Reads the label of the token contained in the given slot.

Parameters:

slot - The slot of the token to read

Returns:

The label of the token in the given slot

Throws:

LunaCryptokiException - If there is no token at that slot

getTokenSerialNumber

public String getTokenSerialNumber(int slot)
                            throws LunaCryptokiException

Reads the serial number of the token contained in the given slot.

Parameters:

slot - The slot of the token to read

Returns:

The serial number of the token in the given slot

Throws:

LunaCryptokiException - If there is no token at that slot

getTokenFirmwareVersion

public Long[] getTokenFirmwareVersion(int slot)
                               throws LunaCryptokiException

Reads the serial number of the token contained in the given slot.

Parameters:

slot - The slot of the token to read

Returns:

The firmware version of the token in the given slot

Throws:

LunaCryptokiException - If there is no token at that slot

setApplicationId

public void setApplicationId(int majorId,
                             int minorId)

Sets the major and minor application IDs.

Parameters:

majorId - The major application ID

minorId - The minor application ID

getHAStatus

public LunaHAStatus getHAStatus(int slot)

Gets the HA Status for the specified slot. This method will not return anything meaningful if the slot is not an HA slot.

Parameters:

slot - The slot to check the HA status on

Returns:

A LunaHAStatus object containing the status information

getHAStatus

public LunaHAStatus getHAStatus()

Gets the HA Status for the default slot. This method will not return anything meaningful if the slot is not an HA slot.

Returns:

A LunaHAStatus object containing the status information

isLoggedIn

public boolean isLoggedIn()

Checks if the application is logged in to at least one token.

This method only checks slots that were already logged in when the application was started, and slots that have been logged in to by this application.

Returns:

true If the application is logged in to at least one token

releaseKey

public void releaseKey(LunaTokenObject lto)

Releases a reference to a session key. This is for internal use only; see LunaKey.release() for the public API.

Parameters:

lto - the session key to release

login

public boolean login(int slot,
                     UserRole userType,
                     String password)

Logs in to a slot with the specified user role and password.

Slots are enumerated starting from 1 (e.g. a system with four slots would have slots numbered '1', '2', '3' and '4').

If an application attempts to use a Luna HSM without explicitly logging in, the Luna provider will attempt to find a token which is already logged in. If no such token exists, an exception will be thrown.

Parameters:

slot - The slot containing the token to log in to

userType - The type of user logging in

password - The password to use for login. If the given slot contains a token which requires use of the PED for PIN entry, the password parameter is ignored.

Returns:

login success or failure

login

public boolean login(int slot,
                     String password)

Logs in to a slot as a normal user role with the specified password.

Parameters:

slot - The slot containing the token to log in to

password - The password to use for login. If the given slot contains a token which requires use of the PED for PIN entry, the password parameter is ignored.

Returns:

true if the login succeeded

login

public int login(String password)

Logs in to the current default slot as a normal user, using the given password. If there is no default slot, we try the first token we encounter. This method should only be used if there is only one token present on the system.

Parameters:

password - The password to use for the login.

Returns:

The slot logged in to

login

public boolean login(String tokenLabel,
                     String password)

Logs in to the token with the given label as a normal user, with the given password.

Parameters:

tokenLabel - The label of the token to which to login

password - The password to use for the login

Returns:

true if the login succeeds, or false if there is no token with the given label

Throws:

LunaException - if the given password is incorrect

findSlotFromLabel

public int findSlotFromLabel(String tokenLabel)

Searches the currently present slots for one with a label matching the one we're given.

Parameters:

tokenLabel - The token label to search for

Returns:

The slot number of the matching token, or -1 if no matching slot is found

logout

public void logout()

Logs out from the current default slot. All open sessions on this slot will be closed. All threads within the current application are affected by this call (i.e. the login state applies to the entire application).

logout

public void logout(int slotNum)

Logs out from the specified slot. All open sessions on this slot will be closed. All threads within the current application are affected by this call (i.e. login state applies to the entire application).

Parameters:

slotNum - The slot to log out of

reinitialize

public void reinitialize()

Re-initializes the connection to the HSM. This method can be used if the NTLS connection is broken (due to a network timeout, for example).

This operation has consequences to be aware of:

• Re-initializing the connection will kill all existing sessions, so all session objects will be lost.
• Because of the above, any Java crypto objects generated by the Luna provider that referred to session objects on the HSM will be invalidated. After the re-init they will throw LunaException for most common operations.
• The PKCS11 spec says that any operations in progress when the library is finalized will have "undefined" behaviour. In practice this could mean an application crash. Having said that though, a JVM crash is *never* considered by rational people to be an acceptable error path. On this note then, it is highly recommended that all application threads are allowed to complete their current operation before calling reinitialize()
• If the application was working against an HA slot when reinitialize() was called then the object handles of token objects may change, due to the fact that the HA library uses a virtual handle table. In this case best practice would be to let all Java crypto objects that refer to token objects on the HSM be garbage collected before calling reinitialize().