Most visited

Recently visited

Results for

Summary: Methods | Inherited Methods

IdentityCredential

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.

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.
`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 `IdentityCredential`.
`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 `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`	`storeStaticAuthenticationData(X509Certificate authenticationKey, byte[] staticAuthData)` Store authentication data associated with a dynamic authentication key.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeout, int nanos)` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.
`final void`	`wait(long timeout)` Causes the current thread to wait until either another thread invokes the `notify()` method or the `notifyAll()` method for this object, or a specified amount of time has elapsed.
`final void`	`wait()` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object.

Public methods

createEphemeralKeyPair

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

decryptMessageFromReader

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.

encryptMessageToReader

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

Encrypt a message for transmission to the reader.

Parameters
`messagePlaintext`	`byte`: unencrypted message to encrypt. This value cannot be `null`.

Returns
`byte[]`	encrypted message. This value cannot be `null`.

getAuthKeysNeedingCertification

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

getAuthenticationDataUsageCount

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

getCredentialKeyCertificateChain

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

getEntries

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:

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

setAllowUsingExhaustedKeys

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.

setAvailableAuthenticationKeys

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.

setReaderEphemeralPublicKey

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.

storeStaticAuthenticationData

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.

Classes

Exceptions

Most visited

Recently visited

Results for

IdentityCredential

Summary

Public methods

Inherited methods

Public methods

createEphemeralKeyPair

decryptMessageFromReader

encryptMessageToReader

getAuthKeysNeedingCertification

getAuthenticationDataUsageCount

getCredentialKeyCertificateChain

getEntries

setAllowUsingExhaustedKeys

setAvailableAuthenticationKeys

setReaderEphemeralPublicKey

storeStaticAuthenticationData