Package javacard.security

Class KeyAgreement

java.lang.Object

javacard.security.KeyAgreement

public abstract class KeyAgreement
extends Object

The KeyAgreement class is the base class for key agreement algorithms such as Diffie-Hellman and EC Diffie-Hellman [IEEE P1363]. Implementations of KeyAgreement algorithms must extend this class and implement all the abstract methods. A tear or card reset event resets an initialized KeyAgreement object to the state it was in when previously initialized via a call to init().

Field Summary

Fields

Modifier and Type	Field	Description
static byte	ALG_DH_PLAIN	Diffie-Hellman (DH) secret value derivation primitive as per NIST Special Publication 800-56Ar2.
static byte	ALG_EC_PACE_GM	Elliptic curve Generic Mapping according to TR03110 v2.
static byte	ALG_EC_SVDP_DH	Elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363].
static byte	ALG_EC_SVDP_DH_KDF	Elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363].
static byte	ALG_EC_SVDP_DH_PLAIN	Elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363].
static byte	ALG_EC_SVDP_DH_PLAIN_XY	Elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363].
static byte	ALG_EC_SVDP_DHC	Elliptic curve secret value derivation primitive, Diffie-Hellman version, with cofactor multiplication and compatibility mode, as per [IEEE P1363].
static byte	ALG_EC_SVDP_DHC_KDF	Elliptic curve secret value derivation primitive, Diffie-Hellman version, with cofactor multiplication and compatibility mode, as per [IEEE P1363].
static byte	ALG_EC_SVDP_DHC_PLAIN	Elliptic curve secret value derivation primitive, Diffie-Hellman version, with cofactor multiplication and compatibility mode, as per [IEEE P1363].
static byte	ALG_SM2	SM2 Key Exchange protocol, using named curve key NamedParameterSpec.SM2, as defined in GM/T 0003.3-2012 (Public Key Cryptographic Algorithm SM2 Based on Elliptic Curves Part 3: Key Exchange Protocol).
static byte	ALG_XDH	X25519 and X448 Diffie-Hellman key agreement protocol, using named curves keys NamedParameterSpec.X25519 or NamedParameterSpec.X448, as defined in RFC 7748.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	KeyAgreement()	Protected constructor.

Method Summary

Modifier and Type	Method	Description
abstract short	generateSecret(byte[] publicData, short publicOffset, short publicLength, byte[] secret, short secretOffset)	Generates the secret data as per the requested algorithm using the PrivateKey specified during initialization and the public key data provided.
abstract byte	getAlgorithm()	Gets the KeyAgreement algorithm.
static KeyAgreement	getInstance(byte algorithm, boolean externalAccess)	Creates a KeyAgreement object instance of the selected algorithm.
abstract void	init(PrivateKey privKey)	Initializes the object with the given private key.

Methods inherited from class java.lang.Object

equals

Field Detail

ALG_EC_SVDP_DH

public static final byte ALG_EC_SVDP_DH

Elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363].

Note:

• This algorithm computes the SHA-1 message digest of the output of the derivation primitive to yield a 20 byte result.

See Also:

Constant Field Values

ALG_EC_SVDP_DH_KDF

public static final byte ALG_EC_SVDP_DH_KDF

Elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363].

Note:

• This algorithm computes the SHA-1 message digest of the output of the derivation primitive to yield a 20 byte result.

See Also:

Constant Field Values

ALG_EC_SVDP_DHC

public static final byte ALG_EC_SVDP_DHC

Elliptic curve secret value derivation primitive, Diffie-Hellman version, with cofactor multiplication and compatibility mode, as per [IEEE P1363]. (output value is to be equal to that from ALG_EC_SVDP_DH)

Note:

• This algorithm computes the SHA-1 message digest of the output of the derivation primitive to yield a 20 byte result.

See Also:

Constant Field Values

ALG_EC_SVDP_DHC_KDF

public static final byte ALG_EC_SVDP_DHC_KDF

Elliptic curve secret value derivation primitive, Diffie-Hellman version, with cofactor multiplication and compatibility mode, as per [IEEE P1363]. (output value is to be equal to that from ALG_EC_SVDP_DH_KDF)

Note:

• This algorithm computes the SHA-1 message digest of the output of the derivation primitive to yield a 20 byte result.

See Also:

Constant Field Values

ALG_EC_SVDP_DH_PLAIN

public static final byte ALG_EC_SVDP_DH_PLAIN

Elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363].

Note:

• This algorithm returns the raw output of the derivation primitive.

See Also:

Constant Field Values

ALG_EC_SVDP_DHC_PLAIN

public static final byte ALG_EC_SVDP_DHC_PLAIN

Elliptic curve secret value derivation primitive, Diffie-Hellman version, with cofactor multiplication and compatibility mode, as per [IEEE P1363]. (output value is to be equal to that from ALG_EC_SVDP_DH_PLAIN)

Note:

• This algorithm returns the raw output of the derivation primitive.

See Also:

Constant Field Values

ALG_EC_PACE_GM

public static final byte ALG_EC_PACE_GM

Elliptic curve Generic Mapping according to TR03110 v2. Performs the s * G + H calculation, where s is provided as EC private key private value, G is provided as base point of the private key object and H is passed as public data in the generateSecret() method.

Note:

• This algorithm returns the raw output of the derivation primitive.

