java.lang.Object
- com.authlete.common.dto.CredentialIssuanceOrder

All Implemented Interfaces:: Serializable

public class CredentialIssuanceOrder
extends Object
implements Serializable

Instruction for credential issuance.

Authlete APIs that may issue one or more verifiable credentials expect that an API call contains one or more instructions for the credential issuance. This class represents such instructions.

The `requestIdentifier` Parameter

This mandatory parameter must be the identifier that has been assigned to the credential request by the preceding Authlete API.

The /vci/single/parse API parses a credential request that the implementation of the credential endpoint receives. The response from the API (CredentialSingleParseResponse) includes an identifier (info.identifier) assigned to the credential request. The identifier has to be set to this requestIdentifier parameter.

Likewise, the /vci/batch/parse API parses a batch credential request that the implementation of the batch credential endpoint receives. The response from the API includes identifiers assigned to each credential request in the batch credential request. A request to the /vci/batch/issue API is expected to contain multiple credential orders. Each order is represented by this class and its requestIdentifier parameter should hold an identifier that was contained in the response from the /vci/batch/parse API.

The /vci/deferred/parse API parses a deferred credential request that the implementation of the deferred credential endpoint receives. The API returns information about a credential request (CredentialRequestInfo) that is tied to the transaction ID in the deferred credential request. The identifier in the information should be set to this requestIdentifier parameter when the /vci/deferred/issue API is called. FYI: The Authlete implementation uses the identifier as a transaction ID, so the value of the transaction ID in the deferred credential request is equal to the identifier in the information returned from the /vci/deferred/parse API.

The `credentialPayload` Parameter

This parameter is an additional content that will be added to the payload of a credential to be issued. The format of this parameter must be a JSON object if present. The necessity and content of this parameter depend on the credential format.

The vc+sd-jwt Format

When the credential format is "vc+sd-jwt", the credentialPayload parameter is mandatory. It must contain at least the "vct" claim whose value is a string, and typically it is expected to contain some claims about the user such as the "sub" claim and the "family_name" claim.
 {
   "vct": "Diploma",
   "sub": "79301273",
   "family_name": "Kawasaki"
 }
 
The following claims are added by Authlete even if they are not included in the credentialPayload parameter.

iss
iat
exp (only when the credential has an expiration time.)
cnf (only when the credential request included a key proof.)

Claims in the payload will be made selectively-disclosable automatically in the way that conforms to the "Selective Disclosure for JWTs (SD-JWT)" specification. Note that, however, the following claims appear in the payload as they are without being made selectively-disclosable.

iss
iat
nbf
exp
cnf
type
status

The current Authlete implementation makes leaf elements selectively-disclosable. On the other hand, names of claims that have a nested structure are not hidden. For example, "country" and "locality" in the "address" object become selectively-disclosable, but the name of the object, i.e., "address", will appear in the payload like below.
 "address": {
   "_sd": [
     "G_FeM1D-U3tDJcHB7pwTNEElLal9FE9PUs0klHgeM1c",
     "KlG6HEM6XWbymEJDfyDY4klJkQQ9iTuNG0LQXnE9mQ0",
     "X96Emv4S9uzFUGkU8MmOlFzUwEtDNeT-ToXw3Fx9AfI",
     "ffPGyxFBnNA1r60g2f796Hqq3dBGtaOogpnIBgRGdyY"
   ]
 }
 
Authlete may provide an advanced mechanism to control the behavior in the future.

The mso_mdoc Format

This format identifier represents the mdoc format which is defined in the "ISO/IEC 18013-5:2021" standard.

When the credential format is "mso_mdoc", the credentialPayload parameter is mandatory. It must contain at least the "doctype" property and the "claims" property.

The value of the "doctype" property must be a string which represents the document type of the mdoc being issued. For example, in the case of mDL, the value should be "org.iso.18013.5.1.mDL".

The value of the "claims" property must be a JSON object. The keys of the top-level properties in the JSON object must be strings representing name spaces, and their values must be JSON objects, each of which contains claims under the corresponding name space.

The following JSON shows the structure that the credentialPayload should have.
 {
   "doctype": "org.iso.18013.5.1.mDL",
   "claims": {
     "org.iso.18013.5.1": {
       "family_name": "Doe",
       "issue_date": "cbor:1004(\"2019-10-20\")",
       "expiry_date": "cbor:1004(\"2024-10-20\")",
       "document_number": "123456789",
       "portrait": "cbor:h'ffd8ffe...'",
       "driving_privileges": [
         {
           "vehicle_category_code": "A",
           "issue_date": "cbor:1004(\"2018-08-09\")",
           "expiry_date": "cbor:1004(\"2024-10-20\")"
         },
         {
           "vehicle_category_code": "B",
           "issue_date": "cbor:1004(\"2017-08-09\")",
           "expiry_date": "cbor:1004(\"2024-10-20\")"
         }
       ]
     }
   }
 }
 
