public class LunaKey extends Object implements Key
LunaKey objects can be created through KeyGenerator and KeyPairGenerator objects making use of the "LunaProvider" provider. Alternately, they can be created to represent keys already stored on the hardware, using a KeyStore (type "Luna") or the LocateKeyByAlias() method.
Modifier and Type | Field and Description |
---|---|
protected int |
keySize
Size of the token key, in bits.
|
protected static LunaAPI |
lapi |
protected long |
mKeyClass |
protected long |
mKeyType |
protected LunaTokenObject |
mObject |
static int |
UNLIMITED_USE
Use this value with
setUsageLimit to enable usage counting for
this key without actually asserting a limit on the use. |
protected static byte[] |
WRAP_IV |
Modifier | Constructor and Description |
---|---|
protected |
LunaKey()
Creates an uninitialized LunaKey object.
|
|
LunaKey(int hKey)
Create a LunaKey object from the key stored in the default slot
with the given handle.
|
|
LunaKey(int hKey,
int slot)
Create a LunaKey object from the key stored in the specified slot
with the given handle.
|
protected |
LunaKey(int hKey,
int slot,
long keyClass,
long keyType)
Create a LunaKey object from the key stored in the specified slot
with the given handle.
|
protected |
LunaKey(int hKey,
int slot,
Map<Long,Object> sessionParameters)
Create a LunaKey object from the key stored in the specified slot
with the given handle.
|
|
LunaKey(LunaTokenObject object)
Create a LunaKey object from the key stored on the Luna hardware.
|
Modifier and Type | Method and Description |
---|---|
static BigInteger |
AttributeToBigInteger(byte[] in)
Turn an integer attribute (such as CKA_MODULUS) into a BigInteger.
|
static byte[] |
BigIntegerToAttribute(BigInteger b)
Converts a big integer into a byte array suitable for use
as a token object attribute.
|
void |
DestroyKey()
Destroys the key completely, including removing it from the hardware.
|
boolean |
equals(Object obj)
Check for equivalence between this LunaKey object and the object that's
passed in.
|
String |
getAlgorithm()
Returns a String representation of the key algorithm
|
String |
GetAlias()
Returns the alias of the LunaKey object.
|
Date |
GetDateMadePersistent()
Returns the date that the LunaKey was made persistent.
|
byte[] |
getEncoded()
Returns the encoded form of the LunaKey object.
|
protected byte[] |
getEncodedInternal() |
byte[] |
GetFingerprint()
Returns a fingerprint of an object (a byte array that contains a
cryptographic hash of various attributes of the object).
|
String |
getFormat()
Returns the name of the format used to encode the LunaKey object.
|
long |
GetKeyClass()
Returns the PKCS11 object class of the key.
|
int |
GetKeyHandle()
Returns the handle of the key stored in hardware.
|
int |
getKeySize()
Returns the size of the key wrapped by this LunaKey, in bits.
|
static long |
GetKeyType(String algorithm)
Returns the key type identifier for the given algorithm
|
LunaSession |
getSession()
Returns a new LunaSession on same slot as this key.
|
int |
getSlot()
Returns the slot the key is stored in.
|
int |
getUsageCount()
Get the number of times this key has been used.
|
int |
getUsageLimit()
Get the usage limit set on this on this key.
|
int |
hashCode()
Two Keys are considered equal if their encoded forms match, so we simply
return the hash code of the encoded bytes.
|
protected void |
Initialize(int hKey,
int slot,
long keyClass,
long keyType)
Initialize a LunaKey object with the given data.
|
protected void |
Initialize(int hKey,
int slot,
Map<Long,Object> sessionParameters)
Initialize a LunaKey object with the given data.
|
protected static int |
injectKey(byte[] keyBytes,
long keyAlg,
long keyType,
int slot,
boolean extractable,
boolean derive) |
static PrivateKey |
InjectPrivateKey(byte[] encodedKey,
long algId)
Injects the given encoded private key of the specified algorithm
type into the token at the default slot.
|
static PrivateKey |
InjectPrivateKey(byte[] encodedKey,
long algId,
int slot)
Injects the given encoded private key of the specified algorithm
type into the token at the specified slot.
|
static PrivateKey |
InjectPrivateKey(PrivateKey key)
Inject (encrypt encoded key and unwrap) a non-Luna private key into
the token at the default slot.
|
static PrivateKey |
InjectPrivateKey(PrivateKey key,
int slot)
Inject (encrypt encoded key and unwrap) a non-Luna private key into
the token at the specified slot.
|
boolean |
IsKeyPersistent()
Returns a boolean indicating whether or not the given LunaKey object
is persistent.
|
static LunaKey |
LocateKeyByAlias(String alias)
Locate a persisted key on the default slot using the alias assigned
when MakePersistant() was invoked.
|
static LunaKey |
LocateKeyByAlias(String alias,
int slot)
Locate a persisted key on the specified slot using the alias assigned
when MakePersistant() was invoked.
|
static LunaKey |
LocateKeyByFingerprint(byte[] fingerprint)
Locate a persisted key on the default slot using the key's fingerprint.
|
static LunaKey |
LocateKeyByFingerprint(byte[] fingerprint,
int slot)
Locate a persisted key on the specified slot using the key's fingerprint.
|
static LunaKey |
LocateKeyByHandle(int handle)
Locate a persisted key on the default slot using the handle assigned
when MakePersistant() was invoked.
|
static LunaKey |
LocateKeyByHandle(int handle,
int slot)
Locate a persisted key on the specified slot using the handle assigned
when MakePersistent() was invoked.
|
static LunaKey |
LocateKeyOnlyByAlias(String alias)
Locate a persisted key on the default slot using the alias assigned
when MakePersistant() was invoked.
|
static LunaKey |
LocateKeyOnlyByAlias(String alias,
int slot)
Locate a persisted key on the specified slot using the alias assigned
when MakePersistant() was invoked.
|
void |
MakePersistent(String alias)
The MakePersistent() method can be used to ensure that a key that has
been generated will continue to exist from one instance of an application
to another.
|
void |
release()
This method is used to signal to the Luna provider that an application
is finished with a session (temporary) object on the HSM.
|
protected void |
setKeySize()
Sets the size of the key we're wrapping, in bits.
|
boolean |
setUsageCount(int count)
Set the usage count on this key.
|
boolean |
setUsageLimit(int limit)
Set the usage limit on this key.
|
String |
toString()
Returns a string representation of the key object.
|
protected void |
verifyClassAndType()
Checks that the existing object handle being wrapped by this LunaKey
objects has the key class and key type expected by the LunaKey subclass.
|
protected static final byte[] WRAP_IV
protected static final LunaAPI lapi
protected transient LunaTokenObject mObject
protected long mKeyClass
protected long mKeyType
protected int keySize
public static final int UNLIMITED_USE
setUsageLimit
to enable usage counting for
this key without actually asserting a limit on the use. By default key usage
is not counted.protected LunaKey()
public LunaKey(int hKey)
hKey
- The handle of the key stored in hardware.public LunaKey(int hKey, int slot)
hKey
- The handle of the key stored in hardware.slot
- The slot the key is stored inprotected LunaKey(int hKey, int slot, long keyClass, long keyType)
hKey
- The handle of the key stored in hardware.slot
- The slot the key is stored inkeyClass
- the PKCS class of the keykeyType
- the PKCS type of the keyprotected LunaKey(int hKey, int slot, Map<Long,Object> sessionParameters)
hKey
- The handle of the key stored in hardware.slot
- The slot the key is stored insessionParameters
- session parameters which will avoid an attribute call to the hsm.public LunaKey(LunaTokenObject object)
object
- The LunaTokenObject corresponding to the key in hardware.protected void Initialize(int hKey, int slot, long keyClass, long keyType)
hKey
- the key's handle on the HSMslot
- the slot the key resides inkeyClass
- the PKCS class of the keykeyType
- the PKCS type of the keyprotected void Initialize(int hKey, int slot, Map<Long,Object> sessionParameters)
hKey
- the key's handle on the HSMslot
- the slot the key resides insessionParameters
- the (session or token) indicator, PKCS class, type and length of the keyprotected void verifyClassAndType()
LunaException
- if there is a mismatchprotected void setKeySize()
public int getKeySize()
public int GetKeyHandle()
public LunaSession getSession()
public int getSlot()
public byte[] GetFingerprint()
public long GetKeyClass()
public String toString()
public void MakePersistent(String alias)
The same alias can be assigned to both a public and a private key. If the same alias is assigned to two public or two private keys, an exception is thrown.
If a key is not made persistent after it is generated, it will disappear from the token when the application terminates.
alias
- The alias to assign to the key.public Date GetDateMadePersistent()
public void DestroyKey()
public String getAlgorithm()
getAlgorithm
in interface Key
public String getFormat()
This will be one of
public byte[] getEncoded()
getEncoded
in interface Key
protected byte[] getEncodedInternal()
public boolean equals(Object obj)
This method compares the two keys by getting their encoded form, so it would compare this key's:
The second case, where we compare the encoded handle, would not work out when the comparison's done against a software key. Since we can't extract the field values from the hardware, there's no real solution to this problem.
public int hashCode()
public String GetAlias()
public boolean IsKeyPersistent()
public void release()
Two processes A and B share the same PKCS application id. Process A creates a session key. Process B can get a reference to this key by using the LunaKey(handle) constructor. When B is finished with the object it shouldn't delete it since A might still need it. It shouldn't let it just go out of scope either since when it gets GC'd, B's SessionObjectAuditor will delete the object on the HSM. B should call release() first on the key to avoid this latter situation.
Programming note: sharing session objects across processes is not a
standard use of the Luna provider and may cause strange behaviour unless
you are very careful about what you are doing. In almost all cases
it is better to persist a key on the HSM with MakePersistent()
before using it outside the originating process.
public static byte[] BigIntegerToAttribute(BigInteger b)
Since BigIntegers are signed, they use the upper bit for the sign. If an unsigned value with the upper bit set is converted to a BigInteger, the BigInteger will have an extra zero added. This routine removes that extra zero if necessary.
b
- the BigInteger to convertb
public static BigInteger AttributeToBigInteger(byte[] in)
in
- the encoded attribute to convertin
public static long GetKeyType(String algorithm) throws ProviderException
algorithm
- A string containing the name of the key algorithmProviderException
public static PrivateKey InjectPrivateKey(byte[] encodedKey, long algId) throws InvalidKeyException
encodedKey
- The PKCS-8 encoded private keyalgId
- The algorithm type of the keyInvalidKeyException
- exceptionpublic static PrivateKey InjectPrivateKey(byte[] encodedKey, long algId, int slot) throws InvalidKeyException
encodedKey
- The PKCS-8 encoded private keyalgId
- The algorithm type of the keyslot
- The slot of the token to inject the key intoInvalidKeyException
- exceptionpublic static PrivateKey InjectPrivateKey(PrivateKey key) throws InvalidKeyException
key
- The non-Luna key objectInvalidKeyException
- exceptionpublic static PrivateKey InjectPrivateKey(PrivateKey key, int slot) throws InvalidKeyException
key
- The non-Luna key objectslot
- The slot of the token to inject the key intoInvalidKeyException
- If the key is not encoded in PKCS8 format,
or if it is an ECC key on an unsupported named curveprotected static int injectKey(byte[] keyBytes, long keyAlg, long keyType, int slot, boolean extractable, boolean derive)
public boolean setUsageLimit(int limit)
limit
- The maximum number of times this key may be used. This number
cannot be less than zero.public int getUsageLimit()
LunaException
- if there is no limit set on this keypublic boolean setUsageCount(int count)
count
- The new usage count of the key. This number cannot be
less than zero.public int getUsageCount()
LunaException
- if the count isn't being tracked (i.e. there is
no usage limit specified for this key)public static LunaKey LocateKeyByAlias(String alias)
alias
- The alias of the key to retrievepublic static LunaKey LocateKeyByAlias(String alias, int slot)
alias
- The alias of the key to retrieveslot
- The slot to searchpublic static LunaKey LocateKeyByFingerprint(byte[] fingerprint)
fingerprint
- The fingerprint of the key to retrievepublic static LunaKey LocateKeyByFingerprint(byte[] fingerprint, int slot)
fingerprint
- The fingerprint of the key to retrieveslot
- The slot to searchpublic static LunaKey LocateKeyOnlyByAlias(String alias)
alias
- The alias of the key to retrievepublic static LunaKey LocateKeyOnlyByAlias(String alias, int slot)
alias
- The alias of the key to retrieveslot
- The slot to searchpublic static LunaKey LocateKeyByHandle(int handle)
This method should not be used to look up a session (non-persisted) key that was created by another Java process. Doing so may make the key unavailable at an unexpected time in this process or the originating process. If you need to share keys between processes, persist them first.
handle
- The handle of the key to retrievepublic static LunaKey LocateKeyByHandle(int handle, int slot)
This method should not be used to look up a session (non-persisted) key that was created by another Java process. Doing so may make the key unavailable at an unexpected time in this process or the originating process. If you need to share keys between processes, persist them first.
handle
- The handle of the key to retrieveslot
- The slot to searchCopyright 2014-2016 SafeNet Inc