io.jsonwebtoken.security

Interface DynamicJwkBuilder<K extends Key,J extends Jwk<K>>

Type Parameters:

K - the type of Java Key represented by the created Jwk.

J - the type of Jwk created by the builder

All Superinterfaces:

Builder<J>, JwkBuilder<K,J,DynamicJwkBuilder<K,J>>, KeyOperationPolicied<DynamicJwkBuilder<K,J>>, MapMutator<String,Object,DynamicJwkBuilder<K,J>>, SecurityBuilder<J,DynamicJwkBuilder<K,J>>

public interface DynamicJwkBuilder<K extends Key,J extends Jwk<K>>
extends JwkBuilder<K,J,DynamicJwkBuilder<K,J>>

A JwkBuilder that coerces to a more type-specific builder based on the Key that will be represented as a JWK.

Since:

0.12.0

Method Summary

Methods

Modifier and Type	Method and Description
<A extends PublicKey,B extends PrivateKey> PublicJwkBuilder<A,B,?,?,?,?>	chain(List<X509Certificate> chain) Ensures the builder will create a PublicJwk for the specified Java X509Certificate chain.
EcPublicJwkBuilder	ecChain(List<X509Certificate> chain) Ensures the builder will create an EcPublicJwk for the specified Java X509Certificate chain.
EcPrivateJwkBuilder	ecKeyPair(KeyPair keyPair) Ensures the builder will create an EcPrivateJwk for the specified Java Elliptic Curve KeyPair.
<A extends PublicKey,B extends PrivateKey> PublicJwkBuilder<A,B,?,?,?,?>	key(A key) Ensures the builder will create a PublicJwk for the specified Java PublicKey argument.
<A extends PublicKey,B extends PrivateKey> PrivateJwkBuilder<B,A,?,?,?>	key(B key) Ensures the builder will create a PrivateJwk for the specified Java PrivateKey argument.
EcPrivateJwkBuilder	key(ECPrivateKey key) Ensures the builder will create an EcPrivateJwk for the specified Java ECPrivateKey.
EcPublicJwkBuilder	key(ECPublicKey key) Ensures the builder will create an EcPublicJwk for the specified Java ECPublicKey.
RsaPrivateJwkBuilder	key(RSAPrivateKey key) Ensures the builder will create an RsaPrivateJwk for the specified Java RSAPrivateKey.
RsaPublicJwkBuilder	key(RSAPublicKey key) Ensures the builder will create an RsaPublicJwk for the specified Java RSAPublicKey.
SecretJwkBuilder	key(SecretKey key) Ensures the builder will create a SecretJwk for the specified Java SecretKey.
<A extends PublicKey,B extends PrivateKey> PrivateJwkBuilder<B,A,?,?,?>	keyPair(KeyPair keyPair) Ensures the builder will create a PrivateJwk for the specified Java KeyPair argument.
<A extends PublicKey,B extends PrivateKey> OctetPublicJwkBuilder<A,B>	octetChain(List<X509Certificate> chain) Ensures the builder will create an OctetPublicJwk for the specified Java X509Certificate chain.
<A extends PrivateKey,B extends PublicKey> OctetPrivateJwkBuilder<A,B>	octetKey(A key) Ensures the builder will create an OctetPrivateJwk for the specified Edwards-curve PrivateKey argument.
<A extends PublicKey,B extends PrivateKey> OctetPublicJwkBuilder<A,B>	octetKey(A key) Ensures the builder will create an OctetPublicJwk for the specified Edwards-curve PublicKey argument.
<A extends PrivateKey,B extends PublicKey> OctetPrivateJwkBuilder<A,B>	octetKeyPair(KeyPair keyPair) Ensures the builder will create an OctetPrivateJwk for the specified Java Edwards-curve KeyPair.
RsaPublicJwkBuilder	rsaChain(List<X509Certificate> chain) Ensures the builder will create an RsaPublicJwk for the specified Java X509Certificate chain.
RsaPrivateJwkBuilder	rsaKeyPair(KeyPair keyPair) Ensures the builder will create an RsaPrivateJwk for the specified Java RSA KeyPair.

