Package com.nimbusds.jose.crypto.impl

Class ECDH1PU

java.lang.Object

com.nimbusds.jose.crypto.impl.ECDH1PU

public class ECDH1PU
extends Object

Elliptic Curve Diffie-Hellman One-Pass Unified Model (ECDH-1PU) key agreement functions and utilities.

Version:

2021-08-03

Author:

Alexander Martynov

See Also:

Public Key Authenticated Encryption for JOSE: ECDH-1PU

Method Summary

Modifier and Type	Method	Description
static SecretKey	deriveRecipientZ(OctetKeyPair privateKey, OctetKeyPair publicKey, OctetKeyPair epk)	Derives a shared secret (also called 'Z') for recipient where Z is the concatenation of Ze and Zs.
static SecretKey	deriveRecipientZ(ECPrivateKey privateKey, ECPublicKey publicKey, ECPublicKey epk, Provider provider)	Derives a shared secret (also called 'Z') for sender where Z is the concatenation of Ze and Zs.
static SecretKey	deriveSenderZ(OctetKeyPair privateKey, OctetKeyPair publicKey, OctetKeyPair epk)	Derives a shared secret (also called 'Z') for sender where Z is the concatenation of Ze and Zs.
static SecretKey	deriveSenderZ(ECPrivateKey privateKey, ECPublicKey publicKey, ECPrivateKey epk, Provider provider)	Derives a shared secret (also called 'Z') for sender where Z is the concatenation of Ze and Zs.
static SecretKey	deriveSharedKey(JWEHeader header, SecretKey Z, ConcatKDF concatKDF)	Derives a shared key (via concat KDF).
static SecretKey	deriveSharedKey(JWEHeader header, SecretKey Z, Base64URL tag, ConcatKDF concatKDF)	Derives a shared key (via concat KDF).
static SecretKey	deriveZ(SecretKey Ze, SecretKey Zs)	Derives a shared secret (also called 'Z') where Z is the concatenation of Ze and Zs.
static ECDH.AlgorithmMode	resolveAlgorithmMode(JWEAlgorithm alg)	Resolves the ECDH algorithm mode.
static int	sharedKeyLength(JWEAlgorithm alg, EncryptionMethod enc)	Returns the bit length of the shared key (derived via concat KDF) for the specified JWE ECDH algorithm.
static void	validateSameCurve(OctetKeyPair privateKey, OctetKeyPair publicKey)	Ensures the private key and public key are from the same curve.
static void	validateSameCurve(ECPrivateKey privateKey, ECPublicKey publicKey)	Ensures the private key and public key are from the same curve.

Methods inherited from class java.lang.Object

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

Method Detail

resolveAlgorithmMode

public static ECDH.AlgorithmMode resolveAlgorithmMode(JWEAlgorithm alg)
                                               throws JOSEException

Resolves the ECDH algorithm mode.

Parameters:

alg - The JWE algorithm. Must be supported and not null.

Returns:

The algorithm mode.

Throws:

JOSEException - If the JWE algorithm is not supported.

sharedKeyLength

public static int sharedKeyLength(JWEAlgorithm alg,
                                  EncryptionMethod enc)
                           throws JOSEException

Returns the bit length of the shared key (derived via concat KDF) for the specified JWE ECDH algorithm.

Parameters:

alg - The JWE ECDH algorithm. Must be supported and not null.

enc - The encryption method. Must be supported and not null.

Returns:

The bit length of the shared key.

Throws:

JOSEException - If the JWE algorithm or encryption method is not supported.

deriveSharedKey

public static SecretKey deriveSharedKey(JWEHeader header,
                                        SecretKey Z,
                                        ConcatKDF concatKDF)
                                 throws JOSEException

Derives a shared key (via concat KDF). The method should only be called in the ECDH.AlgorithmMode.DIRECT mode. The method derives the Content Encryption Key (CEK) for the "enc" algorithm, in the ECDH.AlgorithmMode.DIRECT mode. The method does not take the auth tag because the auth tag will be generated using a CEK derived as an output of this method.

Parameters:

header - The JWE header. Its algorithm and encryption method must be supported. Must not be null.

Z - The derived shared secret ('Z'). Must not be null.

concatKDF - The concat KDF. Must be initialised and not null.

Returns:

The derived shared key.

Throws:

JOSEException - If derivation of the shared key failed.

deriveSharedKey

public static SecretKey deriveSharedKey(JWEHeader header,
                                        SecretKey Z,
                                        Base64URL tag,
                                        ConcatKDF concatKDF)
                                 throws JOSEException

Derives a shared key (via concat KDF). The method should only be called in ECDH.AlgorithmMode.KW. In Key Agreement with ECDH.AlgorithmMode.KW mode, the JWE Authentication Tag is included in the input to the KDF. This ensures that the content of the JWE was produced by the original sender and not by another recipient.

Parameters:

header - The JWE header. Its algorithm and encryption method must be supported. Must not be null.

