Package com.nimbusds.jose.jwk

Class JWKMatcher

java.lang.Object

com.nimbusds.jose.jwk.JWKMatcher

@Immutable
public class JWKMatcher
extends Object

JSON Web Key (JWK) matcher. May be used to ensure a JWK matches a set of application-specific criteria.

Supported key matching criteria:

• Any, unspecified, one or more key types (typ).
• Any, unspecified, one or more key uses (use).
• Any, unspecified, one or more key operations (key_ops).
• Any, unspecified, one or more key algorithms (alg).
• Any, unspecified, one or more key identifiers (kid).
• Private only key.
• Public only key.
• Minimum, maximum or exact key sizes.
• Any, unspecified, one or more curves for EC and OKP keys (crv).
• X.509 certificate SHA-256 thumbprint.
• Has X.509 certificate.

Matching by JWK thumbprint (RFC 7638), X.509 certificate URL and X.509 certificate chain is not supported.

Version:

2022-05-28

Author:

Vladimir Dzhuvinov, Josh Cummings, Ben Arena

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	JWKMatcher.Builder	Builder for constructing JWK matchers.

Constructor Summary

Constructors

Constructor	Description
JWKMatcher(Set<KeyType> types, Set<KeyUse> uses, Set<KeyOperation> ops, Set<Algorithm> algs, Set<String> ids, boolean privateOnly, boolean publicOnly)	Deprecated.
JWKMatcher(Set<KeyType> types, Set<KeyUse> uses, Set<KeyOperation> ops, Set<Algorithm> algs, Set<String> ids, boolean hasUse, boolean hasID, boolean privateOnly, boolean publicOnly, int minSizeBits, int maxSizeBits, Set<Integer> sizesBits, Set<Curve> curves)	Deprecated.
JWKMatcher(Set<KeyType> types, Set<KeyUse> uses, Set<KeyOperation> ops, Set<Algorithm> algs, Set<String> ids, boolean hasUse, boolean hasID, boolean privateOnly, boolean publicOnly, int minSizeBits, int maxSizeBits, Set<Integer> sizesBits, Set<Curve> curves, Set<Base64URL> x5tS256s)	Deprecated.
JWKMatcher(Set<KeyType> types, Set<KeyUse> uses, Set<KeyOperation> ops, Set<Algorithm> algs, Set<String> ids, boolean hasUse, boolean hasID, boolean privateOnly, boolean publicOnly, int minSizeBits, int maxSizeBits, Set<Integer> sizesBits, Set<Curve> curves, Set<Base64URL> x5tS256s, boolean hasX5C)	Creates a new JSON Web Key (JWK) matcher.
JWKMatcher(Set<KeyType> types, Set<KeyUse> uses, Set<KeyOperation> ops, Set<Algorithm> algs, Set<String> ids, boolean privateOnly, boolean publicOnly, int minSizeBits, int maxSizeBits)	Deprecated.
JWKMatcher(Set<KeyType> types, Set<KeyUse> uses, Set<KeyOperation> ops, Set<Algorithm> algs, Set<String> ids, boolean privateOnly, boolean publicOnly, int minSizeBits, int maxSizeBits, Set<Curve> curves)	Deprecated.
JWKMatcher(Set<KeyType> types, Set<KeyUse> uses, Set<KeyOperation> ops, Set<Algorithm> algs, Set<String> ids, boolean privateOnly, boolean publicOnly, int minSizeBits, int maxSizeBits, Set<Integer> sizesBits, Set<Curve> curves)	Deprecated.

Method Summary

