org.forgerock.json.jose.jwk

Class EcJWK

java.lang.Object

org.forgerock.json.jose.jwk.JWK

org.forgerock.json.jose.jwk.EcJWK

All Implemented Interfaces:

EllipticCurveJwk

public class EcJWK
extends JWK
implements EllipticCurveJwk

This class implements an Elliptical Curve Json Web Key storage and manipulation class.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EcJWK.Builder EC JWK builder.

Field Summary

Fields inherited from class org.forgerock.json.jose.jwk.JWK

JSON_KEY_ALG, JSON_KEY_KID, JSON_KEY_KTY, JSON_KEY_OPERATIONS, JSON_KEY_USE, JSON_KEY_X5C, JSON_KEY_X5T, JSON_KEY_X5U

Constructor Summary

Constructors

Constructor and Description
EcJWK(ECPublicKey publicKey, ECPrivateKey privateKey, KeyUse use, String kid) Deprecated. Use the builder instead.
EcJWK(ECPublicKey publicKey, KeyUse use, String kid) Deprecated. Use the builder instead.
EcJWK(KeyUse use, String alg, String kid, String x, String y, String curve, String x5u, String x5t, List<String> x5c) Deprecated. Use the builder instead.
EcJWK(KeyUse use, String alg, String kid, String x, String y, String d, String curve, String x5u, String x5t, List<String> x5c) Deprecated. Use the builder instead.

Method Summary

Modifier and Type	Method and Description
static EcJWK.Builder	builder(ECPublicKey publicKey) Get the builder.
static EcJWK.Builder	builder(String curve, String x, String y) Get the builder.
static EcJWK.Builder	builder(SupportedEllipticCurve curve, String x, String y) Get the builder.
static BigInteger	decodeCoordinate(String encodedCoordinate) Decode the unsigned big-endian base64 url encoding of an elliptical curve point.
static String	encodeCoordinate(int fieldSize, BigInteger coordinate) Base64url encode the unsigned big-endian representation of an elliptical curve point.
String	getCurve() Deprecated. replaced by EcJWK.getEllipticCurve().
String	getD() Gets the unsigned big-endian base64 url encoding of the d value for the elliptical curve private key.
SupportedEllipticCurve	getEllipticCurve() Gets the elliptic curve.
protected Optional<JWK.Builder<?>>	getPublicJwkBuilder() Return a builder with all the values set for representing the public components of the JWK.
String	getX() Gets the unsigned big-endian base64 url encoding of the elliptical curve point x coordinate.
String	getY() Gets the unsigned big-endian base64 url encoding of the elliptical curve point y coordinate.
boolean	isPrivate() Indicates if any private key attributes are present in the JWK.
boolean	isPublicKeyValid() Checks for validity of the public key portion of this JWK as per EcJWK.isPublicKeyValid(ECPublicKey, SupportedEllipticCurve).
static boolean	isPublicKeyValid(ECPublicKey publicKey, SupportedEllipticCurve curve) Checks whether the public key actually lies on the curve it claims to be on.
static EcJWK	parse(JsonValue json) Parses a JWK from a JsonValue json object.
static EcJWK	parse(String json) Parses a JWK from a string json object.
ECPrivateKey	toECPrivateKey() Converts the JWK to a ECPrivateKey.
ECPublicKey	toECPublicKey() Converts the JWK to a ECPublicKey.
JsonValue	toJsonValue() Returns a json representation of the JWK.
KeyPair	toKeyPair() Converts the JWK to a KeyPair.
PublicKey	toPublicKey() Converts the public claims in the JWK into a public key.

Methods inherited from class org.forgerock.json.jose.jwk.JWK

getAlgorithm, getAlgorithm, getJwaAlgorithm, getKeyId, getKeyOperations, getKeyType, getUse, getX509Chain, getX509Thumbnail, getX509URL, loadJWKFromJson, putField, toJsonString, toJsonValue, toPublicJwk

Methods inherited from class java.lang.Object

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

Constructor Detail

EcJWK

@Deprecated
public EcJWK(ECPublicKey publicKey,
                         KeyUse use,
                         String kid)

Deprecated. Use the builder instead.

Creates a public EcJWK.

Parameters:

publicKey - The public key for the JWK

use - The value of the use JWK parameter

kid - The key id of the JWK

EcJWK

@Deprecated
public EcJWK(ECPublicKey publicKey,
                         ECPrivateKey privateKey,
                         KeyUse use,
                         String kid)