Methods inherited from interface io.jsonwebtoken.security.JwkBuilder

algorithm, id, idFromThumbprint, idFromThumbprint, operations

Methods inherited from interface io.jsonwebtoken.lang.MapMutator

add, add, delete, empty

Methods inherited from interface io.jsonwebtoken.security.SecurityBuilder

provider, random

Methods inherited from interface io.jsonwebtoken.lang.Builder

build

Methods inherited from interface io.jsonwebtoken.security.KeyOperationPolicied

operationPolicy

Method Detail

chain

<A extends PublicKey,B extends PrivateKey> PublicJwkBuilder<A,B,?,?,?,?> chain(List<X509Certificate> chain)
                                                                         throws UnsupportedKeyException

Ensures the builder will create a PublicJwk for the specified Java X509Certificate chain. The first X509Certificate in the chain (at array index 0) MUST contain a PublicKey instance when calling the certificate's getPublicKey() method.

This method is provided for congruence with the other chain methods and is expected to be used when the calling code has a variable PublicKey reference. Based on the argument type, it will delegate to one of the following methods if possible:

• rsaChain(List)
• ecChain(List)
• octetChain(List)

If the specified chain argument is not capable of being supported by one of those methods, an UnsupportedKeyException will be thrown.

Type Parameters

In addition to the public key type A, the public key's associated private key type B is parameterized as well. This ensures that any subsequent call to the builder's privateKey method will be type-safe. For example:

Jwks.builder().<EdECPublicKey, EdECPrivateKey>chain(edECPublicKeyX509CertificateChain)
     .privateKey(aPrivateKey) // <-- must be an EdECPrivateKey instance
     ... etc ...
     .build();

Type Parameters:

A - the type of PublicKey provided by the created public JWK.

B - the type of PrivateKey that may be paired with the PublicKey to produce a PrivateJwk if desired.

Parameters:

chain - the X509Certificate chain to inspect to find the PublicKey to represent as a PublicJwk.

Returns:

the builder coerced as a PublicJwkBuilder for continued method chaining.

Throws:

UnsupportedKeyException - if the specified key is not a supported type and cannot be used to delegate to other key methods.

See Also:

PublicJwk, PrivateJwk

key

SecretJwkBuilder key(SecretKey key)

Ensures the builder will create a SecretJwk for the specified Java SecretKey.

Parameters:

key - the SecretKey to represent as a SecretJwk.

Returns:

the builder coerced as a SecretJwkBuilder.

key

RsaPublicJwkBuilder key(RSAPublicKey key)

Ensures the builder will create an RsaPublicJwk for the specified Java RSAPublicKey.

Parameters:

key - the RSAPublicKey to represent as a RsaPublicJwk.

Returns:

the builder coerced as an RsaPublicJwkBuilder.

key

RsaPrivateJwkBuilder key(RSAPrivateKey key)

Ensures the builder will create an RsaPrivateJwk for the specified Java RSAPrivateKey. If possible, it is recommended to also call the resulting builder's publicKey method with the private key's matching PublicKey for better performance. See the publicKey and PrivateJwk JavaDoc for more information.

Parameters:

key - the RSAPublicKey to represent as a RsaPublicJwk.

Returns:

the builder coerced as an RsaPrivateJwkBuilder.

key

EcPublicJwkBuilder key(ECPublicKey key)

Ensures the builder will create an EcPublicJwk for the specified Java ECPublicKey.

Parameters:

key - the ECPublicKey to represent as a EcPublicJwk.

Returns:

the builder coerced as an EcPublicJwkBuilder.

key

EcPrivateJwkBuilder key(ECPrivateKey key)