Modifier and Type	Method	Description
static JWKMatcher	forJWEHeader(JWEHeader jweHeader)	Returns a JWKMatcher based on the given JWEHeader.
static JWKMatcher	forJWSHeader(JWSHeader jwsHeader)	Returns a JWKMatcher based on the given JWSHeader.
Set<Algorithm>	getAlgorithms()	Returns the JOSE algorithms to match.
Set<Curve>	getCurves()	Returns the curves to match (for EC and OKP keys).
Set<String>	getKeyIDs()	Returns the key IDs to match.
Set<KeyOperation>	getKeyOperations()	Returns the key operations to match.
Set<Integer>	getKeySizes()	Returns the key sizes.
Set<KeyType>	getKeyTypes()	Returns the key types to match.
Set<KeyUse>	getKeyUses()	Returns the public key uses to match.
int	getMaxKeySize()	Returns the maximum key size.
int	getMaxSize()	Deprecated.
int	getMinKeySize()	Returns the minimum key size.
int	getMinSize()	Deprecated.
Set<Base64URL>	getX509CertSHA256Thumbprints()	Returns the X.509 certificate SHA-256 thumbprints to match.
boolean	hasKeyID()	Returns true if keys with a set use are matched.
boolean	hasKeyUse()	Returns true if keys with a set use are matched.
boolean	hasX509CertChain()	Returns true if keys with a set X.509 certificate chain are matched.
boolean	isPrivateOnly()	Returns true if only private keys are matched.
boolean	isPublicOnly()	Returns true if only public keys are matched.
boolean	matches(JWK key)	Returns true if the specified JWK matches.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

JWKMatcher

@Deprecated
public JWKMatcher(Set<KeyType> types,
                  Set<KeyUse> uses,
                  Set<KeyOperation> ops,
                  Set<Algorithm> algs,
                  Set<String> ids,
                  boolean privateOnly,
                  boolean publicOnly)

Deprecated.

Creates a new JSON Web Key (JWK) matcher.

Parameters:

types - The key types to match, null if not specified.

uses - The public key uses to match, null if not specified.

ops - The key operations to match, null if not specified.

algs - The JOSE algorithms to match, null if not specified.

ids - The key IDs to match, null if not specified.

privateOnly - true to match a private key.

publicOnly - true to match a public only key.

JWKMatcher

@Deprecated
public JWKMatcher(Set<KeyType> types,
                  Set<KeyUse> uses,
                  Set<KeyOperation> ops,
                  Set<Algorithm> algs,
                  Set<String> ids,
                  boolean privateOnly,
                  boolean publicOnly,
                  int minSizeBits,
                  int maxSizeBits)

Deprecated.

Creates a new JSON Web Key (JWK) matcher.

Parameters:

types - The key types to match, null if not specified.

uses - The public key uses to match, null if not specified.

ops - The key operations to match, null if not specified.

algs - The JOSE algorithms to match, null if not specified.

ids - The key IDs to match, null if not specified.

privateOnly - true to match a private key.

publicOnly - true to match a public only key.

minSizeBits - The minimum key size in bits, zero implies no minimum size limit.

maxSizeBits - The maximum key size in bits, zero implies no maximum size limit.

JWKMatcher

@Deprecated
public JWKMatcher(Set<KeyType> types,
                  Set<KeyUse> uses,
                  Set<KeyOperation> ops,
                  Set<Algorithm> algs,
                  Set<String> ids,
                  boolean privateOnly,
                  boolean publicOnly,
                  int minSizeBits,
                  int maxSizeBits,
                  Set<Curve> curves)

Deprecated.

Creates a new JSON Web Key (JWK) matcher.

Parameters:

types - The key types to match, null if not specified.

uses - The public key uses to match, null if not specified.

ops - The key operations to match, null if not specified.

algs - The JOSE algorithms to match, null if not specified.

ids - The key IDs to match, null if not specified.

privateOnly - true to match a private key.

publicOnly - true to match a public only key.

minSizeBits - The minimum key size in bits, zero implies no minimum size limit.

maxSizeBits - The maximum key size in bits, zero implies no maximum size limit.

curves - The curves to match (for EC keys), null if not specified.

JWKMatcher

@Deprecated
public JWKMatcher(Set<KeyType> types,
                  Set<KeyUse> uses,
                  Set<KeyOperation> ops,
                  Set<Algorithm> algs,
                  Set<String> ids,
                  boolean privateOnly,
                  boolean publicOnly,
                  int minSizeBits,
                  int maxSizeBits,
                  Set<Integer> sizesBits,
                  Set<Curve> curves)

Deprecated.

Creates a new JSON Web Key (JWK) matcher.

Parameters:

types - The key types to match, null if not specified.

uses - The public key uses to match, null if not specified.

ops - The key operations to match, null if not specified.

algs - The JOSE algorithms to match, null if not specified.

ids - The key IDs to match, null if not specified.

privateOnly - true to match a private key.

publicOnly - true to match a public only key.

