IdentityCredential
abstract class IdentityCredential
kotlin.Any | |
↳ | android.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 |
Create an ephemeral key pair to use to establish a secure channel with a reader. |
abstract ByteArray |
decryptMessageFromReader(messageCiphertext: ByteArray) Decrypt a message received from the reader. |
open ByteArray |
Deletes a credential. |
abstract ByteArray |
encryptMessageToReader(messagePlaintext: ByteArray) Encrypt a message for transmission to the reader. |
abstract MutableCollection<X509Certificate!> |
Gets a collection of dynamic authentication keys that need certification. |
abstract IntArray |
Get the number of times the dynamic authentication keys have been used. |
open MutableList<AuthenticationKeyMetadata!> |
Get information about dynamic authentication keys. |
abstract MutableCollection<X509Certificate!> |
Gets the X. |
abstract ResultData |
getEntries(requestMessage: ByteArray?, entriesToRequest: MutableMap<String!, MutableCollection<String!>!>, sessionTranscript: ByteArray?, readerSignature: ByteArray?) Retrieve data entries and associated data from this |
open ByteArray |
proveOwnership(challenge: ByteArray) Proves ownership of a credential. |
abstract Unit |
setAllowUsingExhaustedKeys(allowUsingExhaustedKeys: Boolean) Sets whether to allow using an authentication key which use count has been exceeded if no other key is available. |
open Unit |
setAllowUsingExpiredKeys(allowUsingExpiredKeys: Boolean) Sets whether to allow using an authentication key which has been expired if no other key is available. |
abstract Unit |
setAvailableAuthenticationKeys(keyCount: Int, maxUsesPerKey: Int) Sets the number of dynamic authentication keys the |
open Unit |
setAvailableAuthenticationKeys(keyCount: Int, maxUsesPerKey: Int, minValidTimeMillis: Long) Sets the number of dynamic authentication keys the |
abstract Unit |
setReaderEphemeralPublicKey(readerEphemeralPublicKey: PublicKey) Set the ephemeral public key provided by the reader. |
abstract Unit |
storeStaticAuthenticationData(authenticationKey: X509Certificate, staticAuthData: ByteArray) Store authentication data associated with a dynamic authentication key. |
open Unit |
storeStaticAuthenticationData(authenticationKey: X509Certificate, expirationDate: Instant, staticAuthData: ByteArray) Store authentication data associated with a dynamic authentication key. |
open ByteArray |
update(personalizationData: PersonalizationData) Updates the credential with new access control profiles and data items. |
Public methods
createEphemeralKeyPair
abstract funcreateEphemeralKeyPair(): KeyPair
Deprecated: Use PresentationSession
instead.
Create an ephemeral key pair to use to establish a secure channel with a reader.
Applications should use this key-pair for the communications channel with the reader 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 section 9.2.1 "Session encryption".
Return | |
---|---|
KeyPair |
ephemeral key pair to use to establish a secure channel with a reader. This value cannot be null . |
decryptMessageFromReader
abstract fundecryptMessageFromReader(messageCiphertext: ByteArray): ByteArray
Deprecated: Applications should use PresentationSession
and implement encryption/decryption themselves.
Decrypt a message received from the reader.
Do not use. In this version of the API, this method produces an incorrect result. Instead, applications should implement message encryption/decryption themselves as detailed in the createEphemeralKeyPair()
method. In a future API-level, this method will be deprecated.
Parameters | |
---|---|
messageCiphertext |
ByteArray: encrypted message to decrypt. This value cannot be null . |
Return | |
---|---|
ByteArray |
decrypted message. This value cannot be null . |
Exceptions | |
---|---|
android.security.identity.MessageDecryptionException |
if the ciphertext couldn't be decrypted. |
delete
open fun delete(challenge: ByteArray): ByteArray
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 in feature version 202101 or later. If not implemented, the call fails with UnsupportedOperationException
. See android.content.pm.PackageManager#FEATURE_IDENTITY_CREDENTIAL_HARDWARE
for known feature versions.
Parameters | |
---|---|
challenge |
ByteArray: 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. Implementations are required to support challenges at least 32 bytes of length. This value cannot be null . |
Return | |
---|---|
ByteArray |
the COSE_Sign1 data structure above This value cannot be null . |
encryptMessageToReader
abstract funencryptMessageToReader(messagePlaintext: ByteArray): ByteArray
Deprecated: Applications should use PresentationSession
and implement encryption/decryption themselves.
Encrypt a message for transmission to the reader.
Do not use. In this version of the API, this method produces an incorrect result. Instead, applications should implement message encryption/decryption themselves as detailed in the createEphemeralKeyPair()
method. In a future API-level, this method will be deprecated.
Parameters | |
---|---|
messagePlaintext |
ByteArray: unencrypted message to encrypt. This value cannot be null . |
Return | |
---|---|
ByteArray |
encrypted message. This value cannot be null . |
getAuthKeysNeedingCertification
abstract fun getAuthKeysNeedingCertification(): MutableCollection<X509Certificate!>
Gets a collection of dynamic authentication keys that need certification.
When there aren't enough certified dynamic authentication keys, either because the key count has been increased or because one or more keys have reached their usage count or it if a key is too close to its expiration date, this method will generate replacement keys and certificates and return them for issuer certification. The issuer certificates and associated static authentication data must then be provided back to the Identity Credential using storeStaticAuthenticationData(java.security.cert.X509Certificate,byte[])
. The private part of each authentication key never leaves secure hardware.
Each X.509 certificate is signed by CredentialKey. The certificate chain for CredentialKey can be obtained using the getCredentialKeyCertificateChain()
method.
If the implementation is feature version 202101 or later, each X.509 certificate contains an X.509 extension at OID 1.3.6.1.4.1.11129.2.1.26 which contains a DER encoded OCTET STRING with the bytes of the CBOR with the following CDDL:
ProofOfBinding = [ "ProofOfBinding", bstr, // Contains SHA-256(ProofOfProvisioning) ]
This CBOR enables an issuer to determine the exact state of the credential it returns issuer-signed data for.
See android.content.pm.PackageManager#FEATURE_IDENTITY_CREDENTIAL_HARDWARE
for known feature versions.
Return | |
---|---|
MutableCollection<X509Certificate!> |
A collection of X.509 certificates for dynamic authentication keys that need issuer certification. This value cannot be null . |
getAuthenticationDataUsageCount
abstract fungetAuthenticationDataUsageCount(): IntArray
Deprecated: Use getAuthenticationKeyMetadata()
instead.
Get the number of times the dynamic authentication keys have been used.
Return | |
---|---|
IntArray |
int array of dynamic authentication key usage counts. This value cannot be null . |
getAuthenticationKeyMetadata
open fun getAuthenticationKeyMetadata(): MutableList<AuthenticationKeyMetadata!>
Get information about dynamic authentication keys.
The returned list may have null
values if certification for the dynamic authentication key is pending.
The list is always keyCount
elements long.
Return | |
---|---|
MutableList<AuthenticationKeyMetadata!> |
list of authentication key metadata objects. |
getCredentialKeyCertificateChain
abstract fun getCredentialKeyCertificateChain(): MutableCollection<X509Certificate!>
Gets the X.509 certificate chain for the CredentialKey which identifies this credential to the issuing authority. This is the same certificate chain that was returned by WritableIdentityCredential#getCredentialKeyCertificateChain(byte[])
when the credential was first created and its Android Keystore extension will contain the challenge
data set at that time. See the documentation for that method for important information about this certificate chain.
Return | |
---|---|
MutableCollection<X509Certificate!> |
the certificate chain for this credential's CredentialKey. This value cannot be null . |
getEntries
abstract fungetEntries(
requestMessage: ByteArray?,
entriesToRequest: MutableMap<String!, MutableCollection<String!>!>,
sessionTranscript: ByteArray?,
readerSignature: ByteArray?
): ResultData
Deprecated: Use PresentationSession
instead.
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[],java.util.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:
- The content must be a CBOR-encoded structure.
- The CBOR structure must be a map.
- The map must contain a tstr key "nameSpaces" whose value contains a map, as described in the example below.
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.
Parameters | |
---|---|
requestMessage |
ByteArray?: If not null , must contain CBOR data conforming to the schema mentioned above. |
entriesToRequest |
MutableMap<String!, MutableCollection<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. This value cannot be null . |
readerSignature |
ByteArray?: A COSE_Sign1 structure as described above or null if reader authentication is not being used. |
sessionTranscript |
ByteArray?: This value may be null . |
Return | |
---|---|
ResultData |
A ResultData object containing entry data organized by namespace and a cryptographically authenticated representation of the same data. |
Exceptions | |
---|---|
android.security.identity.SessionTranscriptMismatchException |
Thrown when trying use multiple different session transcripts. |
android.security.identity.NoAuthenticationKeyAvailableException |
if authentication keys were never provisioned, the method setAvailableAuthenticationKeys(int,int,long) was called with keyCount set to 0, the method setAllowUsingExhaustedKeys(boolean) was called with false and all available authentication keys have been exhausted. |
android.security.identity.InvalidReaderSignatureException |
if the reader signature is invalid, or it doesn't contain a certificate chain, or if the signature failed to validate. |
android.security.identity.InvalidRequestMessageException |
if the requestMessage is malformed. |
android.security.identity.EphemeralPublicKeyNotFoundException |
if the ephemeral public key was not found in the session transcript. |
proveOwnership
open fun proveOwnership(challenge: ByteArray): ByteArray
Proves ownership of a credential.
This method returns a COSE_Sign1 data structure signed by the CredentialKey with payload set to ProofOfDeletion
as defined below.
The returned CBOR is the following:
ProofOfOwnership = [ "ProofOfOwnership", ; tstr tstr, ; DocType bstr, ; Challenge bool ; true if this is a test credential, should ; always be false. ]
This is only implemented in feature version 202101 or later. If not implemented, the call fails with UnsupportedOperationException
. See android.content.pm.PackageManager#FEATURE_IDENTITY_CREDENTIAL_HARDWARE
for known feature versions.
Parameters | |
---|---|
challenge |
ByteArray: 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. Implementations are required to support challenges at least 32 bytes of length. This value cannot be null . |
Return | |
---|---|
ByteArray |
the COSE_Sign1 data structure above This value cannot be null . |
setAllowUsingExhaustedKeys
abstract funsetAllowUsingExhaustedKeys(allowUsingExhaustedKeys: Boolean): Unit
Deprecated: Use PresentationSession
instead.
Sets whether to allow using an authentication key which use count has been exceeded if no other key is available. This must be called prior to calling getEntries(byte[],java.util.Map,byte[],byte[])
. By default this is set to true.
Parameters | |
---|---|
allowUsingExhaustedKeys |
Boolean: whether to allow using an authentication key which use count has been exceeded if no other key is available. |
setAllowUsingExpiredKeys
open funsetAllowUsingExpiredKeys(allowUsingExpiredKeys: Boolean): Unit
Deprecated: Use PresentationSession
instead.
Sets whether to allow using an authentication key which has been expired if no other key is available. This must be called prior to calling getEntries(byte[],java.util.Map,byte[],byte[])
.
By default this is set to false.
This is only implemented in feature version 202101 or later. If not implemented, the call fails with UnsupportedOperationException
. See android.content.pm.PackageManager#FEATURE_IDENTITY_CREDENTIAL_HARDWARE
for known feature versions.
Parameters | |
---|---|
allowUsingExpiredKeys |
Boolean: whether to allow using an authentication key which use count has been exceeded if no other key is available. |
setAvailableAuthenticationKeys
abstract funsetAvailableAuthenticationKeys(
keyCount: Int,
maxUsesPerKey: Int
): Unit
Deprecated: Use setAvailableAuthenticationKeys(int,int,long)
instead.
Sets the number of dynamic authentication keys the IdentityCredential
will maintain, and the number of times each should be used.
The Identity Credential system will select the least-used dynamic authentication key each time getEntries(byte[],java.util.Map,byte[],byte[])
is called. Identity Credentials for which this method has not been called behave as though it had been called wit keyCount
0 and maxUsesPerKey
1.
The effect of this method is like calling setAvailableAuthenticationKeys(int,int,long)
with the last parameter is set to 0.
Parameters | |
---|---|
keyCount |
Int: The number of active, certified dynamic authentication keys the IdentityCredential will try to keep available. This value must be non-negative. |
maxUsesPerKey |
Int: The maximum number of times each of the keys will be used before it's eligible for replacement. This value must be greater than zero. |
setAvailableAuthenticationKeys
open fun setAvailableAuthenticationKeys(
keyCount: Int,
maxUsesPerKey: Int,
minValidTimeMillis: Long
): Unit
Sets the number of dynamic authentication keys the IdentityCredential
will maintain, the number of times each should be used, and the minimum amount of time it's valid for.
The Identity Credential system will select the least-used dynamic authentication key each time getEntries(byte[],java.util.Map,byte[],byte[])
is called. Identity Credentials for which this method has not been called behave as though it had been called wit keyCount
0, maxUsesPerKey
1, and minValidTimeMillis
0.
Applications can use getAuthenticationKeyMetadata()
to get a picture of the usage andtime left of each configured authentication key. This can be used to determine how urgent it is recertify new authentication keys via the getAuthKeysNeedingCertification()
method.
Parameters | |
---|---|
keyCount |
Int: The number of active, certified dynamic authentication keys the IdentityCredential will try to keep available. This value must be non-negative. Value is 0 or greater |
maxUsesPerKey |
Int: The maximum number of times each of the keys will be used before it's eligible for replacement. This value must be greater than zero. Value is 1 or greater |
minValidTimeMillis |
Long: If a key has less time left than this value it will be eliglible for replacement. This value must be non-negative. Value is 0 or greater |
setReaderEphemeralPublicKey
abstract funsetReaderEphemeralPublicKey(readerEphemeralPublicKey: PublicKey): Unit
Deprecated: Use PresentationSession
instead.
Set the ephemeral public key provided by the reader. If called, this must be called before getEntries(byte[],java.util.Map,byte[],byte[])
is called.
Parameters | |
---|---|
readerEphemeralPublicKey |
PublicKey: The ephemeral public key provided by the reader to establish a secure session. This value cannot be null . |
Exceptions | |
---|---|
java.security.InvalidKeyException |
if the given key is invalid. |
storeStaticAuthenticationData
abstract funstoreStaticAuthenticationData(
authenticationKey: X509Certificate,
staticAuthData: ByteArray
): Unit
Deprecated: Use storeStaticAuthenticationData(java.security.cert.X509Certificate,java.time.Instant,byte[])
instead.
Store authentication data associated with a dynamic authentication key. This should only be called for an authenticated key returned by getAuthKeysNeedingCertification()
.
Parameters | |
---|---|
authenticationKey |
X509Certificate: The dynamic authentication key for which certification and associated static authentication data is being provided. This value cannot be null . |
staticAuthData |
ByteArray: Static authentication data provided by the issuer that validates the authenticity and integrity of the credential data fields. This value cannot be null . |
Exceptions | |
---|---|
android.security.identity.UnknownAuthenticationKeyException |
If the given authentication key is not recognized. |
storeStaticAuthenticationData
open fun storeStaticAuthenticationData(
authenticationKey: X509Certificate,
expirationDate: Instant,
staticAuthData: ByteArray
): Unit
Store authentication data associated with a dynamic authentication key. This should only be called for an authenticated key returned by getAuthKeysNeedingCertification()
.
Parameters | |
---|---|
authenticationKey |
X509Certificate: The dynamic authentication key for which certification and associated static authentication data is being provided. This value cannot be null . |
expirationDate |
Instant: The expiration date of the static authentication data. This value cannot be null . |
staticAuthData |
ByteArray: Static authentication data provided by the issuer that validates the authenticity and integrity of the credential data fields. This value cannot be null . |
Exceptions | |
---|---|
android.security.identity.UnknownAuthenticationKeyException |
If the given authentication key is not recognized. |
update
open fun update(personalizationData: PersonalizationData): ByteArray
Updates the credential with new access control profiles and data items.
This method is similar to WritableIdentityCredential#personalize(PersonalizationData)
except that it operates on an existing credential, see the documentation for that method for the format of the returned data.
If this call succeeds an side-effect is that all dynamic authentication keys for the credential are deleted. The application will need to use getAuthKeysNeedingCertification()
to generate replacement keys and return them for issuer certification.
This is only implemented in feature version 202101 or later. If not implemented, the call fails with UnsupportedOperationException
. See android.content.pm.PackageManager#FEATURE_IDENTITY_CREDENTIAL_HARDWARE
for known feature versions.
Parameters | |
---|---|
personalizationData |
PersonalizationData: The data to update, including access control profiles and data elements and their values, grouped into namespaces. This value cannot be null . |
Return | |
---|---|
ByteArray |
A COSE_Sign1 data structure, see above. This value cannot be null . |