Deprecated. Use the builder instead.

Creates a public and private EcJWK.

Parameters:

publicKey - The public key for the JWK

privateKey - The private key for the JWK

use - The value of the use JWK parameter

kid - The key id of the JWK

EcJWK

@Deprecated
public EcJWK(KeyUse use,
                         String alg,
                         String kid,
                         String x,
                         String y,
                         String curve,
                         String x5u,
                         String x5t,
                         List<String> x5c)

Deprecated. Use the builder instead.

Creates a public EcJWK.

Parameters:

use - The value of the use JWK parameter

alg - The value of the alg JWK parameter

kid - The key id of the JWK

x - The unsigned big-endian base64 url encoding of the elliptical curve point x coordinate

y - The unsigned big-endian base64 url encoding of the elliptical curve point y coordinate

curve - The known curve to use. For example "NIST P-256".

x5u - the x509 url for the key

x5t - the x509 thumbnail for the key

x5c - the x509 chain as a list of Base64 encoded strings

EcJWK

@Deprecated
public EcJWK(KeyUse use,
                         String alg,
                         String kid,
                         String x,
                         String y,
                         String d,
                         String curve,
                         String x5u,
                         String x5t,
                         List<String> x5c)

Deprecated. Use the builder instead.

Creates a public and private EcJWK.

Parameters:

use - The value of the use JWK parameter

alg - The value of the alg JWK parameter

kid - The key id of the JWK

x - The unsigned big-endian base64 url encoding of the elliptical curve point x coordinate

y - The unsigned big-endian base64 url encoding of the elliptical curve point y coordinate

d - The unsigned big-endian base64 url encoding of the d value for the elliptical curve private key

curve - The known curve to use. For example "NIST P-256".

x5u - the x509 url for the key

x5t - the x509 thumbnail for the key

x5c - the x509 chain as a list of Base64 encoded strings

Method Detail

builder

public static EcJWK.Builder builder(SupportedEllipticCurve curve,
                                    String x,
                                    String y)

Get the builder.

Parameters:

curve - The known curve to use. For example "NIST P-256".

x - The unsigned big-endian base64 url encoding of the elliptical curve point x coordinate

y - The unsigned big-endian base64 url encoding of the elliptical curve point y coordinate

Returns:

the EC JWK builder

builder

public static EcJWK.Builder builder(String curve,
                                    String x,
                                    String y)

Get the builder.

Parameters:

curve - The known curve to use. For example "NIST P-256".

x - The unsigned big-endian base64 url encoding of the elliptical curve point x coordinate

y - The unsigned big-endian base64 url encoding of the elliptical curve point y coordinate

Returns:

the EC JWK builder

builder

public static EcJWK.Builder builder(ECPublicKey publicKey)

Get the builder.

Parameters:

publicKey - The public key for the JWK

Returns:

the EC JWK builder

getX

public String getX()

Gets the unsigned big-endian base64 url encoding of the elliptical curve point x coordinate.

Returns:

unsigned big-endian base64 url encoding of the elliptical curve point x coordinate

getY

public String getY()

Gets the unsigned big-endian base64 url encoding of the elliptical curve point y coordinate.

Returns:

the unsigned big-endian base64 url encoding of the elliptical curve point y coordinate

getD

public String getD()

Gets the unsigned big-endian base64 url encoding of the d value for the elliptical curve private key.

Returns:

the unsigned big-endian base64 url encoding of the d value for the elliptical curve private key

getCurve

@Deprecated
public String getCurve()

Deprecated. replaced by EcJWK.getEllipticCurve().

Gets the known curve to use. For example "NIST P-256".

Returns:

the known curve of the JWK

getEllipticCurve

public SupportedEllipticCurve getEllipticCurve()

Gets the elliptic curve.

Specified by:

getEllipticCurve in interface EllipticCurveJwk

Returns:

the elliptic curve of the JWK

parse

public static EcJWK parse(String json)

Parses a JWK from a string json object.

Parameters:

json - string json object

Returns:

a EcJWK object

parse

public static EcJWK parse(JsonValue json)

Parses a JWK from a JsonValue json object.

Parameters:

json - JsonValue json object

Returns:

a EcJWK object

toJsonValue

public JsonValue toJsonValue()

Description copied from class: JWK

Returns a json representation of the JWK.

Overrides:

toJsonValue in class JWK

Returns:

A JSON representation.

toECPublicKey

public ECPublicKey toECPublicKey()

Converts the JWK to a ECPublicKey.

