Package com.android.identity

Class DeviceRetrievalHelper

java.lang.Object

com.android.identity.DeviceRetrievalHelper

public class DeviceRetrievalHelper
extends java.lang.Object

Helper used for establishing engagement with, interacting with, and presenting credentials to a remote mdoc reader device.

This class implements the interface between an mdoc and mdoc verifier using the connection setup and device retrieval interfaces defined in ISO/IEC 18013-5.

Reverse engagement as per drafts of 18013-7 and 23220-4 is supported. These protocols are not finalized so should only be used for testing.

As with PresentationSession, instances of this class are only good for a single session with a remote reader. Once a session ends (indicated by e.g. DeviceRetrievalHelper.Listener.onDeviceDisconnected(boolean) or DeviceRetrievalHelper.Listener.onError(Throwable) the object should no longer be used.

Unlike IdentityCredentialStore, IdentityCredential, WritableIdentityCredential, and PresentationSession this class is never backed by secure hardware and is entirely implemented in the library. The class does however depend on data returned by PresentationSession.getCredentialData(String, CredentialDataRequest) which may be backed by secure hardware.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	DeviceRetrievalHelper.Builder	Builder for DeviceRetrievalHelper.
static interface	DeviceRetrievalHelper.Listener	Interface for listening to messages from the remote verifier device.

Method Summary

Modifier and Type	Method	Description
void	disconnect()	Stops the presentation and shuts down the transport.
byte[]	getDeviceEngagement()
byte[]	getSessionTranscript()	Gets the session transcript.
boolean	isTransportSpecificTerminationSupported()	Returns whether transport specific termination is available for the current connection.
void	sendDeviceResponse(byte[] deviceResponseBytes)	Send a response to the remote mdoc verifier.
void	sendDeviceResponse(byte[] deviceResponseBytes, TransmissionProgressListener progressListener, java.util.concurrent.Executor progressExecutor)	Send a response to the remote mdoc verifier.
void	setSendSessionTerminationMessage(boolean sendSessionTerminationMessage)	Sets whether to send session termination message.
void	setUseTransportSpecificSessionTermination(boolean useTransportSpecificSessionTermination)	Sets whether to use transport-specific session termination.

Methods inherited from class java.lang.Object

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

Method Detail

getSessionTranscript

@NonNull
public byte[] getSessionTranscript()

Gets the session transcript.

This must not be called until a message has been received from the mdoc verifier.

See ISO/IEC 18013-5 for the definition of the bytes in the session transcript.

Returns:

the session transcript.

Throws:

java.lang.IllegalStateException - if called before a message is received from the verifier.

getDeviceEngagement

@NonNull
public byte[] getDeviceEngagement()

sendDeviceResponse

public void sendDeviceResponse(@NonNull
                               byte[] deviceResponseBytes)

Send a response to the remote mdoc verifier.

This is typically called in response to the DeviceRetrievalHelper.Listener.onDeviceRequest(byte[]) callback.

The deviceResponseBytes parameter should contain CBOR conforming to DeviceResponse CBOR as specified in ISO/IEC 18013-5 section 8.3 Device Retrieval. This can be generated using DeviceResponseGenerator.

Parameters:

deviceResponseBytes - the response to send.

sendDeviceResponse

public void sendDeviceResponse(@NonNull
                               byte[] deviceResponseBytes,
                               @Nullable
                               TransmissionProgressListener progressListener,
                               @Nullable
                               java.util.concurrent.Executor progressExecutor)

Send a response to the remote mdoc verifier.

This is typically called in response to the DeviceRetrievalHelper.Listener.onDeviceRequest(byte[]) callback.

The deviceResponseBytes parameter should contain CBOR conforming to DeviceResponse CBOR as specified in ISO/IEC 18013-5 section 8.3 Device Retrieval. This can be generated using DeviceResponseGenerator.

Parameters:

deviceResponseBytes - the response to send.

progressListener - a progress listener that will subscribe to updates or null

progressExecutor - a Executor to do the progress listener updates in, or null (required if progressListener is non-null

disconnect

public void disconnect()

Stops the presentation and shuts down the transport.

If connected to a mdoc verifier also sends a session termination message prior to disconnecting if applicable. See setSendSessionTerminationMessage(boolean) and setUseTransportSpecificSessionTermination(boolean) for how to configure this.

No callbacks will be done on a listener after calling this.

This method is idempotent so it is safe to call multiple times.

setUseTransportSpecificSessionTermination

public void setUseTransportSpecificSessionTermination(boolean useTransportSpecificSessionTermination)

Sets whether to use transport-specific session termination.

By default this is set to false.

As per ISO/IEC 18013-5 transport-specific session-termination is currently only supported for BLE. The isTransportSpecificTerminationSupported() method can be used to determine whether it's available for the current transport. If the current transport does not support the feature, then this method is a noop.

Parameters:

useTransportSpecificSessionTermination - Whether to use transport-specific session

isTransportSpecificTerminationSupported

public boolean isTransportSpecificTerminationSupported()

Returns whether transport specific termination is available for the current connection. See setUseTransportSpecificSessionTermination(boolean) for more information about what transport specific session termination is.

Returns:

true if transport specific termination is available, false if not or if not connected.

setSendSessionTerminationMessage

public void setSendSessionTerminationMessage(boolean sendSessionTerminationMessage)

Sets whether to send session termination message.

This controls whether a session termination message is sent when disconnect() is called. Most applications would want to do this as it is required by ISO/IEC 18013-5.

By default this is set to true.

Parameters:

sendSessionTerminationMessage - Whether to send session termination message.