Added in API level 33

CredentialDataResult


abstract class CredentialDataResult
kotlin.Any
   ↳ android.security.identity.CredentialDataResult

An object that contains the result of retrieving data from a credential. This is used to return data requested in a PresentationSession.

Summary

Nested classes
abstract

A class for representing data elements returned.

Public methods
abstract ByteArray?

Returns a message authentication code over the DeviceAuthenticationBytes CBOR specified in getDeviceNameSpaces(), to prove to the reader that the data is from a trusted credential.

abstract ByteArray

Returns a CBOR structure containing the retrieved device-signed data.

open ByteArray?

Returns a signature over the DeviceAuthenticationBytes CBOR specified in getDeviceNameSpaces(), to prove to the reader that the data is from a trusted credential.

abstract CredentialDataResult.Entries

Gets the device-signed entries that was returned.

abstract CredentialDataResult.Entries

Gets the issuer-signed entries that was returned.

abstract ByteArray

Returns the static authentication data associated with the dynamic authentication key used to MAC the data returned by getDeviceNameSpaces().

Public methods

getDeviceMac

Added in API level 33
abstract fun getDeviceMac(): ByteArray?

Returns a message authentication code over the DeviceAuthenticationBytes CBOR specified in getDeviceNameSpaces(), to prove to the reader that the data is from a trusted credential.

The MAC proves to the reader that the data is from a trusted credential. This code is produced by using the key agreement and key derivation function from the ciphersuite with the authentication private key and the reader ephemeral public key to compute a shared message authentication code (MAC) key, then using the MAC function from the ciphersuite to compute a MAC of the authenticated data. See section 9.2.3.5 of ISO/IEC 18013-5 for details of this operation.

If the session transcript or reader ephemeral key wasn't set on the PresentationSession used to obtain this data no message authencation code will be produced and this method will return null.

Return
ByteArray? A COSE_Mac0 structure with the message authentication code as described above or null if the conditions specified above are not met.

getDeviceNameSpaces

Added in API level 33
abstract fun getDeviceNameSpaces(): ByteArray

Returns a CBOR structure containing the retrieved device-signed data.

This structure - along with the session transcript - may be cryptographically authenticated to prove to the reader that the data is from a trusted credential and getDeviceMac() can be used to get a MAC.

The CBOR structure which is cryptographically authenticated is the DeviceAuthenticationBytes structure according to the following CDDL schema:

DeviceAuthentication = [
      "DeviceAuthentication",
      SessionTranscript,
      DocType,
      DeviceNameSpacesBytes
    ]
 
    DocType = tstr
    SessionTranscript = any
    DeviceNameSpacesBytes = #6.24(bstr .cbor DeviceNameSpaces)
    DeviceAuthenticationBytes = #6.24(bstr .cbor DeviceAuthentication)
  

where

DeviceNameSpaces = {
      * NameSpace => DeviceSignedItems
    }
 
    DeviceSignedItems = {
      + DataItemName => DataItemValue
    }
 
    NameSpace = tstr
    DataItemName = tstr
    DataItemValue = any
  

The returned data is the binary encoding of the DeviceNameSpaces structure as defined above.

Return
ByteArray The bytes of the DeviceNameSpaces CBOR structure. This value cannot be null.

getDeviceSignature

Added in API level 34
open fun getDeviceSignature(): ByteArray?

Returns a signature over the DeviceAuthenticationBytes CBOR specified in getDeviceNameSpaces(), to prove to the reader that the data is from a trusted credential.

The signature is made using the authentication private key. See section 9.1.3.4 of ISO/IEC 18013-5:2021 for details of this operation.

If the session transcript or reader ephemeral key wasn't set on the PresentationSession used to obtain this data no signature will be produced and this method will return null.

This is only implemented in feature version 202301 or later. If not implemented, the call fails with UnsupportedOperationException. See android.content.pm.PackageManager#FEATURE_IDENTITY_CREDENTIAL_HARDWARE for known feature versions.

Return
ByteArray? A COSE_Sign1 structure as described above or null if the conditions specified above are not met.

getDeviceSignedEntries

Added in API level 33
abstract fun getDeviceSignedEntries(): CredentialDataResult.Entries

Gets the device-signed entries that was returned.

Return
CredentialDataResult.Entries an object to examine the entries returned. This value cannot be null.

getIssuerSignedEntries

Added in API level 33
abstract fun getIssuerSignedEntries(): CredentialDataResult.Entries

Gets the issuer-signed entries that was returned.

Return
CredentialDataResult.Entries an object to examine the entries returned. This value cannot be null.

getStaticAuthenticationData

Added in API level 33
abstract fun getStaticAuthenticationData(): ByteArray

Returns the static authentication data associated with the dynamic authentication key used to MAC the data returned by getDeviceNameSpaces().

Return
ByteArray The static authentication data associated with dynamic authentication key used to MAC the data. This value cannot be null.