com.authlete.common.dto.CredentialIssuanceOrder Maven / Gradle / Ivy
/*
* Copyright (C) 2023 Authlete, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.authlete.common.dto;
import java.io.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 {@code requestIdentifier} Parameter
*
*
*
* This mandatory parameter must be the identifier that has been assigned
* to the credential request by the preceding Authlete API.
*
*
*
* The {@code /vci/single/parse} API parses a credential request that the
* implementation of the credential endpoint receives. The response from
* the API ({@link CredentialSingleParseResponse}) includes an identifier
* ({@code info.identifier}) assigned to the credential request. The
* identifier has to be set to this {@code requestIdentifier} parameter.
*
*
*
* Likewise, the {@code /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 {@code /vci/batch/issue} API is expected to contain multiple
* credential orders. Each order is represented by this class and its
* {@code requestIdentifier} parameter should hold an identifier that was
* contained in the response from the {@code /vci/batch/parse} API.
*
*
*
* The {@code /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
* ({@link CredentialRequestInfo}) that is tied to the transaction ID in
* the deferred credential request. The identifier in the information should
* be set to this {@code requestIdentifier} parameter when the
* {@code /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 {@code /vci/deferred/parse}
* API.
*
*
*
* The {@code 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 {@code vc+sd-jwt} Format
*
*
* When the credential format is "{@code vc+sd-jwt}", the {@code credentialPayload}
* parameter is mandatory. It must contain at least the "{@code type}" claim
* whose value is a string, and typically it is expected to contain some claims
* about the user such as the "{@code sub}" claim and the "{@code family_name}"
* claim.
*
*
*
* {
* "type": "Diploma",
* "sub": "79301273",
* "family_name": "Kawasaki"
* }
*
*
*
* The following claims are added by Authlete even if they are not included in
* the {@code credentialPayload} parameter.
*
*
*
* - {@code iss}
*
- {@code iat}
*
- {@code exp} (only when the credential has an expiration time.)
*
- {@code 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.
*
*
*
* - {@code iss}
*
- {@code iat}
*
- {@code nbf}
*
- {@code exp}
*
- {@code cnf}
*
- {@code type}
*
- {@code 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, "{@code country}" and "{@code locality}" in the "{@code address}"
* object become selectively-disclosable, but the name of the object, i.e.,
* "{@code 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 {@code issuanceDeferred} Parameter
*
*
*
* This boolean parameter indicates whether to defer credential issuance.
*
*
*
* When the value of this parameter is {@code true}, a transaction ID is issued
* instead of a credential. That is, the response from the credential issuer
* will contain the "{@code transaction_id}" parameter instead of the
* "{@code credential}" parameter.
*
*
*
* When {@code true}, other parameters than {@code requestIdentifier} will not
* be referenced.
*
*
*
* The {@code credentialDuration} Parameter
*
*
*
* This optional parameter specifies the duration of the credential in seconds.
*
*
*
* The value of this parameter and the value of the "{@code credentialDuration}"
* property ({@link Service#getCredentialDuration() 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 {@code 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 {@code credentialJwks} property
* ({@link Service#getCredentialJwks() credentialJwks}) of the service.
*
*
*
* If this parameter is omitted, Authlete will automatically select one private
* key from the JWK Set.
*
*
*
* @since 3.67
* @since Authlete 3.0
*
* @see OpenID for Verifiable Credential Issuance
*
* @see Selective Disclosure for JWTs (SD-JWT)
*/
public class CredentialIssuanceOrder implements Serializable
{
private static final long serialVersionUID = 1L;
/**
* The identifier of a credential request.
*/
private String requestIdentifier;
/**
* The additional payload that will be added into a credential to be issued.
*/
private String credentialPayload;
/**
* The flag indicating whether to defer credential issuance.
*/
private boolean issuanceDeferred;
/**
* The duration of a credential to be issued.
*/
private long credentialDuration;
/**
* The key ID of a private key that should be used for signing a credential
* to be issued.
*/
private String signingKeyId;
/**
* Get the identifier that has been assigned to the credential request by
* the preceding Authlete API.
*
* @return
* The identifier of a credential request.
*/
public String getRequestIdentifier()
{
return requestIdentifier;
}
/**
* Set the identifier that has been assigned to the credential request by
* the preceding Authlete API.
*
* @param identifier
* The identifier of a credential request.
*
* @return
* {@code this} object.
*/
public CredentialIssuanceOrder setRequestIdentifier(String identifier)
{
this.requestIdentifier = identifier;
return this;
}
/**
* Get the additional payload that will be added into a credential to be
* issued.
*
* @return
* The additional payload of a credential.
*/
public String getCredentialPayload()
{
return credentialPayload;
}
/**
* Set the additional payload that will be added into a credential to be
* issued.
*
* @param payload
* The additional payload of a credential.
*
* @return
* {@code this} object.
*/
public CredentialIssuanceOrder setCredentialPayload(String payload)
{
this.credentialPayload = payload;
return this;
}
/**
* Get the flag indicating whether to defer credential issuance.
*
* @return
* {@code true} if credential issuance should be deferred.
*/
public boolean isIssuanceDeferred()
{
return issuanceDeferred;
}
/**
* Set the flag indicating whether to defer credential issuance.
*
* @param deferred
* {@code true} to defer credential issuance.
*
* @return
* {@code this} object.
*/
public CredentialIssuanceOrder setIssuanceDeferred(boolean deferred)
{
this.issuanceDeferred = deferred;
return this;
}
/**
* 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
* ({@link Service#getCredentialDuration()}) is used. If the value is a
* negative number, the credential will not have an expiration time.
*
*
* @return
* The duration of the credential in seconds.
*/
public long getCredentialDuration()
{
return credentialDuration;
}
/**
* 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
* ({@link Service#getCredentialDuration()}) is used. If the value is a
* negative number, the credential will not have an expiration time.
*
*
* @param duration
* The duration of the credential in seconds.
*
* @return
* {@code this} object.
*/
public CredentialIssuanceOrder setCredentialDuration(long duration)
{
this.credentialDuration = duration;
return this;
}
/**
* Get the key ID of the private key that should be used for signing
* the credential.
*
* @return
* The key ID of the private key that should be used for signing
* the credential. If omitted, Authlete will select one
* automatically.
*/
public String getSigningKeyId()
{
return signingKeyId;
}
/**
* Set the key ID of the private key that should be used for signing
* the credential.
*
* @param keyId
* The key ID of the private key that should be used for signing
* the credential. If omitted, Authlete will select one
* automatically.
*
* @return
* {@code this} object.
*/
public CredentialIssuanceOrder setSigningKeyId(String keyId)
{
this.signingKeyId = keyId;
return this;
}
}