Specified by:

toECPublicKey in interface EllipticCurveJwk

Returns:

an ECPublicKey

toPublicKey

public PublicKey toPublicKey()

Description copied from interface: EllipticCurveJwk

Converts the public claims in the JWK into a public key. Note that the public key returned may not be an ECPublicKey. For instance, on Java 11 an OkpJWK may return a XECPrivateKey.

Specified by:

toPublicKey in interface EllipticCurveJwk

Returns:

the public key.

toECPrivateKey

public ECPrivateKey toECPrivateKey()

Converts the JWK to a ECPrivateKey.

Returns:

an ECPrivateKey

toKeyPair

public KeyPair toKeyPair()

Converts the JWK to a KeyPair.

Specified by:

toKeyPair in interface EllipticCurveJwk

Returns:

an KeyPair

decodeCoordinate

public static BigInteger decodeCoordinate(String encodedCoordinate)

Decode the unsigned big-endian base64 url encoding of an elliptical curve point.

Parameters:

encodedCoordinate - the unsigned big-endian base64 url encoding of a the elliptical curve point

Returns:

the elliptical curve point

encodeCoordinate

public static String encodeCoordinate(int fieldSize,
                                      BigInteger coordinate)

Base64url encode the unsigned big-endian representation of an elliptical curve point.

Parameters:

fieldSize - the EC field size in bits.

coordinate - the elliptical curve point

Returns:

the unsigned big-endian base64 url encoding of the elliptical curve point

isPrivate

public boolean isPrivate()

Description copied from class: JWK

Indicates if any private key attributes are present in the JWK.

Overrides:

isPrivate in class JWK

Returns:

true if this JWK contains any private key attributes.

getPublicJwkBuilder

protected Optional<JWK.Builder<?>> getPublicJwkBuilder()

Description copied from class: JWK

Return a builder with all the values set for representing the public components of the JWK. Common JWK attributes will be added in JWK.toPublicJwk().

Specified by:

getPublicJwkBuilder in class JWK

Returns:

The builder.

isPublicKeyValid

public boolean isPublicKeyValid()

Checks for validity of the public key portion of this JWK as per EcJWK.isPublicKeyValid(ECPublicKey, SupportedEllipticCurve).

Specified by:

isPublicKeyValid in interface EllipticCurveJwk

Returns:

true if the public key is on the curve it claims to be on and is valid.

isPublicKeyValid

public static boolean isPublicKeyValid(ECPublicKey publicKey,
                                       SupportedEllipticCurve curve)

Checks whether the public key actually lies on the curve it claims to be on. Checking this is critical in ECDH protocols where the other party may be malicious. In this case, the attacker can send public keys that force the shared secret to be chosen from a small group. If a long-lived ECDH key pair is being used, then this may eventually allow an attacker to recover the private key.

NB: This bug has been fixed in the Oracle JRE/OpenJDK since 1.6.0_101, 1.7.0_85, and 1.8.0_51, but we include the check here for completeness and security when running on other JREs which may not implement the check.

The checks performed are those from NIST SP 800-56A (rev. 2), section 5.6.2.3.3 - ECC Partial Public-Key Validation Routine. This is a sufficient check for validating public keys used in "Cofactor Diffie Hellman" (ECC CDH), as defined in SP 800-56A. The JWA spec actually uses non-cofactor Diffie Hellman (ECDH), but because the cofactor for all of the NIST prime order curves in use here (P-256, P-384 and P-521) is 1 (i.e., h = 1), the two schemes are equivalent. This is confirmed by SEC 1: Elliptic Curve Cryptography, section 3.2.2.1 - Elliptic Curve Public Key Validation Primitive:

“In Step 4, it may not be necessary to compute the point nQ. For example, if h = 1, then nQ = O is implied by the checks in Steps 2 and 3, because this property holds for all points Q ∈ E”

Parameters:

publicKey - the public key to check.

curve - the supported elliptic curve parameters to check the public key against.

Returns:

true if the public key is on the curve it claims to be on and is valid.

See Also:

Critical vulnerability in JSON Web Encryption (JWE) for background, Bug report for CVE-2015-2613 - missing EC parameter validation in ECDH_Derive(), NIST SP 800-56A (rev 2) sections 5.6.2.2 and 5.6.2.3 for detailed advice on what validations to perform on public keys and how., SEC 1: Elliptic Curve Cryptography, sections 3.2.2 and 3.2.3 for further guidance on public key validation.