The "doctype" property in the example above specifies "org.iso.18013.5.1.mDL" as the document type. The "claims" JSON object contains one name space, "org.iso.18013.5.1". Under the name space, 6 claims are listed. The names of the claims are "family_name", "issue_date", "expiry_date", "document_number", "portrait", and "driving_privileges".

According to the mdoc specification, claim names must be strings. On the other hand, the restriction is not imposed on claim values. Claim values can have any CBOR data type.

Authlete converts claim values to corresponding CBOR items properly. For example, Authlete converts JSON strings into CBOR text strings, JSON arrays into CBOR arrays, and JSON objects into CBOR maps. However, some CBOR data types cannot be expressed by JSON primitive data types. For instance, CBOR tags and binary data cannot be expressed. For such CBOR data types, Authlete provides a mechanism to specify CBOR-specific data using CBOR Diagnostic Notation (RFC 8949, 8. Diagnostic Notation) and CBOR Extended Diagnostic Notation (RFC 8610, Appendix G. Extended Diagnostic Notation).

When the type of a claim value is a string and the value starts from the prefix "cbor:", Authlete parses the substring after the prefix as CBOR (Extended) Diagnostic Notation. For example, using one of the syntaxes below, binary data can be embedded.

syntax example

h'base16-string' h'12345678'

b32'base32-string' b32'CI2FM6A'

h32'base32hex-string' h32'28Q5CU0'

b64'base64(url)-string' b64'EjRWeA'

'string' 'hello world'
(equivalent to h'68656c6c6f20776f726c64')

The syntax "TagNumber(CBOR item)" can prepend a CBOR tag to any CBOR item. For instance, to prepend a CBOR tag 1004 (cf. RFC 8943) to the string "2019-10-20", the following expression works: 1004("2019-10-20")

The `issuanceDeferred` Parameter

This boolean parameter indicates whether to defer credential issuance.

When the value of this parameter is true, a transaction ID is issued instead of a credential. That is, the response from the credential issuer will contain the "transaction_id" parameter instead of the "credential" parameter.

When true, other parameters than requestIdentifier will not be referenced.

The `credentialDuration` Parameter

This optional parameter specifies the duration of the credential in seconds.

The value of this parameter and the value of the "credentialDuration" property (credentialDuration) of the service are used as input to determine the final duration of the credential. The table below indicates how the duration is determined.

Request Parameter Service Property Result

0 or omitted 0 The credential won't expire.

0 or omitted positive number The value of the service property is used as the duration.

positive number any The value of the request parameter is used as the duration.

negative number any The credential won't expire.

The `signingKeyId` Parameter

This optional parameter specifies the key ID of the private key that should be used for signing the credential.

The key ID should be found in the JWK Set of the credential issuer, which is the content of the credentialJwks property (credentialJwks) of the service.

If this parameter is omitted, Authlete will automatically select one private key from the JWK Set.

Since:: 3.67, Authlete 3.0
See Also:: OpenID for Verifiable Credential Issuance, Selective Disclosure for JWTs (SD-JWT), Serialized Form

Constructor Summary

Constructors
Constructor Description

CredentialIssuanceOrder()

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`long`	`getCredentialDuration()`	Get the duration of the credential in seconds.
`String`	`getCredentialPayload()`	Get the additional payload that will be added into a credential to be issued.
`String`	`getRequestIdentifier()`	Get the identifier that has been assigned to the credential request by the preceding Authlete API.
`String`	`getSigningKeyId()`	Get the key ID of the private key that should be used for signing the credential.
`boolean`	`isIssuanceDeferred()`	Get the flag indicating whether to defer credential issuance.
`CredentialIssuanceOrder`	`setCredentialDuration(long duration)`	Set the duration of the credential in seconds.
`CredentialIssuanceOrder`	`setCredentialPayload(String payload)`	Set the additional payload that will be added into a credential to be issued.
`CredentialIssuanceOrder`	`setIssuanceDeferred(boolean deferred)`	Set the flag indicating whether to defer credential issuance.
`CredentialIssuanceOrder`	`setRequestIdentifier(String identifier)`	Set the identifier that has been assigned to the credential request by the preceding Authlete API.
`CredentialIssuanceOrder`	`setSigningKeyId(String keyId)`	Set the key ID of the private key that should be used for signing the credential.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - CredentialIssuanceOrder
```
public CredentialIssuanceOrder()
```
- Method Detail
  - getRequestIdentifier