Ensures the builder will create an EcPrivateJwk for the specified Java ECPrivateKey. If possible, it is recommended to also call the resulting builder's publicKey method with the private key's matching PublicKey for better performance. See the publicKey and PrivateJwk JavaDoc for more information.

Parameters:

key - the ECPublicKey to represent as an EcPublicJwk.

Returns:

the builder coerced as a EcPrivateJwkBuilder.

key

<A extends PublicKey,B extends PrivateKey> PublicJwkBuilder<A,B,?,?,?,?> key(A key)
                                                                       throws UnsupportedKeyException

Ensures the builder will create a PublicJwk for the specified Java PublicKey argument. This method is provided for congruence with the other key methods and is expected to be used when the calling code has an untyped PublicKey reference. Based on the argument type, it will delegate to one of the following methods if possible:

• key(RSAPublicKey)
• key(ECPublicKey)
• octetKey(PublicKey)

If the specified key argument is not capable of being supported by one of those methods, an UnsupportedKeyException will be thrown.

Type Parameters

In addition to the public key type A, the public key's associated private key type B is parameterized as well. This ensures that any subsequent call to the builder's privateKey method will be type-safe. For example:

Jwks.builder().<EdECPublicKey, EdECPrivateKey>key(anEdECPublicKey)
     .privateKey(aPrivateKey) // <-- must be an EdECPrivateKey instance
     ... etc ...
     .build();

Type Parameters:

A - the type of PublicKey provided by the created public JWK.

B - the type of PrivateKey that may be paired with the PublicKey to produce a PrivateJwk if desired.

Parameters:

key - the PublicKey to represent as a PublicJwk.

Returns:

the builder coerced as a PublicJwkBuilder for continued method chaining.

Throws:

UnsupportedKeyException - if the specified key is not a supported type and cannot be used to delegate to other key methods.

See Also:

PublicJwk, PrivateJwk

key

<A extends PublicKey,B extends PrivateKey> PrivateJwkBuilder<B,A,?,?,?> key(B key)
                                                                      throws UnsupportedKeyException

Ensures the builder will create a PrivateJwk for the specified Java PrivateKey argument. This method is provided for congruence with the other key methods and is expected to be used when the calling code has an untyped PrivateKey reference. Based on the argument type, it will delegate to one of the following methods if possible:

• key(RSAPrivateKey)
• key(ECPrivateKey)
• octetKey(PrivateKey)

If the specified key argument is not capable of being supported by one of those methods, an UnsupportedKeyException will be thrown.

Type Parameters

In addition to the private key type B, the private key's associated public key type A is parameterized as well. This ensures that any subsequent call to the builder's publicKey method will be type-safe. For example:

Jwks.builder().<EdECPublicKey, EdECPrivateKey>key(anEdECPrivateKey)
     .publicKey(aPublicKey) // <-- must be an EdECPublicKey instance
     ... etc ...
     .build();

Type Parameters:

A - the type of PublicKey paired with the key argument to produce the PrivateJwk.

B - the type of the PrivateKey argument.

Parameters:

key - the PrivateKey to represent as a PrivateJwk.

Returns:

the builder coerced as a PrivateJwkBuilder for continued method chaining.

Throws:

UnsupportedKeyException - if the specified key is not a supported type and cannot be used to delegate to other key methods.

See Also:

PublicJwk, PrivateJwk

keyPair

<A extends PublicKey,B extends PrivateKey> PrivateJwkBuilder<B,A,?,?,?> keyPair(KeyPair keyPair)
                                                                          throws UnsupportedKeyException

Ensures the builder will create a PrivateJwk for the specified Java KeyPair argument. This method is provided for congruence with the other keyPair methods and is expected to be used when the calling code has a variable PrivateKey reference. Based on the argument's PrivateKey type, it will delegate to one of the following methods if possible:

• key(RSAPrivateKey)
• key(ECPrivateKey)
• octetKey(PrivateKey)

and automatically set the resulting builder's publicKey with the pair's PublicKey.

