Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Getting started with functional eID
Now that you are familiar with generating foundational eID SensePrints, it is time to learn how to allow verification of foundational eID holders using their face without having their face.
To generate a Face Certificate, you must have:
SensePrint - You cannot generate a certificate for a particular pupose without having the foundational eID - i.e. the SensePrint
User's Face - Any key generation operation using a SensePrint is impossible without the user's face.
Purpose ID - A Face Certificate contains a public key derived from a user's face as pertaining to a specific purpose. As an example, the purpose ID could simply be a unique identifier associated to a particular verifier - i.e. the verifier's ID / web site etc.
eID attributes subset (optional) - A Face Certificate can also contain a subset of attributes from the foundational eID as requested by a particular verifier. When included, these are typically encrypted using a specified public key so that only an authorized verifier can read them. The attributes are included as a JSON string. If the SensePrint doesn't contain any of the requested attributes, they are ignored.
Public Key (optional) - When included, the requested attributes JSON string is encrypted using this key.
The server must be configured with a private key as detailed in the Configuration section.
While most programming languages will provide libraries to generate key pairs, to get you started, you can use the the OpenSSL command line tool. To install OpenSSL:
Windows - FireDaemon provides binary installers for your convenience.
Linux - You can install OpenSSL on linux by using the following commands:
sudo apt update
sudo apt install openssl
Within OpenSSL installed, from the command line, you can first generate a keypair:
The keypair is now stored in a file called secp256k1-key.pem.
To print the Base64 encoded public key that the API will accept:
Later, during certificate verification, you will also need the private key. You can get this from the same file using:
As before, on the Swagger Docs page authorize using the API Key you setup earlier.
Expand the /generate-face-certificate section and then click the Try it out button as shown below:
As before, after clicking the Try it out button, the following JSON text will become editable:
attribute_encryption_secp256k1_public_key_base64 specifies a base64 encoded public key on the Secp256k1 curve. When this key is specified, the server will encrypt the requested_attributes JSON string with this key.
check_live_face_before_creation will check if the face in face_base_64 is live (no spoofing detected) before creating a Face Certificate.
expiration_date_utc is a UTC time stamp of when the Face Ceritificate will expire.
face_base_64 is an image of the eID holder's face represented as a Base64 string. Most programming libraries will provide a way to convert a file to Base64, but for a quick demonstration, you can use this page to convert an image to a Base64 string.
liveness_tolerance is only used when check_live_face_before_creation is set to true and determines the strictness of the liveness algorithm.
os is also used only when check_live_face_before_creation is set to true and finetunes the liveness check. It indicates the operating system the image was captured on. Valid values are ANDROID / IOS / DESKTOP.
password should be specified when the senseprint_base_64 was generated with a password.
purpose_id specifies the purpose of the Face Certificate. It can also be simply a verifiers ID (UUID).
senseprint_base_64 is a base 64 encoded raw SensePrint from which a public key will be generated fo the specified purpose.
requested_attributes when specified, will include the attributes in the Face Certificate. Only matched attribute names will be included. When a attribute_encryption_secp256k1_public_key_base64 is specified, the attributes JSON string will be encypted with the specified public key. If a key is not specified, then the attributes will be included as plain-text JSON.
user_subject_name is the subject name of the use for whom the cerificate is being generated. If the certificate will be stored in a public registry, it is recommended that the subject name is pseudonymized or hashed.
verifiers_auth_key should be specified when a SensePrint was generated with it specified during generation as well.
If all goes well, you should see a response like the following:
This is the JSON representation of you certificate (with line breaks represented as \n. You could use a language of your choice to save the string to a file. In this example, we use Python:
Now you will have a file called example.pem which contains your certificate.
You can run an OpenSSL command to view the contents of your certificate:
Depending on whether you supplied a verifiers_auth_key or not, the certificate will contain either an X.509v3 extension of 1.2.702.0.1012.1.1.0.0 (for plain text attributes) or 1.2.702.0.1012.1.1.1.0 (for encrypted attributes).
Below we show a certificate where the verifiers_auth_key was not specified and eID attributes are unencrypted - correspondingly the 1.2.702.0.1012.1.1.0.0 extension is included in the certificate:
The meaning of 1.2.702.0.1012.1.1.0.0 (for plain text attributes) or 1.2.702.0.1012.1.1.1.0 (for encrypted attributes) can be seen at the following URLs:
1.2.702.0.1012.1.1.0.0 (unencrypted)- http://www.oid-info.com/cgi-bin/display?oid=1.2.702.0.1012.1.1.0.0
1.2.702.0.1012.1.1.1.0 (encrypted) - http://www.oid-info.com/cgi-bin/display?oid=1.2.702.0.1012.1.1.1.0
These are globally registered object IDs that are expanded below.
{iso(1) member-body(2) sg(702) snraoid(0) seventh-sense(1012) sensecrypt(1) user-attributes(1) plain-text(0) json(0)}
{iso(1) member-body(2) sg(702) snraoid(0) seventh-sense(1012) sensecrypt(1) user-attributes(1) encrypted(1) json(0)}
Depending on whether eID attributes were requested, and whether an encryption key was specified, your certificate will contain either no extension, or one of 1.2.702.0.1012.1.1.0.0 (unencrypted), or 1.2.702.0.1012.1.1.1.0 (encrypted).
Functional eID features
As discussed earlier SenseCrypt Face PKI extends SenseCrypt eID by enabling a third party, without having / processing a person’s face / biometric data to
encrypt information for that person's eyes only
verify that the person signed specific information
verify a subset of eID attributes are real as issued by a trusted issuer
The central piece of technology in SenseCrypt Face-PKI is the Face Certificate. A Face Certificate is generated from:
the user’s face
a purpose ID
metadata
In the following sections, we shall see how to use the end-points to accomplish various different objectives within SenseCrypt Face PKI functionality.
How to use Face Certificates to encrypt keys
As a Face Certificate contains a public key, it can be used to encrypt data. To decrypt the encrypted data, a user would, then, need the right private key.
This private key can only be generated from the user's face, SensePrint, and the purpose ID specified to generate the Face Certificate.
Hence, encrypted data can only be decrypted via a live Face Scan of the intended recipient.
The type of key contained in a Face Certificate is an Elliptic Curve Cryptography (ECC) key based on the Secp256k1 (Bitcoin) curve.
It is possible to directly use the public key in the Face Certificate to encrypt any arbitrary size of data using an implementation of Elliptic Curve Integrated Encryption Scheme (ECIES) in a programming language of your choice.
However, to make life simpler, we offer an end-point to encrypt data using a Face Certificate.
As a web end-point, we restrict the size of data to be encrypted. However, we suggest that instead of encrypting a large amount of data directly, the end-point can be used to encrypt a symmetric key or the private key from an assymetric key pair.
Then the encrypted key can be stored side by side with encrypted data. To decrypt the data, the steps needed would be:
Decrypt the encrypted key using a SensePrint, Face, and Purpose ID
Decrypt the encrypted data using the decrypted key in step 1
As before, on the Swagger Docs page authorize using the API Key you setup earlier.
Expand the /encrypt-with-face-certificate section and then click the Try it out button as shown below:
Upon clicking Try it out you should be able to submit the data as shown below:
Please note that when you generate a Face Certificate, it is returned with line breaks. When you submit it through the Swagger Docs page, those line breaks need to be replaced with escaped \n characters to be a proper JSON representation.
However, if you submit the Face Certificate programaitically, you would not need to manually replace the line breaks with \n.
How to determine the authenticity of a certificate
A Face Certificate is a standard x509v3 certificate and as such, its validity can be determined using conventional cryptographic tools such as OpenSSL:
In the above command, root.pem can be obtained by calling the /root-certificate end-point on the server.
As a standard cryptography construct, an x509 certificate can be verified using various libraries in many different languages:
Python - the cryptography package support x509 verification. See here.
NodeJS - pki.js provides functionality that should help in x509 verification.
C# - Useful functions can be found in the System.Security.Cryptography.X509Certificates namespace in .NET 8.
Java - This blog article covers a lot of gorund.
While the above list is by no means exhaustive, it should give you an idea of how you can verify certificates on your own server.
However, for the sake of convenience, we also provide an end-point for you to call to check the validity of a Face Certificate.
As before, on the Swagger Docs page authorize using the API Key you setup earlier.
Expand the /verify-face-certificate section and then click the Try it out button as shown below:
As before, after clicking the Try it out button, the following JSON text will become editable:
cert_pem - specifies the certificate to be verified (in PEM format)
secp256k1_private_key_base64 - when included, this key will be used to decrypt the eID attributes in a Face Certificate.
If the certificate includes encrypted attributes and this key is not specified, they will be returned as base64 encoded bytes which can later be decrypted offline using the ECIES algorithm (using your private key).
If the attributes were included without specifying a public key for their encryption, this parameter can be omitted and the attributes will be returned as a plain-text JSON string.
The process of generating keypairs for use with the API is described here.
How to enable Face PKI features
This section serves as a reminder that for SenseCrypt Face PKI features to work, you must configure the issuers_private_key in your secrets.json file while running the server (please see the section).
If you do not set this, most SenseCrypt Face PKI end-points will return the following error with a 403 status code:
Assuming you have setup your private key, in the next section we will understand how a third-party can access your Root CA Certificate for Face Certificate verification.
If you want to independently generate a key-pair (without using the installation script), it is described .
How to decrypt keys using a face
In the previous section, we saw how to encrypt a key using a Face Certificate.
The key is encrypted using ECIES using the public key in the Face Certificate.
To decrypt the encrypted key, the right private key must be generated from your SensePrint, face, and purpose ID.
As before, on the Swagger Docs page authorize using the API Key you setup earlier.
Expand the /face-decrypt section and then click the Try it out button as shown below:
Upon clicking Try it out you should be able to submit the data as shown below:
The following summarizes the parameters for the request:
encrypted_key_base_64 - this is the encrypted key that was obtained using the /encrypt-with-face-certificate end-point described in the previous section.
face_base_64 - the face of the SensePrint eID holder.
liveness_tolerance (optional) - the tolerance of the liveness algorithm used to check for a live face before allowing the decryption to proceed.
os (optional) - indicates the operating system the image was captured on. Valid values are ANDROID / IOS / DESKTOP.
password (optional) - the same password (if one was specified) that was used during the SensePrint generation.
purpose_id - a unique purpose ID. This should match the purpose ID that was used to generate the Face Certificate used to encrypt the key.
senseprint_base_64 - the foundational SensePrint eID in raw form.
verifiers_auth_key (optional) - the same verifiers_auth_key (if one was specified) that was used during the SensePrint generation.
How to verify a Face Signature using a Face Certificate
In the previous section we have seen how to sign a piece of data using a SensePrint, a face, and a purpose ID.
The signature is a standard Elliptic Curve Digital Signature Algorithm (ECDSA) and it is recommended that the signature be independently verified without calling the server API. As an example, the following steps describe how to verify the signature using OpenSSL:
Ensure the raw data for which the signature is being generated is saved to a file
data.txtEnsure that the signature generated through is saved in a file called
signature.b64Convert the signature to raw bytes from base64:
openssl base64 -d -in signature.b64 -out signature.derExtract the public key from the (you can save the Face Certificate to a file called
face-cert.pemafter generating it)openssl x509 -in face-cert.pem -pubkey -noout > face-cert-pub-key.pemVerify the signature using the public key:
openssl dgst -sha256 -verify face-cert-pub-key.pem -signature signature.der data.txt
We have used OpenSSL as an example, but it should be possible to use a cryptographic library in a language of your choice to accomplish the same functionality.
However, for ease of development (in pre-production mode), we also provide an end-point to verify a face signature. Even though we provide an end-point, it is highly recommended that developers put in the effort to verify signatures on their own servers. This will not only decrease latency, but also preserve privacy.
As before, on the Swagger Docs page authorize using the API Key you setup earlier.
Expand the /verify-face-signature section and then click the Try it out button as shown below:
Upon clicking Try it out you should be able to submit the data as shown below:
The following summarizes the parameters for the request:
data_sha256_base_64 - given a piece of data (bytes), it should then be SHA256 hashed to obtain 256 bits. The hash should then be Base64 encoded to send it to the API.
ecdsa_der_signature_base_64 - this is the signature obtained from the SensePrint, face and purpose ID using the /face-sign end-point discussed in the previous section.
face_certificate_pem - this is the Face Certificate generated for the same purpose ID. When obtaining the certificate, the API returns the string with line breaks. However, line breaks are not valid JSON so when using the Swagger Docs page, be sure to replace line breaks in the certificate string with \n. When programatically calling the API this would not be required.
Your server's Root Certificate contains the public key for you as an eID Issuer and CA
Your Root Certificate forms the root of trust for anyone verifying Face Certificates issued by you.
It contains the corresponding public key for the private key (issuers_private_key) that you configured in secrets.json before starting the server.
To access your Root Certificate, simply navigate to:
How an eID holder can use their SensePrint to sign a piece of data
Just as a private key can be used in cryptographic systems to sign a piece of data (usually its SHA256 hash), in Face PKI, a face, SensePrint, and a purpose ID can be used to sign some data.
The steps in this process are the following:
Generate a SHA256 hash of the data to be signed.
Base64 encode the SHA256 hash.
Send the Base64 encoded string to the server along with a SensePrint and a purpose ID.
The algorithm used for the signature is the Elliptic Curve Digital Signature Algorithm (ECDSA). Thus, the generated signtature can also be independently verified using a Face Certificate containing the public key for the same purpose ID.
As before, on the Swagger Docs page authorize using the API Key you setup earlier.
Expand the /face-sign section and then click the Try it out button as shown below:
Upon clicking Try it out you should be able to submit the data as shown below:
The following summarizes the parameters for the request:
data_sha256_base_64 - given a piece of data (bytes), it should then be SHA256 hashed to obtain 256 bits. The hash should then be Base64 encoded to send it to the API
face_base_64 - the face of the SensePrint eID holder
liveness_tolerance (optional) - the tolerance of the liveness algorithm used to check for a live face before allowing the signing to proceed.
os (optional) - indicates the operating system the image was captured on. Valid values are ANDROID / IOS / DESKTOP.
password (optional) - the same password (if one was specified) that was used during the SensePrint generation.
purpose_id - a unique purpose ID. This should match the purpose ID that was used to generate the Face Certificate that will be used to verify the signature.
senseprint_base_64 - the foundational SensePrint eID in raw form.
verifiers_auth_key (optional) - the same verifiers_auth_key (if one was specified) that was used during the SensePrint generation.
