Package com.nimbusds.jose.jwk

Class JWK

  • All Implemented Interfaces:
    Serializable
    Direct Known Subclasses:
    ECKey, OctetKeyPair, OctetSequenceKey, RSAKey
    public abstract class JWK
extends Object
implements Serializable
    The base abstract class for JSON Web Keys (JWKs). It serialises to a JSON object.

    The following JSON object members are common to all JWK types:

    Example JWK (of the Elliptic Curve type): 

     {
   "kty" : "EC",
   "crv" : "P-256",
   "x"   : "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
   "y"   : "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
   "use" : "enc",
   "kid" : "1"
 }
    Version:
    2022-12-26
    Author:
    Vladimir Dzhuvinov, Justin Richer, Stefan Larsson
    See Also:
    Serialized Form

    • Constructor Detail

      • JWK

        @Deprecated
protected JWK​(KeyType kty,
              KeyUse use,
              Set<KeyOperation> ops,
              Algorithm alg,
              String kid,
              URI x5u,
              Base64URL x5t,
              Base64URL x5t256,
              List<Base64> x5c,
              KeyStore ks)
        Deprecated.
        Creates a new JSON Web Key (JWK).
        Parameters:
        kty - The key type. Must not be null.
        use - The key use, null if not specified or if the key is intended for signing as well as encryption.
        ops - The key operations, null if not specified.
        alg - The intended JOSE algorithm for the key, null if not specified.
        kid - The key ID, null if not specified.
        x5u - The X.509 certificate URL, null if not specified.
        x5t - The X.509 certificate thumbprint, null if not specified.
        x5t256 - The X.509 certificate SHA-256 thumbprint, null if not specified.
        x5c - The X.509 certificate chain, null if not specified.
        ks - Reference to the underlying key store, null if none.

      • JWK

        protected JWK​(KeyType kty,
              KeyUse use,
              Set<KeyOperation> ops,
              Algorithm alg,
              String kid,
              URI x5u,
              Base64URL x5t,
              Base64URL x5t256,
              List<Base64> x5c,
              Date exp,
              Date nbf,
              Date iat,
              KeyStore ks)
        Creates a new JSON Web Key (JWK).
        Parameters:
        kty - The key type. Must not be null.
        use - The key use, null if not specified or if the key is intended for signing as well as encryption.
        ops - The key operations, null if not specified.
        alg - The intended JOSE algorithm for the key, null if not specified.
        kid - The key ID, null if not specified.
        x5u - The X.509 certificate URL, null if not specified.
        x5t - The X.509 certificate thumbprint, null if not specified.
        x5t256 - The X.509 certificate SHA-256 thumbprint, null if not specified.
        x5c - The X.509 certificate chain, null if not specified.
        exp - The key expiration time, null if not specified.
        nbf - The key not-before time, null if not specified.
        iat - The key issued-at time, null if not specified.
        ks - Reference to the underlying key store, null if none.

    • Method Detail

      • getKeyType

        public KeyType getKeyType()
        Gets the type (kty) of this JWK.
        Returns:
        The key type.

      • getKeyUse

        public KeyUse getKeyUse()
        Gets the use (use) of this JWK.
        Returns:
        The key use, null if not specified or if the key is intended for signing as well as encryption.

      • getKeyOperations

        public Set<KeyOperation> getKeyOperations()
        Gets the operations (key_ops) for this JWK.
        Returns:
        The key operations, null if not specified.

      • getAlgorithm

        public Algorithm getAlgorithm()
        Gets the intended JOSE algorithm (alg) for this JWK.
        Returns:
        The intended JOSE algorithm, null if not specified.

      • getKeyID

        public String getKeyID()
        Gets the ID (kid) of this JWK. The key ID can be used to match a specific key. This can be used, for instance, to choose a key within a JWKSet during key rollover. The key ID may also correspond to a JWS/JWE kid header parameter value.
        Returns:
        The key ID, null if not specified.

      • getX509CertURL

        public URI getX509CertURL()
        Gets the X.509 certificate URL (x5u) of this JWK.
        Returns:
        The X.509 certificate URL, null if not specified.

      • getX509CertThumbprint

        @Deprecated
