com.safenetinc.luna.provider.keyagree

Class LunaKeyAgreementDh

java.lang.Object

javax.crypto.KeyAgreementSpi

com.safenetinc.luna.provider.keyagree.LunaKeyAgreementDh

public class LunaKeyAgreementDh
extends KeyAgreementSpi

This class implements a Diffie-Hellman key agreement where the private key and shared secret are stored on the Luna HSM.

Field Summary

Fields

Modifier and Type	Field and Description
protected KeyFactory	kf
protected LunaKey	privateKey

Constructor Summary

Constructors

Constructor and Description
LunaKeyAgreementDh()

Method Summary

Modifier and Type	Method and Description
protected void	checkPublicKey(Key key, boolean lastPhase) Checks the parameters to engineDoPhase().
protected Key	engineDoPhase(Key key, boolean lastPhase) Executes the next phase of this key agreement with the given key that was received from the other party involved in this key agreement.
protected byte[]	engineGenerateSecret() Generates the shared secret and returns it in a new buffer.
protected int	engineGenerateSecret(byte[] sharedSecret, int offset) Generates the shared secret, and places it into the buffer sharedSecret, beginning at offset inclusive.
protected SecretKey	engineGenerateSecret(String algorithm) Creates the shared secret and returns it as a secret key object of the requested algorithm type.
protected void	engineInit(Key key, AlgorithmParameterSpec params, SecureRandom random) Initializes this key agreement with the given key.
protected void	engineInit(Key key, SecureRandom random) Initializes this key agreement.
protected int	getDerivedKeyLength(long algId) Returns the derived key length in bytes for a key of the given algorithm.
protected int	getMaxSharedSecretLength() The maximum size of the generated key will be equal to the size of the prime, in bits.

Methods inherited from class java.lang.Object

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

Field Detail

privateKey

protected LunaKey privateKey

kf

protected final KeyFactory kf

Constructor Detail

LunaKeyAgreementDh

public LunaKeyAgreementDh()

Method Detail

engineInit

protected void engineInit(Key key,
                          SecureRandom random)
                   throws InvalidKeyException

Initializes this key agreement. The given key is required to contain all the algorithm parameters required for this key agreement.

Specified by:

engineInit in class KeyAgreementSpi

Parameters:

key - The party's private information, typically the local party's private key. If the private key does not already exist on the HSM it is injected into the HSM as a session object

random - Unused. The Luna HSM has its own source of randomness

Throws:

InvalidKeyException - If the given key is not a DHPrivateKey

engineDoPhase

protected Key engineDoPhase(Key key,
                            boolean lastPhase)
                     throws InvalidKeyException,
                            IllegalStateException

Executes the next phase of this key agreement with the given key that was received from the other party involved in this key agreement.

The Luna provider only supports two-party key exchanges, so this method can only be called once per exchange, with lastPhase set to true

Specified by:

engineDoPhase in class KeyAgreementSpi

Parameters:

key - The other party's public key

lastPhase - Must be set to true

Returns:

null; only two-party agreements are supported so there are no intermediate keys

Throws:

IllegalStateException - If this key agreement has not been initialized, or if lastPhase is false

InvalidKeyException - If the given key is not a DHPublicKey, or if it is not in the same slot as the private key that the agreement was initialized with

engineGenerateSecret

protected SecretKey engineGenerateSecret(String algorithm)
                                  throws IllegalStateException,
                                         NoSuchAlgorithmException,
                                         InvalidKeyException

Creates the shared secret and returns it as a secret key object of the requested algorithm type.

This method resets this KeyAgreement object, so that it can be reused for further key agreements. Unless this key agreement is reinitialized with one of the init methods, the same private information will be used for subsequent key agreements. However, doPhase will have to be called after every call to generateSecret in order to re-initialize the public information.

Specified by:

engineGenerateSecret in class KeyAgreementSpi

Parameters:

algorithm - The requested secret key algorithm

Returns:

The shared secret key

Throws:

IllegalStateException - If this key agreement has not been completed yet

NoSuchAlgorithmException - If the requested secret key algorithm is not available

InvalidKeyException - If the key material is too short to generate the requested secret key

getMaxSharedSecretLength

protected int getMaxSharedSecretLength()

The maximum size of the generated key will be equal to the size of the prime, in bits.

Returns:

The DH key size, in bits

engineInit

protected void engineInit(Key key,
                          AlgorithmParameterSpec params,
                          SecureRandom random)
                   throws InvalidKeyException,
                          InvalidAlgorithmParameterException

Initializes this key agreement with the given key.

Specified by:

engineInit in class KeyAgreementSpi

Parameters:

key - The party's private information, typically the local party's private key

params - Any additional information required for the key agreement.

random - Unused. The Luna HSM has its own source of randomness

Throws:

InvalidKeyException - If the given key is of the wrong type for this key agreement or has an incompatible algorithm type

InvalidAlgorithmParameterException

checkPublicKey

protected void checkPublicKey(Key key,
                              boolean lastPhase)
                       throws InvalidKeyException,
                              IllegalStateException

Checks the parameters to engineDoPhase().

Parameters:

key - The other party's public key

lastPhase - Must be set to true

Throws:

IllegalStateException - If this key agreement has not been initialized, or if lastPhase is false

InvalidKeyException - If the pubic key's slot doesn't match the private key's slot

engineGenerateSecret

protected byte[] engineGenerateSecret()
                               throws IllegalStateException

Generates the shared secret and returns it in a new buffer. This method will only return the actual shared secret if LunaSlotManager. setExtractableKeys(true) has been set. If LunaSlotManager is set to create non-extractable keys, the shared secret will remain on the HSM. In this case an encoded version of the key handle is returned.

This method resets this KeyAgreement object, so that it can be reused for further key agreements. Unless this key agreement is reinitialized with one of the init methods, the same private information will be used for subsequent key agreements. However, doPhase will have to be called after every call to generateSecret in order to re-initialize the public information.

Specified by:

engineGenerateSecret in class KeyAgreementSpi

Throws:

IllegalStateException

engineGenerateSecret

protected int engineGenerateSecret(byte[] sharedSecret,
                                   int offset)
                            throws IllegalStateException,
                                   ShortBufferException

Generates the shared secret, and places it into the buffer sharedSecret, beginning at offset inclusive.

If the sharedSecret buffer is too small to hold the result, a ShortBufferException is thrown. In this case, the key agreement is not reset and the call can be repeated with a larger output buffer.

Successful completion of this method resets this KeyAgreement object, so that it can be reused for further key agreements. Unless this key agreement is reinitialized with one of the init methods, the same private information will be used for subsequent key agreements. However, doPhase will have to be called after every call to generateSecret in order to re-initialize the public information.

Specified by:

engineGenerateSecret in class KeyAgreementSpi

Parameters:

sharedSecret - The buffer for the shared secret

offset - The offset in sharedSecret where the shared secret will be stored

Returns:

The number of bytes places into sharedSecret

Throws:

IllegalStateException - If this key agreement has not been completed yet

ShortBufferException - If the given output buffer is too small to hold the secret

getDerivedKeyLength

protected int getDerivedKeyLength(long algId)
                           throws NoSuchAlgorithmException

Returns the derived key length in bytes for a key of the given algorithm. A "generic secret" key will have the same length as the DH/ECDH keys used to create it.

Parameters:

algId - Algorithm of the secret key

Returns:

Length of the secret key, in bytes

Throws:

NoSuchAlgorithmException - If the algorithm id is not recognized