Package com.android.identity

Class PresentationSession

java.lang.Object

com.android.identity.PresentationSession

Direct Known Subclasses:

HardwarePresentationSession

public abstract class PresentationSession
extends java.lang.Object

Class for presenting multiple documents to a remote verifier.

This should be used for all interactions with a remote verifier instead of the now deprecated IdentityCredential.getEntries(byte[], Map, byte[]) method. Use IdentityCredentialStore.createPresentationSession(int) to create a PresentationSession instance.

Method Summary

Modifier and Type	Method	Description
abstract CredentialDataResult	getCredentialData(java.lang.String credentialName, CredentialDataRequest request)	Retrieves data from a named credential in the current presentation session.
abstract androidx.biometric.BiometricPrompt.CryptoObject	getCryptoObject()	Gets a BiometricPrompt.CryptoObject which can be used with this PresentationSession.
abstract java.security.KeyPair	getEphemeralKeyPair()	Gets the ephemeral key pair to use to establish a secure channel with the verifier.
abstract void	setReaderEphemeralPublicKey(java.security.PublicKey readerEphemeralPublicKey)	Set the ephemeral public key provided by the verifier.
abstract void	setSessionTranscript(byte[] sessionTranscript)	Set the session transcript.

Methods inherited from class java.lang.Object

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

Method Detail

getEphemeralKeyPair

@NonNull
public abstract java.security.KeyPair getEphemeralKeyPair()

Gets the ephemeral key pair to use to establish a secure channel with the verifier.

Applications should use this key-pair for the communications channel with the verifier using a protocol / cipher-suite appropriate for the application. One example of such a protocol is the one used for Mobile Driving Licenses, see ISO 18013-5.

Returns:

ephemeral key pair to use to establish a secure channel with a reader.

setReaderEphemeralPublicKey

public abstract void setReaderEphemeralPublicKey(@NonNull
                                                 java.security.PublicKey readerEphemeralPublicKey)
                                          throws java.security.InvalidKeyException

Set the ephemeral public key provided by the verifier.

If called, this must be called before any calls to getCredentialData(String, CredentialDataRequest).

This method can only be called once per PresentationSession instance.

Parameters:

readerEphemeralPublicKey - The ephemeral public key provided by the reader to establish a secure session.

Throws:

java.security.InvalidKeyException - if the given key is invalid.

setSessionTranscript

public abstract void setSessionTranscript(@NonNull
                                          byte[] sessionTranscript)

Set the session transcript.

If called, this must be called before any calls to getCredentialData(String, CredentialDataRequest).

The X and Y coordinates of the public part of the key-pair returned by getEphemeralKeyPair() must appear somewhere in the bytes of the passed in 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 and ditto for the 32 bytes for the Y coordinate.

This method can only be called once per PresentationSession instance.

Parameters:

sessionTranscript - the session transcript.

getCredentialData

@Nullable
public abstract CredentialDataResult getCredentialData(@NonNull
                                                       java.lang.String credentialName,
                                                       @NonNull
                                                       CredentialDataRequest request)
                                                throws NoAuthenticationKeyAvailableException,
                                                       InvalidReaderSignatureException,
                                                       InvalidRequestMessageException,
                                                       EphemeralPublicKeyNotFoundException

Retrieves data from a named credential in the current presentation session.

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 CredentialDataResult.Entries.getStatus(String, String) method on each of the requested entries.

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 CredentialDataResult. If CredentialDataResult.Entries.STATUS_USER_AUTHENTICATION_FAILED is returned the application should call getCryptoObject() and use the returned BiometricPrompt.CryptoObject with a BiometricPrompt. Upon successful authentication the application may call getCredentialData(String, CredentialDataRequest) again.

It is permissible to call this method multiple times using the same credential name. If this is done the same auth-key will be used.

If the reader signature is set in the request parameter (via the CredentialDataRequest.Builder.setReaderSignature(byte[]) method) it must contain 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 of the request message set in the request parameter (via the CredentialDataRequest.Builder.setRequestMessage(byte[]) method).

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-08). 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, 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 for a key which appear in the certificate chain.

Note that the request message CBOR is used only for enforcing reader authentication, it's not used for determining which entries this API will return. The application is expected to have parsed the request message and filtered it according to user preference and/or consent.

Parameters:

credentialName - the name of the credential to retrieve.

request - the data to retrieve from the credential

Returns:

If the credential wasn't found, returns null. Otherwise a CredentialDataResult object containing entry data organized by namespace and a cryptographically authenticated representation of the same data, bound to the current session.

Throws:

NoAuthenticationKeyAvailableException - if authentication keys were never provisioned for the credential or if they are expired or exhausted their use-count.

InvalidRequestMessageException - if the requestMessage is malformed.

InvalidReaderSignatureException - if the reader signature is invalid, or it doesn't contain a certificate chain, or if the signature failed to validate.

EphemeralPublicKeyNotFoundException - if the ephemeral public key was not found in the session transcript.

CredentialInvalidatedException - if the credential has been invalidated

getCryptoObject

@Nullable
public abstract androidx.biometric.BiometricPrompt.CryptoObject getCryptoObject()

Gets a BiometricPrompt.CryptoObject which can be used with this PresentationSession.

If IdentityCredential is hardware-backed, the returned BiometricPrompt.CryptoObject is associated android.security.identity.PresentationSession object from the Android Framework. If it's not hardware-backed it's not defined which kind of object it's associated with. Because of this, this method is the preferred way to obtain a BiometricPrompt.CryptoObject rather than to construct it manually.

If no biometrics are enrolled on the device or if the device doesn't support biometrics the value null may be returned. This just means the application won't have a BiometricPrompt.CryptoObject to pass to BiometricPrompt and will have to pass null instead.

Returns:

A BiometricPrompt.CryptoObject which can be used with BiometricPrompt.