Package com.authlete.sd

Class Disclosure

  • public class Disclosure
extends Object
    A class that represents the "Disclosure" defined in the SD-JWT specification.

    Instances of this class are immutable.

    Example 1: 

     // Parameters for the constructor.
 String salt       = "_26bc4LT-ac6q2KI6cBW5es";
 String claimName  = "family_name";
 Object claimValue = "Möbius";

 // Create a Disclosure instance with the parameters.
 Disclosure disclosure =
     new Disclosure(salt, claimName, claimValue);

 // Get the string representation of the disclosure.
 // disclosure.toString() returns the same result.
 String dc = disclosure.getDisclosure();

 // dc -> "WyJfMjZiYzRMVC1hYzZxMktJNmNCVzVlcyIsImZhbWlseV9uYW1lIiwiTcO2Yml1cyJd"

    Example 2: 

     // Parse a string representation of disclosure.
 Disclosure disclosure = Disclosure.parse(
     "WyI2cU1RdlJMNWhhaiIsICJmYW1pbHlfbmFtZSIsICJNw7ZiaXVzIl0");

 // Compute the digest of the disclosure with the default
 // hash algorithm ("sha-256"). disclosure.digest("sha-256")
 // returns the same result.
 String digest = disclosure().digest();

 // digest -> "uutlBuYeMDyjLLTpf6Jxi7yNkEF35jdyWMn9U7b_RYY"

    Example 3: 

     // Disclosure representing ["lklxF5jMYlGTPUovMNIvCA", "FR"].
 Disclosure disclosure = Disclosure.parse(
     "WyJsa2x4RjVqTVlsR1RQVW92TU5JdkNBIiwgIkZSIl0");

 // Create a Map that represents an array element.
 Map<String, Object> element = disclosure.toArrayElement();

 // element -> {"...":"w0I8EKcdCtUPkGCNUrfwVp2xEgNjtoIDlOxc9-PlOhs"}
    Since:
    1.0
    See Also:
    Selective Disclosure for JWTs (SD-JWT)

    • Constructor Detail

      • Disclosure

        public Disclosure​(Object claimValue)
        Constructor with a claim value. A salt is randomly generated. This constructor is dedicated to creating a Disclosure instance that represents an array element.
        Parameters:
        claimValue - A claim value. May be null.
        Since:
        1.2

      • Disclosure

        public Disclosure​(String claimName,
                  Object claimValue)
        Constructor with a pair of claim name and claim value. A salt is randomly generated.
        Parameters:
        claimName - A claim name. A non-null value for an object property, null for an array element.
        claimValue - A claim value. May be null.

      • Disclosure

        public Disclosure​(String salt,
                  String claimName,
                  Object claimValue)
        Constructor with a salt and a pair of claim name and claim value.
        Parameters:
        salt - A salt. Must not be null. It is recommended that the salt have 128-bit or higher entropy and be base64url-encoded.
        claimName - A claim name. A non-null value for an object property, null for an array element.
        claimValue - A claim value. May be null.
        Throws:
        IllegalArgumentException - The given salt is null.

    • Method Detail

      • getSalt

        public String getSalt()
        Get the salt.
        Returns:
        The salt.

      • getClaimName

        public String getClaimName()
        Get the claim name.
        Returns:
        The claim name. If this disclosure is for an array element, null is returned.

      • getClaimValue

        public Object getClaimValue()
        Get the claim value.
        Returns:
        The claim value.

      • getJson

        public String getJson()
        Get the JSON representation of this disclosure. It is a JSON array having two or three elements.
        Returns:
        The JSON representation of this disclosure.

      • getDisclosure

        public String getDisclosure()
        Get the disclosure as a string.
        Returns:
        The disclosure as a string.

      • digest

        public String digest()
        Get the base64url-encoded digest of this disclosure computed with the default hash algorithm ("sha-256").

        The digest value with the default hash algorithm is computed on instance creation and the result is cached. This digest() method always returns the cached value. Therefore, calling this method is lightweight.

        Returns:
        The base64url-encoded digest of this disclosure computed with the default hash algorithm ("sha-256").

      • digest

        public String digest​(String hashAlgorithm)
        Get the base64url-encoded digest of this disclosure computed with the specified hash algorithm.
        Parameters:
        hashAlgorithm - A hash algorithm. Must not be null. If the given hash algorithm is equal to the default hash algorithm ("sha-256"), the cached digest value is returned (cf. digest()).
        Returns:
        The base64url-encoded digest of this disclosure computed with the specified hash algorithm.
        Throws:
        IllegalArgumentException - The specified hash algorithm is null or not supported.
        See Also:
        IANA: Named Information Hash Algorithm Registry

      • toString

        public String toString()
        Get the string representation of this instance is returned, which is the disclosure in the base64url format.
        Overrides:
        toString in class Object
        Returns:
        The disclosure in the base64url format.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • toArrayElement

        public Map<String,​Object> toArrayElement()
        Create a Map instance that represents an array element.

        The returned map contains one key-value pair. The key is "..." (literally three dots), and the value is the digest of this disclosure computed with the default hash algorithm ("sha-256"). 

         {
   "...": "<digest>"
 }
        Returns:
        A Map instance that represents an array element.
        Throws:
        IllegalStateException - This disclosure is not for an array element.
        Since:
        1.2

      • toArrayElement

        public Map<String,​Object> toArrayElement​(String hashAlgorithm)
        Create a Map instance that represents an array element.

        The returned map contains one key-value pair. The key is "..." (literally three dots), and the value is the digest of this disclosure computed with the specified hash algorithm. 

         {
   "...": "<digest>"
 }
        Parameters:
        hashAlgorithm - A hash algorithm used to compute the digest.
        Returns:
        A Map instance that represents an array element.
        Throws:
        IllegalArgumentException - The specified hash algorithm is null or not supported.
        IllegalStateException - This disclosure is not for an array element.
        Since:
        1.2

      • parse

        public static Disclosure parse​(String disclosure)
        Parse the given string as a disclosure.
        Parameters:
        disclosure - A string representation of disclosure. If null is given, null is returned.
        Returns:
        A Disclosure instance created as a result of parsing the input string.
        Throws:
        IllegalArgumentException - (1) The given string is not base64url-encoded. (2) The base64url-decoded value of the given string is not a valid UTF-8 byte sequence. (3) The JSON that the given string represents fails to be parsed as a JSON array. (4) The size of the JSON array is neither 2 nor 3. (5) The first element of the JSON array is not a JSON string. (6) When the size of the JSON array is 3, the second element is not a JSON string. (7) The claim name is a key reserved by the SD-JWT specification.