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 javax.crypto.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 java.security.KeyFactory	kf
protected LunaKey	privateKey

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
protected void	checkPublicKey(java.security.Key key, boolean lastPhase) Checks the parameters to engineDoPhase().
protected java.security.Key	engineDoPhase(java.security.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 javax.crypto.SecretKey	engineGenerateSecret(java.lang.String algorithm) Wrapper function around engineGenerateSecretWantBytes.
protected javax.crypto.SecretKey	engineGenerateSecretWantBytes(java.lang.String algorithm, boolean wantBytes) Creates the shared secret and returns it as a secret key object of the requested algorithm type.
protected void	engineInit(java.security.Key key, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random) Initializes this key agreement.
protected void	engineInit(java.security.Key key, java.security.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.
byte[]	getParameterSpec() Gets the additional information as a byte[].

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 java.security.KeyFactory kf

Constructor Detail

LunaKeyAgreementEcDh

public LunaKeyAgreementEcDh()

LunaKeyAgreementEcDh

protected LunaKeyAgreementEcDh(long kdf,
                    boolean cof)

Method Detail

getParameterSpec

public byte[] getParameterSpec()

Gets the additional information as a byte[].

Returns:

byte[] containing the additional information (AKA shared info, shared data, optional info).

engineInit

protected void engineInit(java.security.Key key,
              java.security.spec.AlgorithmParameterSpec params,
              java.security.SecureRandom random)
                   throws java.security.InvalidKeyException

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

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

params - Any additional information required for the key agreement.

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

Throws:

java.security.InvalidKeyException - If the given key is not an ECPrivateKey

engineInit

protected void engineInit(java.security.Key key,
              java.security.SecureRandom random)
                   throws java.security.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 javax.crypto.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:

java.security.InvalidKeyException - If the given key is not an ECPrivateKey

engineDoPhase

protected java.security.Key engineDoPhase(java.security.Key key,
                              boolean lastPhase)
                                   throws java.security.InvalidKeyException,
                                          java.lang.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 javax.crypto.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:

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

java.security.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 javax.crypto.SecretKey engineGenerateSecretWantBytes(java.lang.String algorithm,
                                                   boolean wantBytes)
                                                        throws java.lang.IllegalStateException,
                                                               java.security.NoSuchAlgorithmException,
                                                               java.security.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:

java.lang.IllegalStateException - If this key agreement has not been completed yet

java.security.NoSuchAlgorithmException - If the requested secret key algorithm is not available

java.security.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 java.lang.IllegalStateException

Wrapper function around engineGenerateSecretWantBytes.

Throws:

java.lang.IllegalStateException

engineGenerateSecret

protected javax.crypto.SecretKey engineGenerateSecret(java.lang.String algorithm)
                                               throws java.lang.IllegalStateException,
                                                      java.security.NoSuchAlgorithmException,
                                                      java.security.InvalidKeyException

Wrapper function around engineGenerateSecretWantBytes.

Specified by:

engineGenerateSecret in class javax.crypto.KeyAgreementSpi

Throws:

java.lang.IllegalStateException

java.security.NoSuchAlgorithmException

java.security.InvalidKeyException

checkPublicKey

protected void checkPublicKey(java.security.Key key,
                  boolean lastPhase)
                       throws java.security.InvalidKeyException,
                              java.lang.IllegalStateException

Checks the parameters to engineDoPhase().

Parameters:

key - The other party's public key

lastPhase - Must be set to true

Throws:

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

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

engineGenerateSecret

protected int engineGenerateSecret(byte[] sharedSecret,
                       int offset)
                            throws java.lang.IllegalStateException,
                                   javax.crypto.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 javax.crypto.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:

java.lang.IllegalStateException - If this key agreement has not been completed yet

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

getDerivedKeyLength

protected int getDerivedKeyLength(long algId)
                           throws java.security.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:

java.security.NoSuchAlgorithmException - If the algorithm id is not recognized