If the specified key argument is not capable of being supported by one of those methods, an UnsupportedKeyException will be thrown.

Type Parameters

In addition to the private key type B, the private key's associated public key type A is parameterized as well. This ensures that any subsequent call to the builder's publicKey method will be type-safe. For example:

Jwks.builder().<EdECPublicKey, EdECPrivateKey>keyPair(anEdECKeyPair)
     .publicKey(aPublicKey) // <-- must be an EdECPublicKey instance
     ... etc ...
     .build();

Type Parameters:

A - the keyPair argument's PublicKey type

B - the keyPair argument's PrivateKey type

Parameters:

keyPair - the KeyPair containing the public and private key

Returns:

the builder coerced as a PrivateJwkBuilder for continued method chaining.

Throws:

UnsupportedKeyException - if the specified KeyPair's keys are not supported and cannot be used to delegate to other key methods.

See Also:

PublicJwk, PrivateJwk

octetKey

<A extends PublicKey,B extends PrivateKey> OctetPublicJwkBuilder<A,B> octetKey(A key)

Ensures the builder will create an OctetPublicJwk for the specified Edwards-curve PublicKey argument. The PublicKey must be an instance of one of the following:

• java.security.interfaces.XECPublicKey, introduced in JDK 11
• java.security.interfaces.EdECPublicKey, introduced in JDK 15
• A PublicKey with a valid Edwards Curve DER encoding, such as those provided by BouncyCastle on earlier JDKs.

Type Parameters

In addition to the public key type A, the public key's associated private key type B is parameterized as well. This ensures that any subsequent call to the builder's privateKey method will be type-safe. For example:

Jwks.builder().<EdECPublicKey, EdECPrivateKey>key(anEdECPublicKey)
     .privateKey(aPrivateKey) // <-- must be an EdECPrivateKey instance
     ... etc ...
     .build();

Type Parameters:

A - the type of Edwards-curve PublicKey provided by the created public JWK.

B - the type of Edwards-curve PrivateKey that may be paired with the PublicKey to produce an OctetPrivateJwk if desired.

Parameters:

key - the Edwards-curve PublicKey to represent as an OctetPublicJwk.

Returns:

the builder coerced as a OctetPublicJwkBuilder for continued method chaining.

Throws:

UnsupportedKeyException - if the specified key is not a supported Edwards-curve key.

See Also:

java.security.interfaces.XECPublicKey, java.security.interfaces.EdECPublicKey

octetKey

<A extends PrivateKey,B extends PublicKey> OctetPrivateJwkBuilder<A,B> octetKey(A key)

Ensures the builder will create an OctetPrivateJwk for the specified Edwards-curve PrivateKey argument. The PrivateKey must be an instance of one of the following:

• java.security.interfaces.XECPrivateKey, introduced in JDK 11
• java.security.interfaces.EdECPrivateKey, introduced in JDK 15
• A PrivateKey with a valid Edwards Curve DER encoding, such as those provided by BouncyCastle on earlier JDKs.

Type Parameters

In addition to the private key type B, the private key's associated public key type A is parameterized as well. This ensures that any subsequent call to the builder's publicKey method will be type-safe. For example:

Jwks.builder().<EdECPublicKey, EdECPrivateKey>key(anEdECPrivateKey)
     .publicKey(aPublicKey) // <-- must be an EdECPublicKey instance
     ... etc ...
     .build();

Type Parameters:

A - the type of the Edwards-curve PrivateKey argument.

B - the type of Edwards-curve PublicKey paired with the key argument to produce the OctetPrivateJwk.

Parameters:

key - the Edwards-curve PrivateKey to represent as an OctetPrivateJwk.

Returns:

the builder coerced as an OctetPrivateJwkBuilder for continued method chaining.

Throws:

UnsupportedKeyException - if the specified key is not a supported Edwards-curve key.

See Also:

java.security.interfaces.XECPrivateKey, java.security.interfaces.EdECPrivateKey

octetChain

