Package com.android.identity

Class DeviceResponseGenerator

java.lang.Object

com.android.identity.DeviceResponseGenerator

public final class DeviceResponseGenerator
extends java.lang.Object

Helper class for building DeviceResponse CBOR as specified in ISO/IEC 18013-5 section 8.3 Device Retrieval.

Constructor Summary

Constructors

Constructor	Description
DeviceResponseGenerator(long statusCode)	Creates a new DeviceResponseGenerator.

Method Summary

Modifier and Type	Method	Description
DeviceResponseGenerator	addDocument(java.lang.String docType, byte[] encodedDeviceNamespaces, byte[] encodedDeviceSignature, byte[] encodedDeviceMac, java.util.Map<java.lang.String,java.util.List<byte[]>> issuerSignedData, java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Long>> errors, byte[] encodedIssuerAuth)	Adds a new document to the device response.
DeviceResponseGenerator	addDocument(java.lang.String docType, CredentialDataResult credentialDataResult, java.util.Map<java.lang.String,java.util.List<byte[]>> issuerSignedMapping, java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Long>> errors, byte[] encodedIssuerAuth)	Like addDocument(String, byte[], byte[], byte[], Map, Map, byte[]) but takes a CredentialDataResult instead and merges the results into the "elementValue" entry of each IssuerSignedItem value.
byte[]	generate()	Builds the DeviceResponse CBOR.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DeviceResponseGenerator

public DeviceResponseGenerator(long statusCode)

Creates a new DeviceResponseGenerator.

Parameters:

statusCode - the status code to use which must be one of Constants.DEVICE_RESPONSE_STATUS_OK, Constants.DEVICE_RESPONSE_STATUS_GENERAL_ERROR, Constants.DEVICE_RESPONSE_STATUS_CBOR_DECODING_ERROR, or Constants.DEVICE_RESPONSE_STATUS_CBOR_VALIDATION_ERROR.

Method Detail

addDocument

@NonNull
public DeviceResponseGenerator addDocument(@NonNull
                                           java.lang.String docType,
                                           @NonNull
                                           byte[] encodedDeviceNamespaces,
                                           @Nullable
                                           byte[] encodedDeviceSignature,
                                           @Nullable
                                           byte[] encodedDeviceMac,
                                           @NonNull
                                           java.util.Map<java.lang.String,java.util.List<byte[]>> issuerSignedData,
                                           @Nullable
                                           java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Long>> errors,
                                           @NonNull
                                           byte[] encodedIssuerAuth)

Adds a new document to the device response.

Issuer-signed data is provided in issuerSignedData which maps from namespaces into a list of bytes of IssuerSignedItem CBOR as defined in 18013-5 where each contains the digest-id, element name, issuer-generated random value and finally the element value. Each IssuerSignedItem must be encoded so the digest of them in a #6.24 bstr matches with the digests in the MobileSecurityObject in the issuerAuth parameter.

The encodedIssuerAuth parameter contains the bytes of the IssuerAuth CBOR as defined in ISO/IEC 18013-5 section 9.1.2.4 Signing method and structure for MSO. That is, the payload for this COSE_Sign1 must be set to the MobileSecurityObjectBytes and the public key used to sign the payload must be included in a x5chain unprotected header element.

For device-signed data, the parameters encodedDeviceNamespaces, encodedDeviceSignature, and encodedDeviceMac are used. Of the latter two, exactly one of them must be non-null. The DeviceNameSpaces CBOR specified in ISO/IEC 18013-5 section 8.3.2.1 Device retrieval is to be set in encodedDeviceNamespaces, and either a ECDSA signature or a MAC over the DeviceAuthentication CBOR as defined in section 9.1.3 mdoc authentication should be set in encodedDeviceSignature or encodedDeviceMac respectively. Values for all parameters can be obtained from the ResultData class from either the Framework or this library.

If present, the errors parameter is a map from namespaces where each value is a map from data elements in said namespace to an error code from ISO/IEC 18013-5:2021 Table 9.

Parameters:

docType - the document type, for example org.iso.18013.5.1.mDL.

encodedDeviceNamespaces - bytes of the DeviceNameSpaces CBOR.

encodedDeviceSignature - bytes of a COSE_Sign1 for authenticating the device data.

encodedDeviceMac - bytes of a COSE_Mac0 for authenticating the device data.

issuerSignedData - the map described above.

errors - a map with errors as described above.

encodedIssuerAuth - the bytes of the COSE_Sign1 described above.

Returns:

the passed-in DeviceResponseGenerator.

addDocument

@NonNull
public DeviceResponseGenerator addDocument(@NonNull
                                           java.lang.String docType,
                                           @NonNull
                                           CredentialDataResult credentialDataResult,
                                           @NonNull
                                           java.util.Map<java.lang.String,java.util.List<byte[]>> issuerSignedMapping,
                                           @Nullable
                                           java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Long>> errors,
                                           @NonNull
                                           byte[] encodedIssuerAuth)

Like addDocument(String, byte[], byte[], byte[], Map, Map, byte[]) but takes a CredentialDataResult instead and merges the results into the "elementValue" entry of each IssuerSignedItem value.

Note: The issuerSignedData and encodedIssuerAuth are parameters usually obtained via Utility.decodeStaticAuthData(byte[]).

Parameters:

docType - The type of the document to send.

credentialDataResult - The device- and issuer-signed data elements to include.

errors - A map with errors as described in addDocument.

issuerSignedMapping - A mapping from namespaces to an array of IssuerSignedItem CBOR for the namespace. The "elementValue" value in each IssuerSignedItem CBOR must be set to the NULL value.

encodedIssuerAuth - the bytes of COSE_Sign1 signed by the issuing authority and where the payload is set to MobileSecurityObjectBytes.

Returns:

the generator.

generate

@NonNull
public byte[] generate()

Builds the DeviceResponse CBOR.

Returns:

the bytes of DeviceResponse CBOR.