Class CWTKeyProofBuilder

java.lang.Object
com.authlete.cwt.CWTKeyProofBuilder
public class CWTKeyProofBuilder extends Object
A utility to generate a CWT key proof, which is defined in the specification of "OpenID for Verifiable Credential Issuance".

EXAMPLE

 // The identifier of the client application.
 String client = "my_client_id";

 // The identifier of the credential issuer.
 String issuer = "https://credential-issuer.example.com";

 // The value of 'c_nonce' issued by the authorization server
 // or the credential issuer.
 String nonce = "my_nonce";

 // A private key for signing. The public key corresponding to
 // this private key will be embedded in the protected header.
 COSEKey key = ...;

 // The issuance time. When omitted, the current time is used.
 Date iat = new Date();

 // Generate a CWT representing a key proof.
 CWT cwt = new CWTKeyProofBuilder()
     .setClient(client)
     .setIssuer(issuer)
     .setNonce(nonce)
     .setKey(key)
     .setIssuedAt(iat)
     .build();

 // The base64url representation of the key proof.
 String base64url = cwt.encodeToBase64Url();

The variable "base64url" in the example above holds a value like below.

2D3ShFifowEmA3RvcGVuaWQ0dmNpLXByb29mK2N3dGhDT1NFX0tleVh7pgECAlgrMWU1QVk5RXlCMDFYblV6YTZMcEp6azAybjZZX0FtbW5TYjBGQmVOVlZyVQMmIAEhWCA9LFCsPbOXT-ZdwCrPWaCpJ4GgGGebHbLEESmsFjwXbSJYIMVfH24tRUqLFLpy3rizbi5CYqpmOkyojJ7q_hp9sEddoFhgpAFsdHJhY2sxX2xpZ2h0A3gaaHR0cHM6Ly90cmlhbC5hdXRobGV0ZS5uZXQGGmZf3KsKWCt2LTFiLW44MmtFSkdiSFJPU2VrR3NtUi14RXVhbUN4WV9UMHRYdFFOLWRZWEB0XIuOQg2CoiLJF99zotTqM80A0i5riMSgKMYzhqfAEckD2BEDIdX1X6ySkRPOAt1ftsy3HLXqg4DAPOldPZOP

The following is the CBOR Diagnostic Notation representation of the example CWT key proof above. Refer to RFC 8949, 8. Diagnostic Notation and RFC 8610, Appendix G. Extended Diagnostic Notation for details about the CBOR Diagnostic Notation. 

 61(18(/ COSE_Sign1 / [
   / protected / <<
     {
       1: -7,
       3: "openid4vci-proof+cwt",
       "COSE_Key": h'a6010202582b3165354159394579423031586e557a61364c704a7a6b30326e36595f416d6d6e5362304642654e56567255032620012158203d2c50ac3db3974fe65dc02acf59a0a92781a018679b1db2c41129ac163c176d225820c55f1f6e2d454a8b14ba72deb8b36e2e4262aa663a4ca88c9eeafe1a7db0475d'
     }
   >>,
   / unprotected / {
   },
   h'a4016c747261636b315f6c6967687403781a68747470733a2f2f747269616c2e617574686c6574652e6e6574061a665fdcab0a582b762d31622d6e38326b454a476248524f53656b47736d522d784575616d4378595f5430745874514e2d6459',
   h'745c8b8e420d82a222c917df73a2d4ea33cd00d22e6b88c4a028c63386a7c011c903d8110321d5f55fac929113ce02dd5fb6ccb71cb5ea8380c03ce95d3d938f'
 ]))

The value of "COSE_Key" in the protected header is a byte string, which wraps the COSE key. The content of the byte string is decoded as follows: 

 {
   1: 2,
   2: h'3165354159394579423031586e557a61364c704a7a6b30326e36595f416d6d6e5362304642654e56567255',
   3: -7,
   -1: 1,
   -2: h'3d2c50ac3db3974fe65dc02acf59a0a92781a018679b1db2c41129ac163c176d',
   -3: h'c55f1f6e2d454a8b14ba72deb8b36e2e4262aa663a4ca88c9eeafe1a7db0475d'
 }

