IdentityCredential

public abstract class IdentityCredential
extends Object

java.lang.Object
   ↳ androidx.security.identity.IdentityCredential


Class used to read data from a previously provisioned credential. Use IdentityCredentialStore.getCredentialByName(String, int) to get a IdentityCredential instance.

Summary

Public methods

abstract KeyPair createEphemeralKeyPair()

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

abstract byte[] decryptMessageFromReader(byte[] messageCiphertext)

Decrypt a message received from the reader.

byte[] delete(byte[] challenge)

Deletes a credential.

abstract byte[] encryptMessageToReader(byte[] messagePlaintext)

Encrypt a message for transmission to the reader.

abstract Collection<X509Certificate> getAuthKeysNeedingCertification()

Gets a collection of dynamic authentication keys that need certification.

abstract int[] getAuthenticationDataUsageCount()

Get the number of times the dynamic authentication keys have been used.

abstract Collection<X509Certificate> getCredentialKeyCertificateChain()

Gets the X.509 certificate chain for the CredentialKey which identifies this credential to the issuing authority.

abstract BiometricPrompt.CryptoObject getCryptoObject()

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

abstract ResultData getEntries(byte[] requestMessage, Map<String, Collection<String>> entriesToRequest, byte[] readerSignature)

Retrieve data entries and associated data from this IdentityCredential.

byte[] proveOwnership(byte[] challenge)

Proves ownership of a credential.

abstract void setAllowUsingExhaustedKeys(boolean allowUsingExhaustedKeys)

Sets whether to allow using an authentication key which use count has been exceeded if no other key is available.

void setAllowUsingExpiredKeys(boolean allowUsingExpiredKeys)

Sets whether to allow using an authentication key which has been expired if no other key is available.

abstract void setAvailableAuthenticationKeys(int keyCount, int maxUsesPerKey)

Sets the number of dynamic authentication keys the IdentityCredential will maintain, and the number of times each should be used.

abstract void setReaderEphemeralPublicKey(PublicKey readerEphemeralPublicKey)

Set the ephemeral public key provided by the reader.

abstract void setSessionTranscript(byte[] sessionTranscript)

Set the session transcript.

abstract void storeStaticAuthenticationData(X509Certificate authenticationKey, byte[] staticAuthData)

This method is deprecated. Use storeStaticAuthenticationData(X509Certificate, Calendar, byte[]) instead.

void storeStaticAuthenticationData(X509Certificate authenticationKey, Calendar expirationDate, byte[] staticAuthData)

Store authentication data associated with a dynamic authentication key.

byte[] update(PersonalizationData personalizationData)

Updates the credential with new access control profiles and data items.

Inherited methods

Public methods

createEphemeralKeyPair

public abstract KeyPair createEphemeralKeyPair ()

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

Most applications will use only the public key, and only to send it to the reader, allowing the private key to be used internally for encryptMessageToReader(byte[]) and decryptMessageFromReader(byte[]). The private key is also provided for applications that wish to use a cipher suite that is not supported by IdentityCredentialStore.

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

decryptMessageFromReader

public abstract byte[] decryptMessageFromReader (byte[] messageCiphertext)

Decrypt a message received from the reader.

In order for this to work, setSessionTranscript(byte[]) and setReaderEphemeralPublicKey(PublicKey) must have already been called.

Parameters
messageCiphertext byte: encrypted message to decrypt.

Returns
byte[] decrypted message.

Throws
MessageDecryptionException if the ciphertext couldn't be decrypted.

delete

public byte[] delete (byte[] challenge)

Deletes a credential.

This method returns a COSE_Sign1 data structure signed by the CredentialKey with payload set to ProofOfDeletion as defined below.

     ProofOfDeletion = [
          "ProofOfDeletion",            ; tstr
          tstr,                         ; DocType
          bstr,                         ; Challenge
          bool                          ; true if this is a test credential, should
                                        ; always be false.
      ]
 

This is only implemented if IdentityCredentialStoreCapabilities.isDeleteSupported() returns true. If not the call fails with UnsupportedOperationException.

Parameters
challenge byte: is a non-empty byte array whose contents should be unique, fresh and provided by the issuing authority. The value provided is embedded in the generated CBOR and enables the issuing authority to verify that the returned proof is fresh.

Returns
byte[] the COSE_Sign1 data structure above

encryptMessageToReader

public abstract byte[] encryptMessageToReader (byte[] messagePlaintext)

Encrypt a message for transmission to the reader.

In order for this to work, setSessionTranscript(byte[]) and