The Keyless SDK can operate in two modes: custom token mode, and legacy mode. In custom token mode, the Keyless SDK safely stores an opaque string (custom token) provided by your application. This is the recommended mode of operation. With legacy mode, the Keyless API generates and manages the authentication secret internally, disclosing only signed authentication tokens upon request.
The mode of operation can be set up before enrollment. Changing mode requires de-enrolling the user.
The Keyless SDK can also be used to safely store an opaque custom token during enrollment, and to later retrieve it as a result of a successful authentication. To set the Keyless SDK in custom token mode, enrollment must be performed using
enrollCustomToken. The custom token can be retrieved using method
getCustomAuthenticationToken. This method triggers biometric authentication.
Depending on your application logic, you can choose to use different custom token. This could be a secret that you have provided to the app from the backend, the the seed of an OTP protocol, or anything else. If you only need to know the result of the authentication (success/failed), you can pass any constant value as the custom token.
In legacy mode, the Keyless SDK generates and handles the authentication secret internally. The API generates a unique authentication token after each successful biometric authentication. The token is cryptographically bound to the user via the Keyless ID, and to a string specified by the caller during authentication.
The authentication tokens are existentially unforgeable: given the authentication token associated to a string, it is infeasible to compute the authentication token associated with a different string for which no token was previously generated. As a result, disclosing a single authentication token does not lead to a long-term compromise of the authentication system.
In legacy mode, the main entry points for the Keyless SDK are: - The enrollment method
enroll, which captures the user’s face and establishes a unique user identifier (Keyless ID). - The token retrieval (authentication) method
getAuthenticationToken, which captures the user’s face, matches it against the user’s biometric template using the Keyless network, and returns the authentication token.