See Also:

Constant Field Values

ALG_EC_SVDP_DH_PLAIN_XY

public static final byte ALG_EC_SVDP_DH_PLAIN_XY

Elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363]. Output is the full result represented as an octet string(uncompressed form) as per ANSI X9.62.

Note:

• This algorithm returns the raw output of the derivation primitive.

See Also:

Constant Field Values

ALG_DH_PLAIN

public static final byte ALG_DH_PLAIN

Diffie-Hellman (DH) secret value derivation primitive as per NIST Special Publication 800-56Ar2. Note:

• This algorithm returns the raw output of the derivation primitive, after integer to byte string conversion.

See Also:

Constant Field Values

ALG_XDH

public static final byte ALG_XDH

X25519 and X448 Diffie-Hellman key agreement protocol, using named curves keys NamedParameterSpec.X25519 or NamedParameterSpec.X448, as defined in RFC 7748.

Note: The curve parameters used depends on the key provided to init(PrivateKey) which must be a XECPrivateKey instantiated for the named curves NamedParameterSpec.X25519 or NamedParameterSpec.X448.

Since:

3.1

See Also:

KeyBuilder.buildXECKey(NamedParameterSpec, short, boolean), Constant Field Values

ALG_SM2

public static final byte ALG_SM2

SM2 Key Exchange protocol, using named curve key NamedParameterSpec.SM2, as defined in GM/T 0003.3-2012 (Public Key Cryptographic Algorithm SM2 Based on Elliptic Curves Part 3: Key Exchange Protocol).

Since:

3.1

See Also:

KeyBuilder.buildXECKey(NamedParameterSpec, short, boolean), Constant Field Values

Constructor Detail

KeyAgreement

protected KeyAgreement()

Protected constructor.

Method Detail

getInstance

public static final KeyAgreement getInstance(byte algorithm,
                                             boolean externalAccess)
                                      throws CryptoException

Creates a KeyAgreement object instance of the selected algorithm.

Parameters:

algorithm - the desired key agreement algorithm Valid codes listed in ALG_* constants above, for example, ALG_EC_SVDP_DH.

externalAccess - if true indicates that the instance will be shared among multiple applet instances and that the KeyAgreement instance will also be accessed (via a Shareable interface) when the owner of the KeyAgreement instance is not the currently selected applet. If true the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.

Returns:

the KeyAgreement object instance of the requested algorithm

Throws:

CryptoException - with the following reason codes:

• CryptoException.NO_SUCH_ALGORITHM if the requested algorithm or shared access mode is not supported.

init

public abstract void init(PrivateKey privKey)
                   throws CryptoException

Initializes the object with the given private key.

The Key is checked for consistency with the KeyAgreement algorithm. For example, the key type must be matched. For elliptic curve algorithms, the key must represent a valid point on the curve's domain parameters. Additional key component/domain parameter strength checks are implementation specific.

Parameters:

privKey - the private key

Throws:

CryptoException - with the following reason codes:

• CryptoException.ILLEGAL_VALUE if the input key type is inconsistent with the KeyAgreement algorithm, for example, if the KeyAgreement algorithm is ALG_EC_SVDP_DH and the key type is TYPE_RSA_PRIVATE, or if privKey is inconsistent with the implementation.
• CryptoException.UNINITIALIZED_KEY if privKey is uninitialized, or if the KeyAgreement algorithm is set to ALG_EC_SVDP_DHC and the cofactor, K, has not been successfully initialized since the time the initialized state of the key was set to false.

getAlgorithm

public abstract byte getAlgorithm()

Gets the KeyAgreement algorithm.

Returns:

the algorithm code defined above

generateSecret

public abstract short generateSecret(byte[] publicData,
                                     short publicOffset,
                                     short publicLength,
                                     byte[] secret,
                                     short secretOffset)
                              throws CryptoException

Generates the secret data as per the requested algorithm using the PrivateKey specified during initialization and the public key data provided.

Note that in the case of the algorithms ALG_EC_SVDP_DH and ALG_EC_SVDP_DHC the public key data provided should be the public elliptic curve point of the second party in the protocol, specified as per ANSI X9.62. A specific implementation need not support the compressed form, but must support the uncompressed form of the point.

In case of the algorithm ALG_DH_PLAIN the expected public data consists of an unsigned big endian encoding of the public parameter y. The maximum size in bytes is the size of the prime p.

In case of named curves algorithms ALG_XDH and ALG_SM2, the expected public data consists of the encoded key value as retrieved by XECKey.getEncoded(byte[], short) from the related public key i.e:

• NamedParameterSpec.X25519 or NamedParameterSpec.X448 for ALG_XDH
• NamedParameterSpec.SM2 for ALG_SM2

Parameters:

publicData - buffer holding the public data of the second party

publicOffset - offset into the publicData buffer at which the data begins

publicLength - byte length of the public data

secret - buffer to hold the secret output

secretOffset - offset into the secret array at which to start writing the secret

Returns:

byte length of the secret

Throws:

CryptoException - with the following reason codes:

• CryptoException.ILLEGAL_VALUE if the publicData data format is incorrect, or if the publicData data is inconsistent with the PrivateKey specified during initialization.
• CryptoException.INVALID_INIT if this KeyAgreement object is not initialized.