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 key only.
  • Public key only.
  • Non-revoked key only.
  • Revoked key only.
  • Minimum, maximum or exact key sizes.
  • Any, unspecified, one or more curves for EC and OKP keys (crv).
  • X.509 certificate SHA-256 thumbprint.
  • With X.509 certificate only.

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

Version:
2024-11-01
Author:
Vladimir Dzhuvinov, Josh Cummings, Ben Arena

  • Constructor Details

    • 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 withUseOnly, boolean withIDOnly, 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.
      withUseOnly - true to match a key with a set use.
      withIDOnly - 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 withUseOnly, boolean withIDOnly, 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.
      withUseOnly - true to match a key with a set use.
      withIDOnly - 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

      @Deprecated public JWKMatcher(Set<KeyType> types, Set<KeyUse> uses, Set<KeyOperation> ops, Set<Algorithm> algs, Set<String> ids, boolean withUseOnly, boolean withIDOnly, boolean privateOnly, boolean publicOnly, int minSizeBits, int maxSizeBits, Set<Integer> sizesBits, Set<Curve> curves, Set<Base64URL> x5tS256s, boolean withX5COnly)
      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.
      withUseOnly - true to match a key with a set use.
      withIDOnly - 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.
      withX5COnly - true to match a key with a set X.509 certificate chain.

    • JWKMatcher

      public JWKMatcher(Set<KeyType> types, Set<KeyUse> uses, Set<KeyOperation> ops, Set<Algorithm> algs, Set<String> ids, boolean withUseOnly, boolean withIDOnly, boolean privateOnly, boolean publicOnly, boolean nonRevokedOnly, boolean revokedOnly, int minSizeBits, int maxSizeBits, Set<Integer> sizesBits, Set<Curve> curves, Set<Base64URL> x5tS256s, boolean withX5COnly)
      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.
      withUseOnly - true to match a key with a set use.
      withIDOnly - true to match a key with a set ID.
      privateOnly - true to match a private key only.
      publicOnly - true to match a public key only.
      nonRevokedOnly - true to match a non-revoked key only.
      revokedOnly - true to match a revoked key only.
      minSizeBits - The minimum key size in bits, zero implies no minimum size.
      maxSizeBits - The maximum key size in bits, zero implies no maximum size.
      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.
      withX5COnly - true to match a key with a set X.509 certificate chain.

  • Method Details

    • 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

      @Deprecated public boolean hasKeyUse()
      Deprecated.
      Returns true if keys with a specified use are matched.
      Returns:
      true if keys with a specified use are matched, else false.

    • isWithKeyUseOnly

      public boolean isWithKeyUseOnly()
      Returns true if keys with a specified use are matched.
      Returns:
      true if keys with a specified use are matched, else false.

    • hasKeyID

      @Deprecated public boolean hasKeyID()
      Deprecated.
      Returns true if keys with a specified ID are matched.
      Returns:
      true if keys with a specified ID are matched, else false.

    • isWithKeyIDOnly

      public boolean isWithKeyIDOnly()
      Returns true if keys with a specified ID are matched.
      Returns:
      true if keys with a specified 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 matched, else false.

    • isNonRevokedOnly

      public boolean isNonRevokedOnly()
      Returns true if only non-revoked keys are matched.
      Returns:
      true if only non-revoked keys are matched, else false.

    • isRevokedOnly

      public boolean isRevokedOnly()
      Returns true if only revoked keys are matched.
      Returns:
      true if only revoked keys are matched, 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

      @Deprecated public boolean hasX509CertChain()
      Deprecated.
      Returns true if keys with a specified X.509 certificate chain are matched.
      Returns:
      true if keys with a specified X.509 certificate are matched, else false.

    • isWithX509CertChainOnly

      public boolean isWithX509CertChainOnly()
      Returns true if keys with a specified X.509 certificate chain are matched.
      Returns:
      true if keys with a specified X.509 certificate chain 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