Z - The derived shared secret ('Z'). Must not be null.

tag - In Direct Key Agreement mode this is set to an empty octet string. In Key Agreement with Key Wrapping mode, this is set to a value of the form Data, where Data is the raw octets of the JWE Authentication Tag.

concatKDF - The concat KDF. Must be initialised and not null.

Returns:

The derived shared key.

Throws:

JOSEException - If derivation of the shared key failed.

deriveZ

public static SecretKey deriveZ(SecretKey Ze,
                                SecretKey Zs)

Derives a shared secret (also called 'Z') where Z is the concatenation of Ze and Zs.

Parameters:

Ze - The shared secret derived from applying the ECDH primitive to the sender's ephemeral private key and the recipient's static public key (when sending) or the recipient's static private key and the sender's ephemeral public key (when receiving). Must not be null.

Zs - The shared secret derived from applying the ECDH primitive to the sender's static private key and the recipient's static public key (when sending) or the recipient's static private key and the sender's static public key (when receiving). Must not be null.

Returns:

The derived shared key.

deriveSenderZ

public static SecretKey deriveSenderZ(ECPrivateKey privateKey,
                                      ECPublicKey publicKey,
                                      ECPrivateKey epk,
                                      Provider provider)
                               throws JOSEException

Derives a shared secret (also called 'Z') for sender where Z is the concatenation of Ze and Zs. Where Ze is shared secret from applying the ECDH primitive to the sender's ephemeral private key and the recipient's static public key, Zs is the shared secret derived from applying the ECDH primitive to the sender's static private key and the recipient's static public key.

Parameters:

privateKey - The sender EC private key.

publicKey - The recipient EC public key.

epk - The sender EC ephemeral private key.

provider - The specific JCA provider for the ECDH key agreement, null to use the default one.

Returns:

The derived shared secret ('Z'), with algorithm "AES".

Throws:

JOSEException - If derivation of the shared secret failed.

deriveSenderZ

public static SecretKey deriveSenderZ(OctetKeyPair privateKey,
                                      OctetKeyPair publicKey,
                                      OctetKeyPair epk)
                               throws JOSEException

Derives a shared secret (also called 'Z') for sender where Z is the concatenation of Ze and Zs. Where Ze is shared secret from applying the ECDH primitive to the sender's ephemeral public key and the recipient's static private key, Zs is the shared secret derived from applying the ECDH primitive to the sender's static public key and the recipient's static private key.

Parameters:

privateKey - The sender OctetKey private key.

publicKey - The recipient OctetKey public key.

epk - The sender OctetKey ephemeral private key.

Returns:

The derived shared secret ('Z'), with algorithm "AES".

Throws:

JOSEException - If derivation of the shared secret failed.

deriveRecipientZ

public static SecretKey deriveRecipientZ(ECPrivateKey privateKey,
                                         ECPublicKey publicKey,
                                         ECPublicKey epk,
                                         Provider provider)
                                  throws JOSEException

Derives a shared secret (also called 'Z') for sender where Z is the concatenation of Ze and Zs. Where Ze is shared secret from applying the ECDH primitive to the sender's ephemeral public key and the recipient's static private key, Zs is the shared secret derived from applying the ECDH primitive to the sender's static public key and the recipient's static private key.

Parameters:

privateKey - The sender EC private key.

publicKey - The recipient EC public key.

epk - The sender EC ephemeral public key.

provider - The specific JCA provider for the ECDH key agreement, null to use the default one.

Returns:

The derived shared secret ('Z'), with algorithm "AES".

Throws:

JOSEException - If derivation of the shared secret failed.

deriveRecipientZ

public static SecretKey deriveRecipientZ(OctetKeyPair privateKey,
                                         OctetKeyPair publicKey,
                                         OctetKeyPair epk)
                                  throws JOSEException

Derives a shared secret (also called 'Z') for recipient where Z is the concatenation of Ze and Zs.

Parameters:

privateKey - The sender OctetKey private key.

publicKey - The recipient OctetKey public key.

epk - The sender OctetKey ephemeral private key.

Returns:

The derived shared secret ('Z'), with algorithm "AES".

Throws:

JOSEException - If derivation of the shared secret failed.

validateSameCurve

public static void validateSameCurve(ECPrivateKey privateKey,
                                     ECPublicKey publicKey)
                              throws JOSEException

Ensures the private key and public key are from the same curve.

Parameters:

privateKey - EC private key. Must not be null.

publicKey - EC public key. Must not be null.

Throws:

JOSEException - If the key curves don't match.

validateSameCurve

public static void validateSameCurve(OctetKeyPair privateKey,
                                     OctetKeyPair publicKey)
                              throws JOSEException

Ensures the private key and public key are from the same curve.

Parameters:

privateKey - OKP private key. Must not be null.

publicKey - OKP public key. Must not be null.

Throws:

JOSEException - If the curves don't match.