Package com.android.identity

Class Utility

java.lang.Object

com.android.identity.Utility

public class Utility
extends java.lang.Object

Miscellaneous utility functions that are useful when building mdoc applications.

Method Summary

Modifier and Type	Method	Description
static androidx.core.util.Pair<java.util.Map<java.lang.String,java.util.List<byte[]>>,byte[]>	decodeStaticAuthData(byte[] staticAuthData)	Helper to decode staticAuthData in the format specified by the encodeStaticAuthData(Map, byte[]) method.
static byte[]	encodeStaticAuthData(java.util.Map<java.lang.String,java.util.List<byte[]>> issuerSignedMapping, byte[] encodedIssuerAuth)	Helper to encode digest-id mapping and issuerAuth CBOR into a single byte array.
static java.util.Map<java.lang.String,java.util.List<byte[]>>	mergeIssuerSigned(java.util.Map<java.lang.String,java.util.List<byte[]>> issuerSignedMapping, CredentialDataResult.Entries issuerSigned)	Merges issuer-signed data with credential result data.
static byte[]	provisionSelfSignedCredential(IdentityCredentialStore store, java.lang.String credentialName, java.security.PrivateKey issuingAuthorityKey, java.security.cert.X509Certificate issuingAuthorityCertificate, java.lang.String docType, PersonalizationData personalizationData, int numAuthKeys, int maxUsesPerKey)	Helper function to create a self-signed credential, including authentication keys and static authentication data.

Methods inherited from class java.lang.Object

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

Method Detail

encodeStaticAuthData

@NonNull
public static byte[] encodeStaticAuthData(@NonNull
                                          java.util.Map<java.lang.String,java.util.List<byte[]>> issuerSignedMapping,
                                          @NonNull
                                          byte[] encodedIssuerAuth)

Helper to encode digest-id mapping and issuerAuth CBOR into a single byte array.

The resulting byte array can be stored as staticAuthData using IdentityCredential.storeStaticAuthenticationData(X509Certificate, Calendar, byte[]) and returned using ResultData.getStaticAuthenticationData() at presentation time.

Use decodeStaticAuthData(byte[]) for the reverse operation.

The returned data are the bytes of CBOR with the following CDDL:

     StaticAuthData = {
         "digestIdMapping": DigestIdMapping,
         "issuerAuth" : IssuerAuth
     }

     DigestIdMapping = {
         NameSpace => [ + IssuerSignedItemBytes ]
     }

     ; Defined in ISO 18013-5
     ;
     NameSpace = String
     DataElementIdentifier = String
     DigestID = uint
     IssuerAuth = COSE_Sign1 ; The payload is MobileSecurityObjectBytes

     IssuerSignedItemBytes = #6.24(bstr .cbor IssuerSignedItem)

     IssuerSignedItem = {
       "digestID" : uint,                           ; Digest ID for issuer data auth
       "random" : bstr,                             ; Random value for issuer data auth
       "elementIdentifier" : DataElementIdentifier, ; Data element identifier
       "elementValue" : NULL                        ; Placeholder for Data element value
     }
 

Note that the the byte[] arrays returned in the list of map values are the bytes of IssuerSignedItem, not IssuerSignedItemBytes.

Parameters:

issuerSignedMapping - A mapping from namespaces into a list of the bytes of IssuerSignedItem (not tagged). The elementValue key must be present and set to the NULL value.

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

Returns:

the bytes of the CBOR described above.

decodeStaticAuthData

@NonNull
public static androidx.core.util.Pair<java.util.Map<java.lang.String,java.util.List<byte[]>>,byte[]> decodeStaticAuthData(@NonNull
                                                                                                                                      byte[] staticAuthData)

Helper to decode staticAuthData in the format specified by the encodeStaticAuthData(Map, byte[]) method.

Note that the the byte[] arrays returned in the list of map values are the bytes of IssuerSignedItem, not IssuerSignedItemBytes.

Parameters:

staticAuthData - the bytes of CBOR as described above.

Returns:

issuerSignedMapping and encodedIssuerAuth.

Throws:

java.lang.IllegalArgumentException - if the given data is not in the format specified by the encodeStaticAuthData(Map, byte[]) method.

provisionSelfSignedCredential

@NonNull
public static byte[] provisionSelfSignedCredential(@NonNull
                                                   IdentityCredentialStore store,
                                                   @NonNull
                                                   java.lang.String credentialName,
                                                   @NonNull
                                                   java.security.PrivateKey issuingAuthorityKey,
                                                   @NonNull
                                                   java.security.cert.X509Certificate issuingAuthorityCertificate,
                                                   @NonNull
                                                   java.lang.String docType,
                                                   @NonNull
                                                   PersonalizationData personalizationData,
                                                   int numAuthKeys,
                                                   int maxUsesPerKey)
                                            throws IdentityCredentialException

Helper function to create a self-signed credential, including authentication keys and static authentication data.

The created authentication keys will have associated staticAuthData which is encoded in the same format as returned by the encodeStaticAuthData(Map, byte[]) helper method meaning that at presentation-time the decodeStaticAuthData(byte[]) helper can be used to recover the digest-id mapping and IssuerAuth CBOR.

This helper is useful only when developing mdoc applications that are not yet using a live issuing authority.

Parameters:

store - the IdentityCredentialStore to create the credential in.

credentialName - name to use for the credential, e.g. "test".

issuingAuthorityKey - the private key to use for signing the static auth data.

issuingAuthorityCertificate - the certificate corresponding the signing key.

docType - the document type of the credential, e.g. "org.iso .18013.5.1.mDL".

personalizationData - the data to put in the document, organized by namespace.

numAuthKeys - number of authentication keys to create.

maxUsesPerKey - number of uses for each authentication key.

Returns:

bytes of a COSE_Sign1 for proof of provisioning

Throws:

IdentityCredentialException - if the given data is not in the correct format

mergeIssuerSigned

@NonNull
public static java.util.Map<java.lang.String,java.util.List<byte[]>> mergeIssuerSigned(@NonNull
                                                                                             java.util.Map<java.lang.String,java.util.List<byte[]>> issuerSignedMapping,
                                                                                             @NonNull
                                                                                             CredentialDataResult.Entries issuerSigned)

Merges issuer-signed data with credential result data.

Parameters:

issuerSignedMapping - A mapping obtained from decodeStaticAuthData(byte[]).

issuerSigned - Data values from a credential.

Returns:

The given mapping but where each encodedIssuerAuth has the given data values filled in.