Package com.android.identity

Class VerificationHelper

  • public class VerificationHelper
extends java.lang.Object
    Helper used for engaging with and receiving documents from a remote mdoc verifier 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:2021.

    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.

    • Method Detail

      • nfcProcessOnTagDiscovered

        public void nfcProcessOnTagDiscovered​(@NonNull
                                      android.nfc.Tag tag)
        Processes a Tag received when in NFC reader mode.

        Applications should call this method in their NfcAdapter.ReaderCallback.onTagDiscovered(Tag) callback.

        Parameters:
        tag - the tag.
        Throws:
        java.lang.IllegalStateException - if called while not listening.

      • disconnect

        public void disconnect()
        Ends the session with the remote device.

        By default, ending a session involves sending a message to the remote device with empty data and the status code set to 20, meaning session termination as per ISO/IEC 18013-5. This can be configured using setSendSessionTerminationMessage(boolean) and setUseTransportSpecificSessionTermination(boolean).

        Some transports - such as BLE - supports a transport-specific session termination message instead of the generic one. By default this is not used but it can be enabled using setUseTransportSpecificSessionTermination(boolean).

        After calling this the current object can no longer be used to send requests.

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

      • sendRequest

        public void sendRequest​(@NonNull
                        byte[] deviceRequestBytes)
        Sends a request to the remote mdoc device.

        The deviceRequestBytes parameter must be DeviceRequest CBOR as specified in ISO/IEC 18013-5 section 8.3 Device Retrieval. The DeviceRequestGenerator class can be used to generate this.

        If a response to the request is received from the remote mdoc device, the VerificationHelper.Listener.onResponseReceived(byte[]) method is invoked. This will usually take several seconds as it typically involves authenticating the holder and asking for their consent to release identity data.

        This is usually called in response to VerificationHelper.Listener.onDeviceConnected() callback.

        Parameters:
        deviceRequestBytes - request message to the remote device

      • getSessionTranscript

        @NonNull
public byte[] getSessionTranscript()
        Gets the session transcript.

        This must not be called until engagement has been established with the mdoc device.

        Returns:
        the session transcript.
        Throws:
        java.lang.IllegalStateException - if called before engaging with mdoc device.

      • getEphemeralReaderKey

        @NonNull
public java.security.PrivateKey getEphemeralReaderKey()
        Gets the ephemeral key used by the reader for session encryption.

        This is made available because it's needed for mdoc verification when using the MAC mechanism.

        Returns:
        the ephemeral key used by the reader for session encryption.

      • 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 isTransportSpecificTerminationSupported() indicates that this is not available for the current transport this is a noop.

        Parameters:
        useTransportSpecificSessionTermination - Whether to use transport-specific session termination.

      • 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.