minSizeBits - The minimum key size in bits, zero implies no minimum size limit.

maxSizeBits - The maximum key size in bits, zero implies no maximum size limit.

sizesBits - The key sizes in bits, null if not specified.

curves - The curves to match (for EC and OKP keys), null if not specified.

JWKMatcher

@Deprecated
public JWKMatcher(Set<KeyType> types,
                  Set<KeyUse> uses,
                  Set<KeyOperation> ops,
                  Set<Algorithm> algs,
                  Set<String> ids,
                  boolean hasUse,
                  boolean hasID,
                  boolean privateOnly,
                  boolean publicOnly,
                  int minSizeBits,
                  int maxSizeBits,
                  Set<Integer> sizesBits,
                  Set<Curve> curves)

Deprecated.

Creates a new JSON Web Key (JWK) matcher.

Parameters:

types - The key types to match, null if not specified.

uses - The public key uses to match, null if not specified.

ops - The key operations to match, null if not specified.

algs - The JOSE algorithms to match, null if not specified.

ids - The key IDs to match, null if not specified.

hasUse - true to match a key with a set use.

hasID - true to match a key with a set ID.

privateOnly - true to match a private key.

publicOnly - true to match a public only key.

minSizeBits - The minimum key size in bits, zero implies no minimum size limit.

maxSizeBits - The maximum key size in bits, zero implies no maximum size limit.

sizesBits - The key sizes in bits, null if not specified.

curves - The curves to match (for EC and OKP keys), null if not specified.

JWKMatcher

@Deprecated
public JWKMatcher(Set<KeyType> types,
                  Set<KeyUse> uses,
                  Set<KeyOperation> ops,
                  Set<Algorithm> algs,
                  Set<String> ids,
                  boolean hasUse,
                  boolean hasID,
                  boolean privateOnly,
                  boolean publicOnly,
                  int minSizeBits,
                  int maxSizeBits,
                  Set<Integer> sizesBits,
                  Set<Curve> curves,
                  Set<Base64URL> x5tS256s)

Deprecated.

Creates a new JSON Web Key (JWK) matcher.

Parameters:

types - The key types to match, null if not specified.

uses - The public key uses to match, null if not specified.

ops - The key operations to match, null if not specified.

algs - The JOSE algorithms to match, null if not specified.

ids - The key IDs to match, null if not specified.

hasUse - true to match a key with a set use.

hasID - true to match a key with a set ID.

privateOnly - true to match a private key.

publicOnly - true to match a public only key.

minSizeBits - The minimum key size in bits, zero implies no minimum size limit.

maxSizeBits - The maximum key size in bits, zero implies no maximum size limit.

sizesBits - The key sizes in bits, null if not specified.

curves - The curves to match (for EC and OKP keys), null if not specified.

x5tS256s - The X.509 certificate thumbprints to match, null if not specified.

JWKMatcher

public JWKMatcher(Set<KeyType> types,
                  Set<KeyUse> uses,
                  Set<KeyOperation> ops,
                  Set<Algorithm> algs,
                  Set<String> ids,
                  boolean hasUse,
                  boolean hasID,
                  boolean privateOnly,
                  boolean publicOnly,
                  int minSizeBits,
                  int maxSizeBits,
                  Set<Integer> sizesBits,
                  Set<Curve> curves,
                  Set<Base64URL> x5tS256s,
                  boolean hasX5C)

Creates a new JSON Web Key (JWK) matcher.

Parameters:

types - The key types to match, null if not specified.

uses - The public key uses to match, null if not specified.

ops - The key operations to match, null if not specified.

algs - The JOSE algorithms to match, null if not specified.

ids - The key IDs to match, null if not specified.

hasUse - true to match a key with a set use.

hasID - true to match a key with a set ID.

privateOnly - true to match a private key.

publicOnly - true to match a public only key.

minSizeBits - The minimum key size in bits, zero implies no minimum size limit.

maxSizeBits - The maximum key size in bits, zero implies no maximum size limit.

sizesBits - The key sizes in bits, null if not specified.

curves - The curves to match (for EC and OKP keys), null if not specified.

x5tS256s - The X.509 certificate thumbprints to match, null if not specified.

hasX5C - true to match a key with a set X.509 certificate chain.

