Interface BDHKeyAgreement

public interface BDHKeyAgreement

BDHKeyAgreement is a preview API of the Java Card platform.

Programs can only use BDHKeyAgreement when preview features are enabled.

Preview features may be removed in a future release, or upgraded to permanent features of the Java Card platform.

The BDHKeyAgreement interface can be used for KeyAgreement instances supporting Elliptic Curve Blinded Diffie-Hellman Key Exchange protocol as defined in EMV Contactless Specifications for Payment Systems - Book E Security and Key Management - Version 1.1 Feb 2025.

A KeyAgreement instance implementing the BDHKeyAgreement interface can be created by the KeyAgreement.getInstance(byte, boolean) method using the KeyAgreement.ALG_EC_BDH_SECP256R1^PREVIEW algorithm constant. The returned KeyAgreement instance should then be cast into BDHKeyAgreement to generate the blinding factor, the blinded public key and the shared secret.

Since:

preview

See Also:

• KeyAgreement.getInstance(byte, boolean)

Method Summary

Modifier and Type	Method	Description
short	generateSecret(byte[] publicData, short publicOffset, short publicLength, byte[] secret, short secretOffset, byte[] blindedPublicKey, short blindedPublicKeyOffset, byte[] blindingFactor, short blindingFactorOffset)	Generates the shared secret data and the blinded public key as per the Blinded Diffie-Hellman key exchange protocol, using the PrivateKey specified during initialization and the provided public key data.

Method Details

generateSecret

short generateSecret(byte[] publicData,
 short publicOffset,
 short publicLength,
 byte[] secret,
 short secretOffset,
 byte[] blindedPublicKey,
 short blindedPublicKeyOffset,
 byte[] blindingFactor,
 short blindingFactorOffset)

Generates the shared secret data and the blinded public key as per the Blinded Diffie-Hellman key exchange protocol, using the PrivateKey specified during initialization and the provided public key data.

The shared secret, referred to as z in the EMV specification, is computed as follows:

z = dC · r · QK

where:

• dC is the private key used for initialization,
• r is the generated blinding factor,
• QK is the public key from the second party.

The resulting shared secret is 32 bytes for secp256r1.

The generated blinded public key is encoded using only its X-affine coordinate, represented as an unsigned, big-endian field element, zero-padded to the curve’s fixed field size. The length of the generated blinded public key is 32 bytes for secp256r1.

The length of the generated blinding factor is 32 bytes for secp256r1.

A call to this method resets the KeyAgreement object to its state set via a call to init(PrivateKey), making the object available again for generating secret data.

Parameters:

publicData - buffer holding the public key data of the second party, encoded as the concatenation of X and Y, where X and Y are the affine coordinates of the elliptic curve point, each represented as an unsigned big-endian field element, zero-padded to the curve’s fixed field size. The total length is therefore 64 bytes for secp256r1 (32 bytes per coordinate).

publicOffset - offset into the publicData buffer where the data begins

publicLength - byte length of the public data

secret - buffer to hold the secret output

secretOffset - offset into the secret array where to start writing the secret

blindedPublicKey - buffer to hold the blinded public key output

blindedPublicKeyOffset - offset into the blindedPublicKey array where to start writing the blinded public key

blindingFactor - buffer to hold the generated blinding factor. The length of the generated blinding factor is 32 bytes for secp256r1.

blindingFactorOffset - offset into the blindingFactor buffer where the data begins

Returns:

byte length of the secret

Throws:

CryptoException - with the following reason codes:

• CryptoException.UNINITIALIZED_KEY if the PrivateKey specified in KeyAgreement.init(PrivateKey) is not initialized.
• CryptoException.ILLEGAL_VALUE
  • if the publicData data format or length is incorrect,
  • or if the publicData data is inconsistent with the key specified in KeyAgreement.init(PrivateKey).
• CryptoException.INVALID_INIT if this KeyAgreement object is not initialized.