FYI: CBOR Zone (https://cbor.zone/) can be used to decode CBOR data.

COMMAND LINE INVOCATION

This class provides the main(String[]) method for invocation from the command line. Refer to the JavaDoc of the method for details. The generate-cwt-key-proof script is a wrapper for the command line invocation.

Since:
1.15
See Also:

  • Constructor Details

    • CWTKeyProofBuilder

      public CWTKeyProofBuilder()
      The default constructor.

  • Method Details

    • getClient

      public String getClient()
      Get the identifier of the client application. This value is used as the value of the Claim Key 1 (iss).

      In most cases, this parameter is mandatory. Omission of this parameter is allowed only when the access token has been issued by the pre-authorized code flow with anonymous access. Refer to "OpenID for Verifiable Credential Issuance" for details.

      Returns:
      The identifier of the client application.
      See Also:

    • setClient

      public CWTKeyProofBuilder setClient(String client)
      Set the identifier of the client application. This value is used as the value of the Claim Key 1 (iss).

      In most cases, this parameter is mandatory. Omission of this parameter is allowed only when the access token has been issued by the pre-authorized code flow with anonymous access. Refer to "OpenID for Verifiable Credential Issuance" for details.

      Parameters:
      client - The identifier of the client application.
      Returns:
      this object.
      See Also:

    • getIssuer

      public String getIssuer()
      Get the identifier of the credential issuer. This value is used as the value of the Claim Key 3 (aud).

      This parameter is mandatory.

      Returns:
      The identifier of the credential issuer.
      See Also:

    • setIssuer

      public CWTKeyProofBuilder setIssuer(String issuer)
      Set the identifier of the credential issuer. This value is used as the value of the Claim Key 3 (aud).

      This parameter is mandatory.

      Parameters:
      issuer - The identifier of the credential issuer.
      Returns:
      this object.
      See Also:

    • getIssuedAt

      public Date getIssuedAt()
      Get the issuance time. This value is used as the value of the Claim Key 6 (iat).

      If this parameter has not been specified, the build() method uses the current time.

      Returns:
      The issuance time.
      See Also:

    • setIssuedAt

      public CWTKeyProofBuilder setIssuedAt(Date issuedAt)
      Set the issuance time. This value is used as the value of the Claim Key 6 (iat).

      If this parameter has not been specified, the build() method uses the current time.

      Parameters:
      issuedAt - The issuance time.
      Returns:
      this object.
      See Also:

    • getNonce

      public String getNonce()
      Get the nonce value, which is the value of "c_nonce" issued by the server (the authorization server or the credential issuer). This value is used as the value of the Claim Key 10 (Nonce).

      If a c_nonce has been issued by the server (the authorization server or the credential issuer), this parameter is mandatory.

      Returns:
      The nonce value.
      See Also:

    • setNonce

      public CWTKeyProofBuilder setNonce(String nonce)
      Set the nonce value, which is the value of "c_nonce" issued by the server (the authorization server or the credential issuer). This value is used as the value of the Claim Key 10 (Nonce).

      If a c_nonce has been issued by the server (the authorization server or the credential issuer), this parameter is mandatory.

      Parameters:
      nonce - The nonce value.
      Returns:
      this object.
      See Also:

    • getKey

      public COSEKey getKey()
      Get the private key.

      The private key is used for signing the CWT key proof. In addition, the public key corresponding to the private key is embedded in the protected header of the CWT key proof as the value of "COSE_Key".

      In the current implementation, the key must be an instance of COSEEC2Key, because supported key algorithms are ES256, ES384 and ES512 only.

      Returns:
      The private key.

    • setKey

      public CWTKeyProofBuilder setKey(COSEKey key)
      Set the private key.

      The private key is used for signing the CWT key proof. In addition, the public key corresponding to the private key is embedded in the protected header of the CWT key proof as the value of "COSE_Key".

      In the current implementation, the key must be an instance of COSEEC2Key, because supported key algorithms are ES256, ES384 and ES512 only.

      Parameters:
      key - The private key.
      Returns:
      this object.

    • build

      public CWT build() throws IllegalStateException, COSEException
      Generate a CWT key proof.

      At least the issuer and the private key must be set before this method is called.

      Returns:
      A CWT instance that represents a CWT key proof.
      Throws:
      IllegalStateException - A mandatory parameter is not set, or the specified key does not satisfy required conditions.
      COSEException - Failed to generate a CWT key proof.

    • main

      public static void main(String[] args)
      The entry point for invocation from the command line. The following command line options are recognized.
      option description
      --issuer ISSUER

      REQUIRED. This option specifies the identifier of the credential issuer.

      --key FILE

      REQUIRED. This option specifies the file containing a private key in the JWK format (RFC 7517: JSON Web Key (JWK)).

      --client CLIENT

      OPTIONAL. This option specifies the identifier of the client application.

      --nonce NONCE

      OPTIONAL. This option specifies the value of "c_nonce" that has been issued by the authorization server or the credential issuer.

      --issued-at TIME

      OPTIONAL. This option specifies the issuance time by using one of the following formats:

      1. integer representing seconds since the Unix epoch
      2. string representing a datetime in UTC in the ISO 8601 format

      When this option is omitted, the current time is used as the issuance time.

      --help

      This option shows the help text.

      Parameters:
      args - The command line arguments.