public Base64URL getX509CertThumbprint()
        Deprecated.
        Gets the X.509 certificate SHA-1 thumbprint (x5t) of this JWK.
        Returns:
        The X.509 certificate SHA-1 thumbprint, null if not specified.

      • getX509CertSHA256Thumbprint

        public Base64URL getX509CertSHA256Thumbprint()
        Gets the X.509 certificate SHA-256 thumbprint (x5t#S256) of this JWK.
        Returns:
        The X.509 certificate SHA-256 thumbprint, null if not specified.

      • getX509CertChain

        public List<Base64> getX509CertChain()
        Gets the X.509 certificate chain (x5c) of this JWK.
        Returns:
        The X.509 certificate chain as a unmodifiable list, null if not specified.

      • getParsedX509CertChain

        public List<X509Certificate> getParsedX509CertChain()
        Gets the parsed X.509 certificate chain (x5c) of this JWK.
        Returns:
        The X.509 certificate chain as a unmodifiable list, null if not specified.

      • getExpirationTime

        public Date getExpirationTime()
        Gets the expiration time (exp) if this JWK.
        Returns:
        The expiration time, null if not specified.

      • getNotBeforeTime

        public Date getNotBeforeTime()
        Gets the not-before (nbf) of this JWK.
        Returns:
        The not-before time, null if not specified.

      • getIssueTime

        public Date getIssueTime()
        Gets the issued-at (iat) time of this JWK.
        Returns:
        The issued-at time, null if not specified.

      • getKeyStore

        public KeyStore getKeyStore()
        Returns a reference to the underlying key store.
        Returns:
        The underlying key store, null if none.

      • getRequiredParams

        public abstract LinkedHashMap<String,​?> getRequiredParams()
        Returns the required JWK parameters. Intended as input for JWK thumbprint computation. See RFC 7638 for more information.
        Returns:
        The required JWK parameters, sorted alphanumerically by key name and ready for JSON serialisation.

      • computeThumbprint

        public Base64URL computeThumbprint()
                            throws JOSEException
        Computes the SHA-256 thumbprint of this JWK. See RFC 7638 for more information.
        Returns:
        The SHA-256 thumbprint.
        Throws:
        JOSEException - If the SHA-256 hash algorithm is not supported.

      • computeThumbprint

        public Base64URL computeThumbprint​(String hashAlg)
                            throws JOSEException
        Computes the thumbprint of this JWK using the specified hash algorithm. See RFC 7638 for more information.
        Parameters:
        hashAlg - The hash algorithm. Must not be null.
        Returns:
        The SHA-256 thumbprint.
        Throws:
        JOSEException - If the hash algorithm is not supported.

      • computeThumbprintURI

        public ThumbprintURI computeThumbprintURI()
                                   throws JOSEException
        Computes the SHA-256 thumbprint URI of this JWK. See RFC 7638 and draft-ietf-oauth-jwk-thumbprint-uri for more information.
        Returns:
        The SHA-256 thumbprint URI.
        Throws:
        JOSEException - If the SHA-256 hash algorithm is not supported.

      • isPrivate

        public abstract boolean isPrivate()
        Returns true if this JWK contains private or sensitive (non-public) parameters.
        Returns:
        true if this JWK contains private parameters, else false.

      • toPublicJWK

        public abstract JWK toPublicJWK()
        Creates a copy of this JWK with all private or sensitive parameters removed.
        Returns:
        The newly created public JWK, or null if none can be created.

      • size

        public abstract int size()
        Returns the size of this JWK.
        Returns:
        The JWK size, in bits.

      • toRSAKey

        public RSAKey toRSAKey()
        Casts this JWK to an RSA JWK.
        Returns:
        The RSA JWK.

      • toECKey

        public ECKey toECKey()
        Casts this JWK to an EC JWK.
        Returns:
        The EC JWK.

      • toJSONObject

        public Map<String,​Object> toJSONObject()
        Returns a JSON object representation of this JWK. This method is intended to be called from extending classes.

        Example: 

         {
   "kty" : "RSA",
   "use" : "sig",
   "kid" : "fd28e025-8d24-48bc-a51a-e2ffc8bc274b"
 }
        Returns:
        The JSON object representation.

      • toJSONString

        public String toJSONString()
        Returns the JSON object string representation of this JWK.
        Returns:
        The JSON object string representation.

      • parse

        public static JWK parse​(String s)
                 throws ParseException
        Parses a JWK from the specified JSON object string representation. The JWK must be an ECKey, an RSAKey, or a OctetSequenceKey.
        Parameters:
        s - The JSON object string to parse. Must not be null.
        Returns:
        The JWK.
        Throws:
        ParseException - If the string couldn't be parsed to a supported JWK.

      • parse

        public static JWK parse​(X509Certificate cert)
                 throws JOSEException
        Parses a public RSA or EC JWK from the specified X.509 certificate. Requires BouncyCastle.

        Important: The X.509 certificate is not validated!

        Sets the following JWK parameters:

        • For an EC key the curve is obtained from the subject public key info algorithm parameters.
        • The JWK use inferred by KeyUse.from(java.security.cert.X509Certificate).
        • The JWK ID from the X.509 serial number (in base 10).
        • The JWK X.509 certificate chain (this certificate only).
        • The JWK X.509 certificate SHA-256 thumbprint.
        Parameters:
        cert - The X.509 certificate. Must not be null.
        Returns:
        The public RSA or EC JWK.
        Throws:
        JOSEException - If parsing failed.

      • parseFromPEMEncodedX509Cert

        public static JWK parseFromPEMEncodedX509Cert​(String pemEncodedCert)
                                       throws JOSEException
        Parses a public RSA or EC JWK from the specified PEM-encoded X.509 certificate. Requires BouncyCastle.

        Important: The X.509 certificate is not validated!

        Sets the following JWK parameters:

        • For an EC key the curve is obtained from the subject public key info algorithm parameters.
        • The JWK use inferred by KeyUse.from(java.security.cert.X509Certificate).
        • The JWK ID from the X.509 serial number (in base 10).
        • The JWK X.509 certificate chain (this certificate only).
        • The JWK X.509 certificate SHA-256 thumbprint.
        Parameters:
        pemEncodedCert - The PEM-encoded X.509 certificate. Must not be null.
        Returns:
        The public RSA or EC JWK.
        Throws:
        JOSEException - If parsing failed.

      • load

        public static JWK load​(KeyStore keyStore,
                       String alias,
                       char[] pin)
                throws KeyStoreException,
                       JOSEException
        Loads a JWK from the specified JCE key store. The JWK can be a public / private RSA key, a public / private EC key, or a secret key. Requires BouncyCastle.

        Important: The X.509 certificate is not validated!

        Parameters:
        keyStore - The key store. Must not be null.
        alias - The alias. Must not be null.
        pin - The pin to unlock the private key if any, empty or null if not required.
        Returns:
        The public / private RSA or EC JWK, or secret JWK, or null if no key with the specified alias was found.
        Throws:
        KeyStoreException - On a key store exception.
        JOSEException - If RSA or EC key loading failed.

      • parseFromPEMEncodedObjects

        public static JWK parseFromPEMEncodedObjects​(String pemEncodedObjects)
                                      throws JOSEException
        Parses an RSA or EC JWK from the specified string of one or more PEM-encoded object(s):
        • X.509 certificate (PEM header: BEGIN CERTIFICATE)
        • PKCS#1 RSAPublicKey (PEM header: BEGIN RSA PUBLIC KEY)
        • X.509 SubjectPublicKeyInfo (PEM header: BEGIN PUBLIC KEY)
        • PKCS#1 RSAPrivateKey (PEM header: BEGIN RSA PRIVATE KEY)
        • PKCS#8 PrivateKeyInfo (PEM header: BEGIN PRIVATE KEY)
        • matching pair of the above

        Requires BouncyCastle.

        Parameters:
        pemEncodedObjects - The string of PEM-encoded object(s).
        Returns:
        The public / (private) RSA or EC JWK.
        Throws:
        JOSEException - If RSA or EC key parsing failed.