Biometric Session Configuration
This page aims to detail the integration of the Biometric Engine Session API into Veridium ID services.
Authentication
First thing for authentication with VFACE, is to check if in the command, there is the field in the configuration called requiredBiometricSession
.
![](../../__attachments/3554672983/image-20230821-082229.png?inst-v=ffa2d127-74f7-4a38-ac00-bc62b4eb8eb4)
If the requiredBiometricSession
is set on true, the server will try to create a new biomatch_session. If the field is set on false, the server behaviour will be unchanged.
When authentication event with VFACE is happening and the requiredBiometricSession
is set on true, the server will follow next steps:
check prerequisites (the authentication should have the VFACE engine, and min version of the engine should be 4.1.2)
generate a nonce, which is the session id and send to the bio match api. The reason for using nonce is that we can protect ourselves for a replay attack.
the server will call
bio_match_session_create
to generate a signed config, config which will be encoded in Base64.the client will try to get authentication template using that signed config received in the previous step
the server will match biometric vector
For this step, the client will send to the server if it’s necessary to match with the signed config, or to match adaptive. If the server will match with the signed config, first thing is to repeate the 1st step, and after that, the nonce will be checked if it’s a match with the nonce from the 2nd step.
Enrolment
In the enrolment process, there is a new setting in the vface.json called requiredBiometricSession
. If the setting is set on true, the server will encrypt the enrolment process on the VFACE, otherwise, the behaviour will be unchanged.
![](../../__attachments/3554672983/image-20230822-110345.png?inst-v=ffa2d127-74f7-4a38-ac00-bc62b4eb8eb4)
When enrolment event with VFACE is happening and the requiredBiometricSession
is set on true, the server will follow next steps:
client (SSP) will get the configuration from the server, including
requiredBiometricSession
setting. this setting will help client to choose the mode that the VFACE is initialisedclient (SSP) will generate a new UUID (as the session id) and send to the server to create the biometric session
check prerequisites (the authentication should have the VFACE engine, and min version of the engine should be 4.1.2)
the server will call
bio_match_session_create
to generate a signed config, config which will be encoded in Base64.the client will try to enroll using that signed configuration received in the previous step. the response will be an encrypted template
the client will send the encrypted template to the server.
the server will call
bio_match_session_enrol_decrypt
with the encrypted template and nonce. nonce is used to validate the request. the response will be a enrolment templatethe server will send the template to the client and the client will follow the normal process
Error Codes
Value | Code name |
---|---|
0 | NO_ERROR |
1 | VFACE_FATAL_ERROR |
2 | INSUFFICIENT_TEMPLATES |
3 | OPENCV_ERROR |
4 | UNINITIALISED |
5 | TEMPLATE_NULLPTR |
6 | AUTH_TEMPLATE_UNPACK_FAIL |
7 | ENROLL_AUTH_TYPE_MISMATCH |
8 | EITHER_TEMPLATE_MUST_BE_INTERACTIVE |
9 | AUTH_TEMPLATE_WRONG_ROLE |
10 | ENROLL_TEMPLATE_WRONG_ROLE |
50 | ENCRYPTED_AUTH_TEMPLATE_INSUFFICIENT_LENGTH |
51 | ENCRYPTED_AUTH_TEMPLATE_DECRYPTION_FAILURE |
52 | NULL_SESSION |
53 | ENCRYPTED_AUTH_TEMPLATE_PARSE_FAILURE |
54 | ENCRYPTED_AUTH_TEMPLATE_NONCE_MISMATCH |
55 | ENCRYPTED_AUTH_TEMPLATE_TOO_LONG |
56 | ENCRYPTED_AUTH_TEMPLATE_TAG_MISMATCH |
57 | INVALID_PUBLIC_KEY |
58 | INVALID_PRIVATE_KEY |
59 | SESSION_STATE_MISMATCH |
60 | ENCRYPTED_AUTH_TEMPLATE_NULL |
61 | NONCE_NULL |
62 | NONCE_ZERO_LENGTH |