# Print output for @column tags ?>
public
abstract
class
IdentityCredential
extends Object
java.lang.Object | |
↳ | android.security.identity.IdentityCredential |
Class used to read data from a previously provisioned credential.
Use IdentityCredentialStore#getCredentialByName(String, int)
to get a
IdentityCredential
instance.
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. |
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
ResultData
|
getEntries(byte[] requestMessage, Map<String, Collection<String>> entriesToRequest, byte[] sessionTranscript, byte[] readerSignature)
Retrieve data entries and associated data from this |
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. |
abstract
void
|
setAvailableAuthenticationKeys(int keyCount, int maxUsesPerKey)
Sets the number of dynamic authentication keys the |
abstract
void
|
setReaderEphemeralPublicKey(PublicKey readerEphemeralPublicKey)
Set the ephemeral public key provided by the reader. |
abstract
void
|
storeStaticAuthenticationData(X509Certificate authenticationKey, byte[] staticAuthData)
Store authentication data associated with a dynamic authentication key. |
Inherited methods | |
---|---|
public abstract KeyPair createEphemeralKeyPair ()
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".
Returns | |
---|---|
KeyPair |
ephemeral key pair to use to establish a secure channel with a reader.
This value cannot be null . |
public abstract byte[] decryptMessageFromReader (byte[] messageCiphertext)
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 |
byte : encrypted message to decrypt.
This value cannot be null . |
Returns | |
---|---|
byte[] |
decrypted message.
This value cannot be null . |
Throws | |
---|---|
MessageDecryptionException |
if the ciphertext couldn't be decrypted. |
public abstract byte[] encryptMessageToReader (byte[] messagePlaintext)
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 |
byte : unencrypted message to encrypt.
This value cannot be null . |
Returns | |
---|---|
byte[] |
encrypted message.
This value cannot be null . |
public abstract Collection<X509Certificate> getAuthKeysNeedingCertification ()
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, 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.
Returns | |
---|---|
Collection<X509Certificate> |
A collection of X.509 certificates for dynamic authentication keys that need issuer
certification.
This value cannot be null . |
public abstract int[] getAuthenticationDataUsageCount ()
Get the number of times the dynamic authentication keys have been used.
Returns | |
---|---|
int[] |
int array of dynamic authentication key usage counts.
This value cannot be null . |
public abstract Collection<X509Certificate> getCredentialKeyCertificateChain ()
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.
Returns | |
---|---|
Collection<X509Certificate> |
the certificate chain for this credential's CredentialKey.
This value cannot be null . |
public abstract ResultData getEntries (byte[] requestMessage, Map<String, Collection<String>> entriesToRequest, byte[] sessionTranscript, byte[] readerSignature)
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 the responsibility of the calling application to know if authentication is needed
and use e.g. BiometricPrompt
to make the user
authenticate using a BiometricPrompt.CryptoObject
which
references this object. If needed, this must be done before calling
getEntries(byte[], java.util.Map, byte[], byte[])
.
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.
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, byt
there are three requirements that must be met to work with this API:
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 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 readerAuth
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 |
byte : If not null , must contain CBOR data conforming to
the schema mentioned above.
This value may be null . |
entriesToRequest |
Map : 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 . |
sessionTranscript |
byte : This value may be null . |
readerSignature |
byte : A COSE_Sign1 structure as described above or
null if reader authentication is not being used.
This value may be null . |
Returns | |
---|---|
ResultData |
A ResultData object containing entry data organized by namespace and a
cryptographically authenticated representation of the same data. |
Throws | |
---|---|
SessionTranscriptMismatchException |
Thrown when trying use multiple different session transcripts. |
NoAuthenticationKeyAvailableException |
if authentication keys were never
provisioned, the method
setAvailableAuthenticationKeys(int, int)
was called with keyCount set to 0,
the method
setAllowUsingExhaustedKeys(boolean)
was called with false and all
available authentication keys have been
exhausted. |
InvalidReaderSignatureException |
if the reader signature is invalid, or it doesn't contain a certificate chain, or if the signature failed to validate. |
InvalidRequestMessageException |
if the requestMessage is malformed. |
EphemeralPublicKeyNotFoundException |
if the ephemeral public key was not found in the session transcript. |
public 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. 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. |
public 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.
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.
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. |
public abstract void setReaderEphemeralPublicKey (PublicKey readerEphemeralPublicKey)
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 . |
Throws | |
---|---|
InvalidKeyException |
if the given key is invalid. |
public abstract void storeStaticAuthenticationData (X509Certificate authenticationKey, byte[] staticAuthData)
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 |
byte : Static authentication data provided by the issuer that validates
the authenticity
and integrity of the credential data fields.
This value cannot be null . |
Throws | |
---|---|
UnknownAuthenticationKeyException |
If the given authentication key is not recognized. |