Added in API level 30
Deprecated in API level 33

ResultData


public abstract class ResultData
extends Object

java.lang.Object
   ↳ android.security.identity.ResultData


This class was deprecated in API level 33.
Use PresentationSession instead.

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

Summary

Constants

int STATUS_NOT_IN_REQUEST_MESSAGE

The entry wasn't in the request message.

int STATUS_NOT_REQUESTED

The entry was not requested.

int STATUS_NO_ACCESS_CONTROL_PROFILES

The entry was not retrieved because it was configured without any access control profile.

int STATUS_NO_SUCH_ENTRY

The entry does not exist.

int STATUS_OK

Value was successfully retrieved.

int STATUS_READER_AUTHENTICATION_FAILED

The entry was not retrieved because reader authentication failed.

int STATUS_USER_AUTHENTICATION_FAILED

The entry was not retrieved because user authentication failed.

Public methods

abstract byte[] getAuthenticatedData()

Returns a CBOR structure containing the retrieved data.

abstract byte[] getEntry(String namespaceName, String name)

Gets the raw CBOR data for the value of an entry.

abstract Collection<String> getEntryNames(String namespaceName)

Get the names of all entries.

abstract byte[] getMessageAuthenticationCode()

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

abstract Collection<String> getNamespaces()

Gets the names of namespaces with retrieved entries.

abstract Collection<String> getRetrievedEntryNames(String namespaceName)

Get the names of all entries that was successfully retrieved.

abstract byte[] getStaticAuthenticationData()

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

abstract int getStatus(String namespaceName, String name)

Gets the status of an entry.

Inherited methods

Constants

STATUS_NOT_IN_REQUEST_MESSAGE

Added in API level 30
public static final int STATUS_NOT_IN_REQUEST_MESSAGE

The entry wasn't in the request message.

Constant Value: 3 (0x00000003)

STATUS_NOT_REQUESTED

Added in API level 30
public static final int STATUS_NOT_REQUESTED

The entry was not requested.

Constant Value: 2 (0x00000002)

STATUS_NO_ACCESS_CONTROL_PROFILES

Added in API level 30
public static final int STATUS_NO_ACCESS_CONTROL_PROFILES

The entry was not retrieved because it was configured without any access control profile.

Constant Value: 6 (0x00000006)

STATUS_NO_SUCH_ENTRY

Added in API level 30
public static final int STATUS_NO_SUCH_ENTRY

The entry does not exist.

Constant Value: 1 (0x00000001)

STATUS_OK

Added in API level 30
public static final int STATUS_OK

Value was successfully retrieved.

Constant Value: 0 (0x00000000)

STATUS_READER_AUTHENTICATION_FAILED

Added in API level 30
public static final int STATUS_READER_AUTHENTICATION_FAILED

The entry was not retrieved because reader authentication failed.

Constant Value: 5 (0x00000005)

STATUS_USER_AUTHENTICATION_FAILED

Added in API level 30
public static final int STATUS_USER_AUTHENTICATION_FAILED

The entry was not retrieved because user authentication failed.

Constant Value: 4 (0x00000004)

Public methods

getAuthenticatedData

Added in API level 30
public abstract byte[] getAuthenticatedData ()

Returns a CBOR structure containing the retrieved 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 getMessageAuthenticationCode() 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.

Returns
byte[] The bytes of the DeviceNameSpaces CBOR structure. This value cannot be null.

getEntry

Added in API level 30
public abstract byte[] getEntry (String namespaceName, 
                String name)

Gets the raw CBOR data for the value of an entry.

This should only be called on an entry for which the getStatus(java.lang.String, java.lang.String) method returns STATUS_OK.

Parameters
namespaceName String: the namespace name of the entry. This value cannot be null.

name String: the name of the entry to get the value for. This value cannot be null.

Returns
byte[] the raw CBOR data or null if no entry with the given name exists.

getEntryNames

Added in API level 30
public abstract Collection<String> getEntryNames (String namespaceName)

Get the names of all entries.

This includes the name of entries that wasn't successfully retrieved.

Parameters
namespaceName String: the namespace name to get entries for. This value cannot be null.

Returns
Collection<String> A collection of names or null if there are no entries for the given namespace.

getMessageAuthenticationCode

Added in API level 30
public abstract byte[] getMessageAuthenticationCode ()

Returns a message authentication code over the DeviceAuthenticationBytes CBOR specified in getAuthenticatedData(), 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 sessionTranscript parameter passed to IdentityCredential#getEntries(byte[], Map, byte[], byte[]) was null or the reader ephmeral public key was never set using IdentityCredential#setReaderEphemeralPublicKey(PublicKey), no message authencation code will be produced and this method will return null.

Returns
byte[] A COSE_Mac0 structure with the message authentication code as described above or null if the conditions specified above are not met.

getNamespaces

Added in API level 30
public abstract Collection<String> getNamespaces ()

Gets the names of namespaces with retrieved entries.

Returns
Collection<String> collection of name of namespaces containing retrieved entries. May be empty if no data was retrieved. This value cannot be null.

getRetrievedEntryNames

Added in API level 30
public abstract Collection<String> getRetrievedEntryNames (String namespaceName)

Get the names of all entries that was successfully retrieved.

This only return entries for which getStatus(java.lang.String, java.lang.String) will return STATUS_OK.

Parameters
namespaceName String: the namespace name to get entries for. This value cannot be null.

Returns
Collection<String> A collection of names or null if there are no entries for the given namespace.

getStaticAuthenticationData

Added in API level 30
public abstract byte[] getStaticAuthenticationData ()

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

Returns
byte[] The static authentication data associated with dynamic authentication key used to MAC the data. This value cannot be null.

getStatus

Added in API level 30
public abstract int getStatus (String namespaceName, 
                String name)

Gets the status of an entry.

This returns STATUS_OK if the value was retrieved, STATUS_NO_SUCH_ENTRY if the given entry wasn't retrieved, STATUS_NOT_REQUESTED if it wasn't requested, STATUS_NOT_IN_REQUEST_MESSAGE if the request message was set but the entry wasn't present in the request message, STATUS_USER_AUTHENTICATION_FAILED if the value wasn't retrieved because the necessary user authentication wasn't performed, STATUS_READER_AUTHENTICATION_FAILED if the supplied reader certificate chain didn't match the set of certificates the entry was provisioned with, or STATUS_NO_ACCESS_CONTROL_PROFILES if the entry was configured without any access control profiles.

Parameters
namespaceName String: the namespace name of the entry. This value cannot be null.

name String: the name of the entry to get the value for. This value cannot be null.

Returns
int the status indicating whether the value was retrieved and if not, why. Value is STATUS_OK, STATUS_NO_SUCH_ENTRY, STATUS_NOT_REQUESTED, STATUS_NOT_IN_REQUEST_MESSAGE, STATUS_USER_AUTHENTICATION_FAILED, STATUS_READER_AUTHENTICATION_FAILED, or STATUS_NO_ACCESS_CONTROL_PROFILES