io.jsonwebtoken.security

Interface Jwk<K extends Key>

Type Parameters:

K - The type of Java Key represented by this JWK

All Superinterfaces:

Identifiable, Map<String,Object>

All Known Subinterfaces:

AsymmetricJwk<K>, EcPrivateJwk, EcPublicJwk, OctetPrivateJwk<K,L>, OctetPublicJwk<K>, PrivateJwk<K,L,M>, PublicJwk<K>, RsaPrivateJwk, RsaPublicJwk, SecretJwk

public interface Jwk<K extends Key>
extends Identifiable, Map<String,Object>

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 Jwk interface represents properties common to all JWKs. Subtypes will have additional properties specific to different types of cryptographic keys (e.g. Secret, Asymmetric, RSA, Elliptic Curve, etc).

Immutability

JWKs are immutable and cannot be changed after they are created. Jwk extends the Map interface purely out of convenience: to allow easy marshalling to JSON as well as name/value pair access and key/value iteration, and other conveniences provided by the Map interface. Attempting to call any of the Map interface's mutation methods however (such as put, remove, clear, etc) will throw an UnsupportedOperationException.

Identification

Jwk extends Identifiable to support the JWK kid parameter. Calling aJwk.getId() is the type-safe idiomatic approach to the alternative equivalent of aJwk.get("kid"). Either approach will return an id if one was originally set on the JWK, or null if an id does not exist.

Private and Secret Value Safety

JWKs often represent secret or private key data which should never be exposed publicly, nor mistakenly printed to application logs or System.out.println calls. As a result, all JJWT JWK private or secret values are 'wrapped' in a Supplier instance to ensure any attempt to call toString() on the value will print a redacted value instead of an actual private or secret value.

For example, a SecretJwk will have an internal "k" member whose value reflects raw key material that should always be kept secret. If the following is called:

 System.out.println(aSecretJwk.get("k"));

You would see the following:

 <redacted>

instead of the actual/raw k value.

Similarly, if attempting to print the entire JWK:

 System.out.println(aSecretJwk);

You would see the following substring in the output:

 k=<redacted>

instead of the actual/raw k value.

Finally, because all private or secret values are wrapped as Supplier instances, if you really wanted the real internal value, you could just call the supplier's get() method:

 String k = ((Supplier<String>)aSecretJwk.get("k")).get();

but BE CAREFUL: obtaining the raw value in your application code exposes greater security risk - you must ensure to keep that value safe and out of console or log output. It is almost always better to interact with the JWK's toKey() instance directly instead of accessing JWK internal serialization parameters.

Since:

0.12.0

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Method Summary

Methods

Modifier and Type	Method and Description
String	getAlgorithm() Returns the JWK alg (Algorithm) value or null if not present.
Set<KeyOperation>	getOperations() Returns the JWK key_ops (Key Operations) parameter values or null if not present.
String	getType() Returns the required JWK kty (Key Type) parameter value.
JwkThumbprint	thumbprint() Computes and returns the canonical JWK Thumbprint of this JWK using the SHA-256 hash algorithm.
JwkThumbprint	thumbprint(HashAlgorithm alg) Computes and returns the canonical JWK Thumbprint of this JWK using the specified hash algorithm.
K	toKey() Represents the JWK as its corresponding Java Key instance for use with Java cryptographic APIs.

Methods inherited from interface io.jsonwebtoken.Identifiable

getId

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Method Detail

getAlgorithm

String getAlgorithm()

Returns the JWK alg (Algorithm) value or null if not present.

Returns:

the JWK alg value or null if not present.

getOperations

Set<KeyOperation> getOperations()

Returns the JWK key_ops (Key Operations) parameter values or null if not present. All JWK standard Key Operations are available via the Jwks.OP registry, but other (custom) values MAY be present in the returned set.

Returns:

the JWK key_ops value or null if not present.

See Also:

key_ops(Key Operations) Parameter

getType

String getType()

Returns the required JWK kty (Key Type) parameter value. A value is required and may not be null.

The JWA specification defines the following kty values:

JWK Key Types

Value	Key Type
EC	Elliptic Curve [DSS]
RSA	RSA [RFC 3447]
oct	Octet sequence (used to represent symmetric keys)
OKP	Octet Key Pair (used to represent Edwards Elliptic Curve keys)

Returns:

the JWK kty (Key Type) value.

thumbprint

JwkThumbprint thumbprint()

Computes and returns the canonical JWK Thumbprint of this JWK using the SHA-256 hash algorithm. This is a convenience method that delegates to thumbprint(HashAlgorithm) with a SHA-256 HashAlgorithm instance.

Returns:

the canonical JWK Thumbprint of this JWK using the SHA-256 hash algorithm.

See Also:

thumbprint(HashAlgorithm)

thumbprint

JwkThumbprint thumbprint(HashAlgorithm alg)

Computes and returns the canonical JWK Thumbprint of this JWK using the specified hash algorithm.

Parameters:

alg - the hash algorithm to use to compute the digest of the canonical JWK Thumbprint JSON form of this JWK.

Returns:

the canonical JWK Thumbprint of this JWK using the specified hash algorithm.

toKey

K toKey()

Represents the JWK as its corresponding Java Key instance for use with Java cryptographic APIs.

Returns:

the JWK's corresponding Java Key instance for use with Java cryptographic APIs.