org.forgerock.json.jose.utils

Class XECUtils

java.lang.Object

org.forgerock.json.jose.utils.XECUtils

public final class XECUtils
extends Object

Utilities for handling XEC keys for X25519 and X448 ECDH key agreement. These classes are only available from Java 11, so we use reflection to perform default behaviour on earlier JDKs (typically returning null).

Method Summary

Modifier and Type	Method and Description
static SupportedEllipticCurve	curve(Key key) Returns the curve that this XECKey is for.
static boolean	isXDHSupported() Indicates whether XDH (Diffie-Hellman using the X25519/X448 curves) is supported by this JDK.
static boolean	isXecKey(Key key) Determines whether the given key is a XECKey.
static AlgorithmParameterSpec	namedCurveParams(Key key) Returns the NamedCurveParameters for this key.
static AlgorithmParameterSpec	namedCurveParams(String namedCurve, AlgorithmParameterSpec defaultSpec) Tries to construct a NamedParameterSpec for a given curve name (currently either "X25519" or "X448").
static byte[]	privateScalarValue(PrivateKey privateKey) Returns the private scalar value for the given XECPrivateKey.
static byte[]	publicUCoordinate(PublicKey publicKey) Returns the little-endian bytes of the public u-coordinate of the given XECPublicKey.
static PrivateKey	xecPrivateKey(SupportedEllipticCurve curve, byte[] privateValue) Converts a private scalar byte value into a XECPrivateKey on the given curve.
static PublicKey	xecPublicKey(SupportedEllipticCurve curve, BigInteger uCoord) Converts a public u-coordinate into a XECPublicKey on the given curve.

Methods inherited from class java.lang.Object

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

Method Detail

isXDHSupported

public static boolean isXDHSupported()

Indicates whether XDH (Diffie-Hellman using the X25519/X448 curves) is supported by this JDK. If this returns true then all methods in this class should be supported. Java 11 is required for XDH support.

Returns:

true if XDH key agreement is supported.

isXecKey

public static boolean isXecKey(Key key)

Determines whether the given key is a XECKey.

Parameters:

key - the key.

Returns:

true if XDH is available and this is a XECKey, or else false.

xecPrivateKey

public static PrivateKey xecPrivateKey(SupportedEllipticCurve curve,
                                       byte[] privateValue)

Converts a private scalar byte value into a XECPrivateKey on the given curve.

Parameters:

curve - the curve. Must be either X25519 or X448.

privateValue - the private scalar value.

Returns:

the XECPrivateKey corresponding to the given curve and private value.

Throws:

UnsupportedOperationException - if XDH support is not available.

IllegalArgumentException - if the curve is not X25519 or X448 or if there is a problem with the scalar.

xecPublicKey

public static PublicKey xecPublicKey(SupportedEllipticCurve curve,
                                     BigInteger uCoord)

Converts a public u-coordinate into a XECPublicKey on the given curve.

Parameters:

curve - the curve. Must be either X25519 or X448.

uCoord - the public u coordinate value.

Returns:

the XECPublicKey corresponding to the given curve and coordinate.

Throws:

UnsupportedOperationException - if XDH support is not available.

IllegalArgumentException - if the curve is not X25519 or X448 or there is a problem with the u-coordinate.

publicUCoordinate

public static byte[] publicUCoordinate(PublicKey publicKey)

Returns the little-endian bytes of the public u-coordinate of the given XECPublicKey.

Parameters:

publicKey - the public key.

Returns:

the unsigned big-endian bytes of the public u-coordinate.

Throws:

IllegalStateException - if XDH support is not available.

IllegalArgumentException - if the key is not a XECPublicKey.

privateScalarValue

public static byte[] privateScalarValue(PrivateKey privateKey)

Returns the private scalar value for the given XECPrivateKey.

Parameters:

privateKey - the private key.

Returns:

the private scalar value.

Throws:

IllegalStateException - if XDH support is not available.

IllegalArgumentException - if the key is not a XECPrivateKey.

curve

public static SupportedEllipticCurve curve(Key key)

Returns the curve that this XECKey is for.

Parameters:

key - the key. Must be a XECKey.

Returns:

the supported elliptic curve for this key.

Throws:

IllegalStateException - if XDH support is not available.

IllegalArgumentException - if the key is not a XECKey.

namedCurveParams

public static AlgorithmParameterSpec namedCurveParams(Key key)

Returns the NamedCurveParameters for this key.

Parameters:

key - the key. Must be a XECKey.

Returns:

the NamedCurveParameters for this key.

Throws:

IllegalArgumentException - if the key is not a XECKey.

IllegalStateException - if XDH support is not available.

namedCurveParams

public static AlgorithmParameterSpec namedCurveParams(String namedCurve,
                                                      AlgorithmParameterSpec defaultSpec)

Tries to construct a NamedParameterSpec for a given curve name (currently either "X25519" or "X448"). If XDH is not supported on this JVM, then this returns the given default parameter spec instead.

Parameters:

namedCurve - the named curve.

defaultSpec - the default parameter spec to use if XDH is not available.

Returns:

the named or default parameter spec.