Package com.nimbusds.jose.jwk

Class JWKSet

  • All Implemented Interfaces:
    java.io.Serializable
    @Immutable
public class JWKSet
extends java.lang.Object
implements java.io.Serializable
    JSON Web Key (JWK) set. Represented by a JSON object that contains an array of JSON Web Keys (JWKs) as the value of its "keys" member. Additional (custom) members of the JWK Set JSON object are also supported.

    Example JWK set: 

     {
   "keys" : [ { "kty" : "EC",
                "crv" : "P-256",
                "x"   : "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
                "y"   : "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
                "use" : "enc",
                "kid" : "1" },

              { "kty" : "RSA",
                "n"   : "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
                         4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
                         tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2
                         QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI
                         SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb
                         w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
                "e"   : "AQAB",
                "alg" : "RS256",
                "kid" : "2011-04-29" } ]
 }
    Version:
    2022-11-22
    Author:
    Vladimir Dzhuvinov, Vedran Pavic
    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String MIME_TYPE
      The MIME type of JWK set objects: application/jwk-set+json; charset=UTF-8

    • Constructor Summary

      Constructors 
      Constructor Description
      JWKSet()
      Creates a new empty JWK set.
      JWKSet​(JWK key)
      Creates a new JWK set with a single key.
      JWKSet​(java.util.List<JWK> keys)
      Creates a new JWK set with the specified keys.
      JWKSet​(java.util.List<JWK> keys, java.util.Map<java.lang.String,​java.lang.Object> customMembers)
      Creates a new JWK set with the specified keys and additional custom members.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean containsJWK​(JWK jwk)
      Returns true if this JWK set contains the specified JWK as public or private key, by comparing its thumbprint with those of the keys in the set.
      boolean equals​(java.lang.Object o)  
      java.util.Map<java.lang.String,​java.lang.Object> getAdditionalMembers()
      Returns the additional custom members of this (JWK) set.
      JWK getKeyByKeyId​(java.lang.String kid)
      Returns the key from this JWK set as identified by its Key ID (kid) member.
      java.util.List<JWK> getKeys()
      Returns the keys (ordered) of this JWK set.
      int hashCode()  
      boolean isEmpty()
      Returns true if this JWK set is empty.
      static JWKSet load​(java.io.File file)
      Loads a JWK set from the specified file.
      static JWKSet load​(java.io.InputStream inputStream)
      Loads a JWK set from the specified input stream.
      static JWKSet load​(java.net.URL url)
      Loads a JWK set from the specified URL.
      static JWKSet load​(java.net.URL url, int connectTimeout, int readTimeout, int sizeLimit)
      Loads a JWK set from the specified URL.
      static JWKSet load​(java.net.URL url, int connectTimeout, int readTimeout, int sizeLimit, java.net.Proxy proxy)
      Loads a JWK set from the specified URL.
      static JWKSet load​(java.security.KeyStore keyStore, PasswordLookup pwLookup)
      Loads a JWK set from the specified JCA key store.
      static JWKSet parse​(java.lang.String s)
      Parses the specified string representing a JWK set.
      static JWKSet parse​(java.util.Map<java.lang.String,​java.lang.Object> json)
      Parses the specified JSON object representing a JWK set.
      int size()
      Returns the number of keys in this JWK set.
      java.util.Map<java.lang.String,​java.lang.Object> toJSONObject()
      Returns the JSON object representation of this JWK set.
      java.util.Map<java.lang.String,​java.lang.Object> toJSONObject​(boolean publicKeysOnly)
      Returns the JSON object representation of this JWK set.
      JWKSet toPublicJWKSet()
      Returns a copy of this (JWK) set with all private keys and parameters removed.
      java.lang.String toString()
      Returns the JSON object string representation of this JWK set.
      java.lang.String toString​(boolean publicKeysOnly)
      Returns the JSON object string representation of this JWK set.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • MIME_TYPE

        public static final java.lang.String MIME_TYPE
        The MIME type of JWK set objects: application/jwk-set+json; charset=UTF-8
        See Also:
        Constant Field Values

    • Constructor Detail

      • JWKSet

        public JWKSet()
        Creates a new empty JWK set.

      • JWKSet

        public JWKSet​(JWK key)
        Creates a new JWK set with a single key.
        Parameters:
        key - The JWK. Must not be null.

      • JWKSet

        public JWKSet​(java.util.List<JWK> keys)
        Creates a new JWK set with the specified keys.
        Parameters:
        keys - The JWK list. Must not be null.

      • JWKSet

        public JWKSet​(java.util.List<JWK> keys,
              java.util.Map<java.lang.String,​java.lang.Object> customMembers)
        Creates a new JWK set with the specified keys and additional custom members.
        Parameters:
        keys - The JWK list. Must not be null.
        customMembers - The additional custom members. Must not be null.

    • Method Detail

      • getKeys

        public java.util.List<JWK> getKeys()
        Returns the keys (ordered) of this JWK set.
        Returns:
        The keys as an unmodifiable list, empty list if none.

      • isEmpty

        public boolean isEmpty()
        Returns true if this JWK set is empty.
        Returns:
        true if empty, else false.

      • size

        public int size()
        Returns the number of keys in this JWK set.
        Returns:
        The number of keys, zero if none.

      • getKeyByKeyId

        public JWK getKeyByKeyId​(java.lang.String kid)
        Returns the key from this JWK set as identified by its Key ID (kid) member.

        If more than one key exists in the JWK Set with the same identifier, this function returns only the first one in the set.

        Parameters:
        kid - They key identifier.
        Returns:
        The key identified by kid or null if no key exists.

      • containsJWK

        public boolean containsJWK​(JWK jwk)
                    throws JOSEException
        Returns true if this JWK set contains the specified JWK as public or private key, by comparing its thumbprint with those of the keys in the set.
        Parameters:
        jwk - The JWK to check. Must not be null.
        Returns:
        true if contained, false if not.
        Throws:
        JOSEException - If thumbprint computation failed.

      • getAdditionalMembers

        public java.util.Map<java.lang.String,​java.lang.Object> getAdditionalMembers()
        Returns the additional custom members of this (JWK) set.
        Returns:
        The additional custom members as a unmodifiable map, empty map if none.

      • toPublicJWKSet

        public JWKSet toPublicJWKSet()
        Returns a copy of this (JWK) set with all private keys and parameters removed.
        Returns:
        A copy of this JWK set with all private keys and parameters removed.

      • toJSONObject

        public java.util.Map<java.lang.String,​java.lang.Object> toJSONObject()
        Returns the JSON object representation of this JWK set. Only public keys will be included. Use the alternative toJSONObject(boolean) method to include all key material.
        Returns:
        The JSON object representation.

      • toJSONObject

        public java.util.Map<java.lang.String,​java.lang.Object> toJSONObject​(boolean publicKeysOnly)
        Returns the JSON object representation of this JWK set.
        Parameters:
        publicKeysOnly - Controls the inclusion of private keys and parameters into the output JWK members. If true only public keys will be included. If false all available keys with their parameters will be included.
        Returns:
        The JSON object representation.

      • toString

        public java.lang.String toString​(boolean publicKeysOnly)
        Returns the JSON object string representation of this JWK set.
        Parameters:
        publicKeysOnly - Controls the inclusion of private keys and parameters into the output JWK members. If true only public keys will be included. If false all available keys with their parameters will be included.
        Returns:
        The JSON object string representation.

      • toString

        public java.lang.String toString()
        Returns the JSON object string representation of this JWK set. Only public keys will be included. Use the alternative toString(boolean) method to include all key material.
        Overrides:
        toString in class java.lang.Object
        Returns:
        The JSON object string representation. Only public keys will be included.

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • parse

        public static JWKSet parse​(java.lang.String s)
                    throws java.text.ParseException
        Parses the specified string representing a JWK set.
        Parameters:
        s - The string to parse. Must not be null.
        Returns:
        The JWK set.
        Throws:
        java.text.ParseException - If the string couldn't be parsed to a valid JWK set.

      • parse

        public static JWKSet parse​(java.util.Map<java.lang.String,​java.lang.Object> json)
                    throws java.text.ParseException
        Parses the specified JSON object representing a JWK set.
        Parameters:
        json - The JSON object to parse. Must not be null.
        Returns:
        The JWK set.
        Throws:
        java.text.ParseException - If the string couldn't be parsed to a valid JWK set.

      • load

        public static JWKSet load​(java.io.InputStream inputStream)
                   throws java.io.IOException,
                          java.text.ParseException
        Loads a JWK set from the specified input stream.
        Parameters:
        inputStream - The JWK set input stream. Must not be null.
        Returns:
        The JWK set.
        Throws:
        java.io.IOException - If the input stream couldn't be read.
        java.text.ParseException - If the input stream couldn't be parsed to a valid JWK set.

      • load

        public static JWKSet load​(java.io.File file)
                   throws java.io.IOException,
                          java.text.ParseException
        Loads a JWK set from the specified file.
        Parameters:
        file - The JWK set file. Must not be null.
        Returns:
        The JWK set.
        Throws:
        java.io.IOException - If the file couldn't be read.
        java.text.ParseException - If the file couldn't be parsed to a valid JWK set.

      • load

        public static JWKSet load​(java.net.URL url,
                          int connectTimeout,
                          int readTimeout,
                          int sizeLimit)
                   throws java.io.IOException,
                          java.text.ParseException
        Loads a JWK set from the specified URL.
        Parameters:
        url - The JWK set URL. Must not be null.
        connectTimeout - The URL connection timeout, in milliseconds. If zero no (infinite) timeout.
        readTimeout - The URL read timeout, in milliseconds. If zero no (infinite) timeout.
        sizeLimit - The read size limit, in bytes. If zero no limit.
        Returns:
        The JWK set.
        Throws:
        java.io.IOException - If the file couldn't be read.
        java.text.ParseException - If the file couldn't be parsed to a valid JWK set.

      • load

        public static JWKSet load​(java.net.URL url,
                          int connectTimeout,
                          int readTimeout,
                          int sizeLimit,
                          java.net.Proxy proxy)
                   throws java.io.IOException,
                          java.text.ParseException
        Loads a JWK set from the specified URL.
        Parameters:
        url - The JWK set URL. Must not be null.
        connectTimeout - The URL connection timeout, in milliseconds. If zero no (infinite) timeout.
        readTimeout - The URL read timeout, in milliseconds. If zero no (infinite) timeout.
        sizeLimit - The read size limit, in bytes. If zero no limit.
        proxy - The optional proxy to use when opening the connection to retrieve the resource. If null, no proxy is used.
        Returns:
        The JWK set.
        Throws:
        java.io.IOException - If the file couldn't be read.
        java.text.ParseException - If the file couldn't be parsed to a valid JWK set.

      • load

        public static JWKSet load​(java.net.URL url)
                   throws java.io.IOException,
                          java.text.ParseException
        Loads a JWK set from the specified URL.
        Parameters:
        url - The JWK set URL. Must not be null.
        Returns:
        The JWK set.
        Throws:
        java.io.IOException - If the file couldn't be read.
        java.text.ParseException - If the file couldn't be parsed to a valid JWK set.

      • load

        public static JWKSet load​(java.security.KeyStore keyStore,
                          PasswordLookup pwLookup)
                   throws java.security.KeyStoreException
        Loads a JWK set from the specified JCA key store. Key conversion exceptions are silently swallowed. PKCS#11 stores are also supported. Requires BouncyCastle.

        Important: The X.509 certificates are not validated!

        Parameters:
        keyStore - The key store. Must not be null.
        pwLookup - The password lookup for password-protected keys, null if not specified.
        Returns:
        The JWK set, empty if no keys were loaded.
        Throws:
        java.security.KeyStoreException - On a key store exception.