Method Detail

forJWEHeader

public static JWKMatcher forJWEHeader(JWEHeader jweHeader)

Returns a JWKMatcher based on the given JWEHeader.

The JWKMatcher is configured as follows:

• The key type to match is determined by the JWE algorithm (alg).
• The key ID to match is set by the JWE header key ID (kid) parameter (if set).
• The key uses to match are set to encryption or not specified.
• The key algorithm to match is set to the JWE algorithm (alg) or not specified.

Other JWE header parameters are not taken into account.

Parameters:

jweHeader - The header to use.

Returns:

A JWKMatcher based on the given header.

forJWSHeader

public static JWKMatcher forJWSHeader(JWSHeader jwsHeader)

Returns a JWKMatcher based on the given JWSHeader.

The JWKMatcher is configured as follows:

• The key type to match is determined by the JWS algorithm (alg).
• The key ID to match is set by the JWS header key ID (kid) parameter (if set).
• The key uses to match are set to signature or not specified.
• The key algorithm to match is set to the JWS algorithm (alg) or not specified.
• The X.509 certificate SHA-256 thumbprint to match is set to the x5t#S256 parameter (if set).

Other JWS header parameters are not taken into account.

Parameters:

jwsHeader - The header to use.

Returns:

A JWKMatcher based on the given header, null if the JWS algorithm is not supported.

getKeyTypes

public Set<KeyType> getKeyTypes()

Returns the key types to match.

Returns:

The key types, null if not specified.

getKeyUses

public Set<KeyUse> getKeyUses()

Returns the public key uses to match.

Returns:

The public key uses, null if not specified.

getKeyOperations

public Set<KeyOperation> getKeyOperations()

Returns the key operations to match.

Returns:

The key operations, null if not specified.

getAlgorithms

public Set<Algorithm> getAlgorithms()

Returns the JOSE algorithms to match.

Returns:

The JOSE algorithms, null if not specified.

getKeyIDs

public Set<String> getKeyIDs()

Returns the key IDs to match.

Returns:

The key IDs, null if not specified.

hasKeyUse

public boolean hasKeyUse()

Returns true if keys with a set use are matched.

Returns:

true if keys with a set use are matched, else false.

hasKeyID

public boolean hasKeyID()

Returns true if keys with a set use are matched.

Returns:

true if keys with a set ID are matched, else false.

isPrivateOnly

public boolean isPrivateOnly()

Returns true if only private keys are matched.

Returns:

true if only private keys are matched, else false.

isPublicOnly

public boolean isPublicOnly()

Returns true if only public keys are matched.

Returns:

true if only public keys are selected, else false.

getMinSize

@Deprecated
public int getMinSize()

Deprecated.

Returns the minimum key size. Use getMinKeySize() instead.

Returns:

The minimum key size in bits, zero implies no minimum size limit.

getMinKeySize

public int getMinKeySize()

Returns the minimum key size.

Returns:

The minimum key size in bits, zero implies no minimum size limit.

getMaxSize

@Deprecated
public int getMaxSize()

Deprecated.

Returns the maximum key size. Use getMaxKeySize() instead.

Returns:

The maximum key size in bits, zero implies no maximum size limit.

getMaxKeySize

public int getMaxKeySize()

Returns the maximum key size.

Returns:

The maximum key size in bits, zero implies no maximum size limit.

getKeySizes

public Set<Integer> getKeySizes()

Returns the key sizes.

Returns:

The key sizes in bits, null if not specified.

getCurves

public Set<Curve> getCurves()

Returns the curves to match (for EC and OKP keys).

Returns:

The curves, null if not specified.

getX509CertSHA256Thumbprints

public Set<Base64URL> getX509CertSHA256Thumbprints()

Returns the X.509 certificate SHA-256 thumbprints to match.

Returns:

The thumbprints, null if not specified.

hasX509CertChain

public boolean hasX509CertChain()

Returns true if keys with a set X.509 certificate chain are matched.

Returns:

true if keys with a set X.509 certificate are matched, else false.

matches

public boolean matches(JWK key)

Returns true if the specified JWK matches.

Parameters:

key - The JSON Web Key (JWK). Must not be null.

Returns:

true if the JWK matches, else false.

toString

public String toString()

Overrides:

toString in class Object