io.jsonwebtoken.security

Interface JwkBuilder<K extends Key,J extends Jwk<K>,T extends JwkBuilder<K,J,T>>

Type Parameters:

K - the type of Java Key represented by the constructed JWK.

J - the type of Jwk created by the builder

T - the type of the builder, for subtype method chaining

All Superinterfaces:

Builder<J>, KeyOperationPolicied<T>, MapMutator<String,Object,T>, SecurityBuilder<J,T>

All Known Subinterfaces:

AsymmetricJwkBuilder<K,J,T>, DynamicJwkBuilder<K,J>, EcPrivateJwkBuilder, EcPublicJwkBuilder, OctetPrivateJwkBuilder<K,L>, OctetPublicJwkBuilder<A,B>, PrivateJwkBuilder<K,L,J,M,T>, PublicJwkBuilder<K,L,J,M,P,T>, RsaPrivateJwkBuilder, RsaPublicJwkBuilder, SecretJwkBuilder

public interface JwkBuilder<K extends Key,J extends Jwk<K>,T extends JwkBuilder<K,J,T>>
extends MapMutator<String,Object,T>, SecurityBuilder<J,T>, KeyOperationPolicied<T>

A SecurityBuilder that produces a JWK. A JWK is an immutable set of name/value pairs that represent a cryptographic key as defined by RFC 7517: JSON Web Key (JWK). The JwkBuilder interface represents common JWK properties that may be specified for any type of JWK. Builder subtypes support additional JWK properties specific to different types of cryptographic keys (e.g. Secret, Asymmetric, RSA, Elliptic Curve, etc).

Since:

0.12.0

See Also:

SecretJwkBuilder, RsaPublicJwkBuilder, RsaPrivateJwkBuilder, EcPublicJwkBuilder, EcPrivateJwkBuilder, OctetPublicJwkBuilder, OctetPrivateJwkBuilder

Method Summary

Methods

Modifier and Type	Method and Description
T	algorithm(String alg) Sets the JWK alg (Algorithm) Parameter.
T	id(String kid) Sets the JWK kid (Key ID) Parameter.
T	idFromThumbprint() Sets the JWK's kid value to be the Base64URL-encoding of its SHA-256 thumbprint.
T	idFromThumbprint(HashAlgorithm alg) Sets the JWK's kid value to be the Base64URL-encoding of its thumbprint using the specified HashAlgorithm.
NestedCollection<KeyOperation,T>	operations() Configures the key operations for which the key is intended to be used.

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

algorithm

T algorithm(String alg)
                                      throws IllegalArgumentException

Sets the JWK alg (Algorithm) Parameter.

The alg (algorithm) parameter identifies the algorithm intended for use with the key. The value specified should either be one of the values in the IANA JSON Web Signature and Encryption Algorithms registry or be a value that contains a Collision-Resistant Name. The alg must be a CaSe-SeNsItIvE ASCII string.

Parameters:

alg - the JWK alg value.

Returns:

the builder for method chaining.

Throws:

IllegalArgumentException - if alg is null or empty.

id

T id(String kid)
                               throws IllegalArgumentException

Sets the JWK kid (Key ID) Parameter.

The kid (key ID) parameter is used to match a specific key. This is used, for instance, to choose among a set of keys within a JWK Set during key rollover. The structure of the kid value is unspecified. When kid values are used within a JWK Set, different keys within the JWK Set SHOULD use distinct kid values. (One example in which different keys might use the same kid value is if they have different kty (key type) values but are considered to be equivalent alternatives by the application using them.)

The kid value is a CaSe-SeNsItIvE string, and it is optional. When used with JWS or JWE, the kid value is used to match a JWS or JWE kid Header Parameter value.

Parameters:

kid - the JWK kid value.

Returns:

the builder for method chaining.

Throws:

IllegalArgumentException - if the argument is null or empty.

idFromThumbprint

T idFromThumbprint()

Sets the JWK's kid value to be the Base64URL-encoding of its SHA-256 thumbprint. That is, the constructed JWK's kid value will equal jwk.thumbprint(Jwks.HASH.SHA256).toString().

This is a convenience method that delegates to idFromThumbprint(HashAlgorithm) using Jwks.HASH.SHA256.

Returns:

the builder for method chaining.

idFromThumbprint

T idFromThumbprint(HashAlgorithm alg)

Sets the JWK's kid value to be the Base64URL-encoding of its thumbprint using the specified HashAlgorithm. That is, the constructed JWK's kid value will equal thumbprint(alg).toString().

Parameters:

alg - the hash algorithm to use to compute the thumbprint.

Returns:

the builder for method chaining.

See Also:

Jwks.HASH

operations

NestedCollection<KeyOperation,T> operations()

Configures the key operations for which the key is intended to be used. When finished, use the collection's and() method to return to the JWK builder, for example:

 jwkBuilder.operations().add(aKeyOperation).and() // etc...

The and() method will throw an IllegalArgumentException if any of the specified KeyOperations are not permitted by the JWK's operationPolicy. See that documentation for more information on security vulnerabilities when using the same key with multiple algorithms.

Standard KeyOperations and Overrides

All RFC-standard JWK Key Operations in the Jwks.OP registry are supported via the builder's default operationPolicy, but other (custom) values MAY be specified (for example, using a Jwks.OP.builder()).

If the JwkBuilder is being used to rebuild or parse an existing JWK however, any custom operations should be enabled by configuring an operationPolicy that includes the custom values (e.g. via Jwks.OP.policy().add(customKeyOperation)).

For best interoperability with other applications however, it is recommended to use only the Jwks.OP constants.

Returns:

the NestedCollection to use for key_ops configuration.

See Also:

Jwks.OP, RFC 7517: key_ops (Key Operations) Parameter