```
public String getRequestIdentifier()
```
    Get the identifier that has been assigned to the credential request by the preceding Authlete API.
    
    Returns:
    
    The identifier of a credential request.
  - setRequestIdentifier
```
public CredentialIssuanceOrder setRequestIdentifier(String identifier)
```
    Set the identifier that has been assigned to the credential request by the preceding Authlete API.
    
    Parameters:
    
    identifier - The identifier of a credential request.
    
    Returns:
    
    this object.
  - getCredentialPayload
```
public String getCredentialPayload()
```
    Get the additional payload that will be added into a credential to be issued.
    
    Returns:
    
    The additional payload of a credential.
  - setCredentialPayload
```
public CredentialIssuanceOrder setCredentialPayload(String payload)
```
    Set the additional payload that will be added into a credential to be issued.
    
    Parameters:
    
    payload - The additional payload of a credential.
    
    Returns:
    
    this object.
  - isIssuanceDeferred
```
public boolean isIssuanceDeferred()
```
    Get the flag indicating whether to defer credential issuance.
    
    Returns:
    
    true if credential issuance should be deferred.
  - setIssuanceDeferred
```
public CredentialIssuanceOrder setIssuanceDeferred(boolean deferred)
```
    Set the flag indicating whether to defer credential issuance.
    
    Parameters:
    
    deferred - true to defer credential issuance.
    
    Returns:
    
    this object.
  - getCredentialDuration
```
public long getCredentialDuration()
```
    Get the duration of the credential in seconds.
    If the value of this parameter is a positive number, the value is used as the duration. If the value is 0, the default duration of the service (Service.getCredentialDuration()) is used. If the value is a negative number, the credential will not have an expiration time.
    
    Returns:
    
    The duration of the credential in seconds.
  - setCredentialDuration
```
public CredentialIssuanceOrder setCredentialDuration(long duration)
```
    Set the duration of the credential in seconds.
    If the value of this parameter is a positive number, the value is used as the duration. If the value is 0, the default duration of the service (Service.getCredentialDuration()) is used. If the value is a negative number, the credential will not have an expiration time.
    
    Parameters:
    
    duration - The duration of the credential in seconds.
    
    Returns:
    
    this object.
  - getSigningKeyId
```
public String getSigningKeyId()
```
    Get the key ID of the private key that should be used for signing the credential.
    
    Returns:
    
    The key ID of the private key that should be used for signing the credential. If omitted, Authlete will select one automatically.
  - setSigningKeyId
```
public CredentialIssuanceOrder setSigningKeyId(String keyId)
```
    Set the key ID of the private key that should be used for signing the credential.
    
    Parameters:
    
    keyId - The key ID of the private key that should be used for signing the credential. If omitted, Authlete will select one automatically.
    
    Returns:
    
    this object.

Class CredentialIssuanceOrder

The `requestIdentifier` Parameter

The `credentialPayload` Parameter

The `vc+sd-jwt` Format

The `mso_mdoc` Format

The `issuanceDeferred` Parameter

The `credentialDuration` Parameter

The `signingKeyId` Parameter

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CredentialIssuanceOrder

Method Detail

getRequestIdentifier

setRequestIdentifier

getCredentialPayload

setCredentialPayload

isIssuanceDeferred

setIssuanceDeferred

getCredentialDuration

setCredentialDuration

getSigningKeyId

setSigningKeyId

syntax	example
`h'base16-string'`	`h'12345678'`
`b32'base32-string'`	`b32'CI2FM6A'`
`h32'base32hex-string'`	`h32'28Q5CU0'`
`b64'base64(url)-string'`	`b64'EjRWeA'`
`'string'`	`'hello world'` (equivalent to `h'68656c6c6f20776f726c64'`)

Request Parameter	Service Property	Result
0 or omitted	0	The credential won't expire.
0 or omitted	positive number	The value of the service property is used as the duration.
positive number	any	The value of the request parameter is used as the duration.
negative number	any	The credential won't expire.

Class CredentialIssuanceOrder

The requestIdentifier Parameter

The credentialPayload Parameter

The vc+sd-jwt Format

The mso_mdoc Format

The issuanceDeferred Parameter

The credentialDuration Parameter

The signingKeyId Parameter

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CredentialIssuanceOrder

Method Detail

getRequestIdentifier

setRequestIdentifier

getCredentialPayload

setCredentialPayload

isIssuanceDeferred

setIssuanceDeferred

getCredentialDuration

setCredentialDuration

getSigningKeyId

setSigningKeyId

The `requestIdentifier` Parameter

The `credentialPayload` Parameter

The `vc+sd-jwt` Format

The `mso_mdoc` Format

The `issuanceDeferred` Parameter

The `credentialDuration` Parameter

The `signingKeyId` Parameter