Usage

Public-Private Key Implementation

The signing kit uses a P256 public-private key pair, separate for each type (presence and silent) when both are present. Supported devices:

• Android devices starting with API 23.

• iOS versions starting with iOS 13.

The public part of the key is sent to VIDAAPI upon registration. The key pair is stored in the Android key store and iOS secure enclave. The public key is stored with a self-signed certificate with a 30-year validity.

For Android, VidaBase provides a function IsHardwareBacked to check whether the key material resides in secure hardware. It uses security level information provided by the KeyInfo class.

Initialization with Bearer Token

1. Prior to registering or wiping a credentialId, a bearer token must be set using setToken(token: string).

2. The bearer token can be acquired from the following endpoint:

curl --location --request POST 'https://{environment-url}/realms/{partner-id}/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=oidc' \
--data-urlencode 'client_secret=9aucyKs054mlmp3DVQ4MSEVrRsBVip8t'
\
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=roles'

VIDA supports sandbox and production environment, and the Identity Verificationenvironment-url can be found under Environment section

Response

• Use access_token value as bearer token for any Push signing API endpoint

• Use expires_in value to detect the lifespan of the token in seconds if needed

• Use refresh_token to refresh the token once expiry time is reached

1. The token expires every 5 minutes. If an expired token is used to register/wipe a credentialId, error code 20018 will be returned or the HTTP request will end with a 401 status code.

2. Signatures can be generated without setting the token or with an expired token.

Registration

1. To start the registration of a new device, first acquire an unbound credentialId from VIDAA using VIDA Credential Services API. It is recommended to do this step from a webserver rather than a React Native app and pass the acquired credential_id to the mobile app via a push notification.

To acquire a new credential ID, use POST to https://{environment-url}/api/v1/device/register.

Use the presence property to register an unbound credentialId with specific signing options.

• SILENT_USER - User presence check is not required

• ENFORCE_USER_PRESENCE - Always check the user’s presence.

• SILENT_AND_ENFORCE_USER_PRESENCE - Signing can be carried out with and without the user presence.

Example

shellCopy codecurl --location --request POST 'https://{environment-url}/api/v1/device/register' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "presence": "SILENT_AND_ENFORCE_USER_PRESENCE"
}'

Response

• Use the unbound credential_id value to finish registration. Unbound credentialId will expire after 60 seconds.

1. To bind a new credentialId to a device, call registerDevice(credentialId: string, password: string).

• Successful registration will return void. If registration was successful you can start signing messages.

• Password is an optional property, But registration will fail if presence user registers without a password.

1. To check if registration was successful, you can call the following credential checking functions: hasSilentCredentials() or hasPresenceCredentials().

2. To wipe credentials for the current device, call wipeDevice(password: string). For silent registration or in case of forgot password, wipeForgotPassword() must be used.

Signing Messages

Signing Functions

To sign a message, you can use the following functions:

1. signMessage(message: string): Signs a message.

2. signMessageWithUserPresence(message: string, password: string): Signs a message with user presence verification using a password.

3. signMessageWithUserPresenceUsingBiometrics(messageHash: string, localizedBiometricReason?: string, title?: string, cancel?: string): Signs a message with user presence verification using biometrics. You can customize the biometric prompt with optional parameters localizedBiometricReason, title, and cancel.

Note: The only way to access the message signature is from the resolved Promise of these functions.

Signature Handling

1. The generated signature count is sent to VIDAAPI periodically.

2. It's up to the consumer app to fetch public keys from VIDAAPI and validate selected signatures if needed.

Enabling and Disabling Biometrics

To enable biometrics, call enableBiometrics(password: string, localizedBiometricReason?: string, title?: string, cancel?: string). Enabling biometrics will prompt for biometric authorization.

• To enable biometrics, presence signing must be registered first.

• To enable biometrics, a password must be provided.

• If presence is registered, but biometrics are not available on a device, enableBiometrics() will reject its Promise.

To disable biometrics, use disableBiometrics(password?: string).

• On iOS, biometric approval password is not required, and biometric approval will be required.

• On Android, a mandatory password check for presence users is performed when disabling biometrics.

Checking Biometric Availability

You can determine the availability of biometrics on the device with the function isBiometryAvailable() -> Bool.

Transactions

1. Registered keys can be used to register and complete a transaction with a given message hash.

2. Only registered users can use the transaction API. Registered presence must conform to the presence given in the transaction. For example, to register a transaction with ENFORCE_USER_PRESENCE presence type, the user has to be registered with ENFORCE_USER_PRESENCE or SILENT_AND_ENFORCE_USER_PRESENCE presence type.

3. To register a new transaction, call registerTransaction(presence: string, messageHash: string).

4. Only ENFORCE_USER_PRESENCE or SILENT_USER can be used as the presence string for transactions. Users registered with SILENT_AND_ENFORCE_USER_PRESENCE have to choose whether to enforce presence or not.

5. To finish a transaction, call finishTransaction(transactionId: String, password: string).