<A extends PublicKey,B extends PrivateKey> OctetPublicJwkBuilder<A,B> octetChain(List<X509Certificate> chain)

Ensures the builder will create an OctetPublicJwk for the specified Java X509Certificate chain. The first X509Certificate in the chain (at list index 0) MUST contain an Edwards-curve public key as defined by octetKey(PublicKey).

Type Parameters:

A - the type of Edwards-curve PublicKey contained in the first X509Certificate.

B - the type of Edwards-curve PrivateKey that may be paired with the PublicKey to produce an OctetPrivateJwk if desired.

Parameters:

chain - the X509Certificate chain to inspect to find the Edwards-curve PublicKey to represent as an OctetPublicJwk.

Returns:

the builder coerced as an OctetPublicJwkBuilder for continued method chaining.

octetKeyPair

<A extends PrivateKey,B extends PublicKey> OctetPrivateJwkBuilder<A,B> octetKeyPair(KeyPair keyPair)

Ensures the builder will create an OctetPrivateJwk for the specified Java Edwards-curve KeyPair. The pair's public key MUST be an Edwards-curve public key as defined by octetKey(PublicKey). The pair's private key MUST be an Edwards-curve private key as defined by octetKey(PrivateKey).

Type Parameters:

A - the type of Edwards-curve PublicKey contained in the key pair.

B - the type of the Edwards-curve PrivateKey contained in the key pair.

Parameters:

keyPair - the Edwards-curve KeyPair to represent as an OctetPrivateJwk.

Returns:

the builder coerced as an OctetPrivateJwkBuilder for continued method chaining.

Throws:

IllegalArgumentException - if the keyPair does not contain Edwards-curve public and private key instances.

ecChain

EcPublicJwkBuilder ecChain(List<X509Certificate> chain)

Ensures the builder will create an EcPublicJwk for the specified Java X509Certificate chain. The first X509Certificate in the chain (at list index 0) MUST contain an ECPublicKey instance when calling the certificate's getPublicKey() method.

Parameters:

chain - the X509Certificate chain to inspect to find the ECPublicKey to represent as a EcPublicJwk.

Returns:

the builder coerced as an EcPublicJwkBuilder.

ecKeyPair

EcPrivateJwkBuilder ecKeyPair(KeyPair keyPair)
                              throws IllegalArgumentException

Ensures the builder will create an EcPrivateJwk for the specified Java Elliptic Curve KeyPair. The pair's public key MUST be an ECPublicKey instance. The pair's private key MUST be an ECPrivateKey instance.

Parameters:

keyPair - the EC KeyPair to represent as an EcPrivateJwk.

Returns:

the builder coerced as an EcPrivateJwkBuilder.

Throws:

IllegalArgumentException - if the keyPair does not contain ECPublicKey and ECPrivateKey instances.

rsaChain

RsaPublicJwkBuilder rsaChain(List<X509Certificate> chain)

Ensures the builder will create an RsaPublicJwk for the specified Java X509Certificate chain. The first X509Certificate in the chain (at list index 0) MUST contain an RSAPublicKey instance when calling the certificate's getPublicKey() method.

Parameters:

chain - the X509Certificate chain to inspect to find the RSAPublicKey to represent as a RsaPublicJwk.

Returns:

the builder coerced as an RsaPublicJwkBuilder.

rsaKeyPair

RsaPrivateJwkBuilder rsaKeyPair(KeyPair keyPair)
                                throws IllegalArgumentException

Ensures the builder will create an RsaPrivateJwk for the specified Java RSA KeyPair. The pair's public key MUST be an RSAPublicKey instance. The pair's private key MUST be an RSAPrivateKey instance.

Parameters:

keyPair - the RSA KeyPair to represent as an RsaPrivateJwk.

Returns:

the builder coerced as an RsaPrivateJwkBuilder.

Throws:

IllegalArgumentException - if the keyPair does not contain RSAPublicKey and RSAPrivateKey instances.