com.safenetinc.luna.provider.keyagree

Class LunaKeyAgreementEcDh

java.lang.Object

javax.crypto.KeyAgreementSpi

com.safenetinc.luna.provider.keyagree.LunaKeyAgreementEcDh

Direct Known Subclasses:

LunaKeyAgreementEcDhC, LunaKeyAgreementEcDhCWithKdf1, LunaKeyAgreementEcDhCWithKdf224, LunaKeyAgreementEcDhCWithKdf256, LunaKeyAgreementEcDhCWithKdf384, LunaKeyAgreementEcDhCWithKdf512, LunaKeyAgreementEcDhWithKdf1, LunaKeyAgreementEcDhWithKdf224, LunaKeyAgreementEcDhWithKdf256, LunaKeyAgreementEcDhWithKdf384, LunaKeyAgreementEcDhWithKdf512, LunaKeyAgreementEcDhWithNistKdf256

public class LunaKeyAgreementEcDh
extends KeyAgreementSpi

This class implements an Elliptic Curve 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

Modifier	Constructor and Description
	LunaKeyAgreementEcDh()
protected	LunaKeyAgreementEcDh(long kdf, boolean cof)

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() Wrapper function around engineGenerateSecretWantBytes.
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) Wrapper function around engineGenerateSecretWantBytes.
protected SecretKey	engineGenerateSecretWantBytes(String algorithm, boolean wantBytes) 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 key size is the maximum size of key that this curve can generate, 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

LunaKeyAgreementEcDh

public LunaKeyAgreementEcDh()

LunaKeyAgreementEcDh

protected LunaKeyAgreementEcDh(long kdf,
                               boolean cof)

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 an ECPrivateKey

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 an ECPublicKey, or if it is not in the same slot as the private key that the agreement was initialized with

engineGenerateSecretWantBytes

protected SecretKey engineGenerateSecretWantBytes(String algorithm,
                                                  boolean wantBytes)
                                           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.

Parameters:

algorithm - The requested secret key algorithm

wantBytes - A hint that the caller just wants the key bytes

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 key size is the maximum size of key that this curve can generate, in bits. This is equal to the field size.

Returns:

The ECDH key size, in bits

engineGenerateSecret

protected byte[] engineGenerateSecret()
                               throws IllegalStateException

Wrapper function around engineGenerateSecretWantBytes.

Throws:

IllegalStateException

engineGenerateSecret

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

Wrapper function around engineGenerateSecretWantBytes.

Specified by:

engineGenerateSecret in class KeyAgreementSpi

Throws:

IllegalStateException

NoSuchAlgorithmException

InvalidKeyException

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 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