IdentityCredential.GetEntries Method

Reference

Definition

Namespace:: Android.Security.Identity

Assembly:: Mono.Android.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Retrieve data entries and associated data from this IdentityCredential.

[Android.Runtime.Register("getEntries", "([BLjava/util/Map;[B[B)Landroid/security/identity/ResultData;", "GetGetEntries_arrayBLjava_util_Map_arrayBarrayBHandler", ApiSince=30)]
public abstract Android.Security.Identity.ResultData GetEntries (byte[]? requestMessage, System.Collections.Generic.IDictionary<string,System.Collections.Generic.ICollection<string>> entriesToRequest, byte[]? sessionTranscript, byte[]? readerSignature);

[<Android.Runtime.Register("getEntries", "([BLjava/util/Map;[B[B)Landroid/security/identity/ResultData;", "GetGetEntries_arrayBLjava_util_Map_arrayBarrayBHandler", ApiSince=30)>]
abstract member GetEntries : byte[] * System.Collections.Generic.IDictionary<string, System.Collections.Generic.ICollection<string>> * byte[] * byte[] -> Android.Security.Identity.ResultData

Parameters

requestMessage: Byte[]

If not null, must contain CBOR data conforming to the schema mentioned above.

entriesToRequest: IDictionary<String,ICollection<String>>

The entries to request, organized as a map of namespace names with each value being a collection of data elements in the given namespace.

sessionTranscript: Byte[]

readerSignature: Byte[]

A COSE_Sign1 structure as described above or null if reader authentication is not being used.

Returns

ResultData

A ResultData object containing entry data organized by namespace and a cryptographically authenticated representation of the same data.

Attributes: RegisterAttribute

Remarks

Retrieve data entries and associated data from this IdentityCredential.

If an access control check fails for one of the requested entries or if the entry doesn't exist, the entry is simply not returned. The application can detect this by using the ResultData#getStatus(String, String) method on each of the requested entries.

It is permissible to call this method multiple times using the same instance but if this is done, the sessionTranscript parameter must be identical for each call. If this is not the case, the SessionTranscriptMismatchException exception is thrown. Additionally, if this is done the same auth-key will be used.

The application should not make any assumptions on whether user authentication is needed. Instead, the application should request the data elements values first and then examine the returned ResultData. If ResultData#STATUS_USER_AUTHENTICATION_FAILED is returned the application should get a android.hardware.biometrics.BiometricPrompt.CryptoObject which references this object and use it with a android.hardware.biometrics.BiometricPrompt. Upon successful authentication the application may call #getEntries(byte[], Map, byte[], byte[]) again.

If not null the requestMessage parameter must contain data for the request from the verifier. The content can be defined in the way appropriate for the credential, but there are three requirements that must be met to work with this API: <ul> <li>The content must be a CBOR-encoded structure.</li> <li>The CBOR structure must be a map.</li> <li>The map must contain a tstr key "nameSpaces" whose value contains a map, as described in the example below.</li> </ul>

If these requirements are not met the InvalidRequestMessageException exception is thrown.

Here's an example of CBOR which conforms to this requirement:

ItemsRequest = {
                ? "docType" : DocType,
                "nameSpaces" : NameSpaces,
                ? "RequestInfo" : {* tstr => any} ; Additional info the reader wants to provide
              }

              DocType = tstr

              NameSpaces = {
                + NameSpace => DataElements    ; Requested data elements for each NameSpace
              }

              NameSpace = tstr

              DataElements = {
                + DataElement => IntentToRetain
              }

              DataElement = tstr
              IntentToRetain = bool

If mdoc session encryption is used (e.g. if #createEphemeralKeyPair() has been called) and if the sessionTranscript parameter is not null, the X and Y coordinates of the public part of the key-pair previously generated by #createEphemeralKeyPair() must appear somewhere in the bytes of the CBOR. Each of these coordinates must appear encoded with the most significant bits first and use the exact amount of bits indicated by the key size of the ephemeral keys. For example, if the ephemeral key is using the P-256 curve then the 32 bytes for the X coordinate encoded with the most significant bits first must appear somewhere in sessionTranscript and ditto for the 32 bytes for the Y coordinate.

If readerSignature is not null it must be the bytes of a COSE_Sign1 structure as defined in RFC 8152. For the payload nil shall be used and the detached payload is the ReaderAuthenticationBytes CBOR described below.

ReaderAuthentication = [
                  "ReaderAuthentication",
                  SessionTranscript,
                  ItemsRequestBytes
                ]

                ItemsRequestBytes = #6.24(bstr .cbor ItemsRequest)

                ReaderAuthenticationBytes = #6.24(bstr .cbor ReaderAuthentication)

where ItemsRequestBytes are the bytes in the requestMessage parameter.

The public key corresponding to the key used to make the signature, can be found in the x5chain unprotected header element of the COSE_Sign1 structure (as as described in draft-ietf-cose-x509-04). There will be at least one certificate in said element and there may be more (and if so, each certificate must be signed by its successor).

Data elements protected by reader authentication are returned if, and only if, they are mentioned in requestMessage, requestMessage is signed by the top-most certificate in the reader's certificate chain, and the data element is configured with an AccessControlProfile configured with an X.509 certificate which appears in the certificate chain.

Note that only items referenced in entriesToRequest are returned - the requestMessage parameter is used only for enforcing reader authentication.

The reason for having requestMessage and entriesToRequest as separate parameters is that the former represents a request from the remote verifier device (optionally signed) and this allows the application to filter the request to not include data elements which the user has not consented to sharing.

This member is deprecated. Use PresentationSession instead.

Java documentation for android.security.identity.IdentityCredential.getEntries(byte[], java.util.Map<java.lang.String, java.util.Collection<java.lang.String>>, byte[], byte[]).

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

Applies to