Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Installation and deployment of the SDK

1. Introduction

This document includes a description of the components provided in the product FacePhi SelphID SDK.

This product incorporates several libraries whose API allows authentication and biometric identification solutions to include functionalities that use images and/or facial templates, passive liveness detection, data validation, and extraction of information from identity documents.

The components provided and the steps required to install the SDK on the operating systems are detailed below Windows and Linux.

2. Contents of SelphID SDK

The Software Development Kit, FacePhi SelphID SDK, contains a set of libraries available for the Java, .NET and C++ programming languages that allow developers to integrate the main functionalities offered by this product:

  • Reading and validation of information from digital identity documents (OCR).

  • Authentication (1:1) and Identification (1:N) of users using Facial Recognition, using images or templates.

  • Passive liveness detection of the user using images (without requiring user collaboration).

The content of SelphID SDK is as follows:

  • Libraries in the C++, Java and .Net programming languages (.Net only in the Windows version).

  • Java API documentation and .Net API documentation, both in HTML format, with information about all the methods supported in each of the classes.

  • Configuration file for the product license and usage and log files.

  • Web services programming example in .Net/Java.

  • C++ header files.

Different products are provided for the Windows and Linux operating systems.

  • Products available for Windows.

  • fphi-selphid-sdk-win64_x.x.x.x (Windows 64-bit).

  • Products available for Linux.

  • fphi-selphid-sdk-linux64_x.x.x.x (Ubuntu-based Linux distributions).

x.x.x.x may vary, and corresponds to the product version provided by FacePhi.

3. SDK Installation

This chapter describes the steps to install SelphID SDK.

3.1 Installation of the Software Development Kit

SelphID SDK is installed by unpacking the provided content into a directory on your system. The recommended directories are the following:

  • Recommended installation directories on Windows: C:\Program Files\FacePhi\Sdk\SelphId\x.x.x.x

    • To unpack the Windows SDK, it is only necessary to unzip it into the indicated path.

  • Recommended installation directories on Linux: /opt/facephi/sdk/selphid/x.x.x.x

    • To unpack the Linux SDK, it is essential to do so on the same Linux server where the symbolic links are created. To do this, use the following command:

where "x.x.x.x" is the product version supplied by FacePhi.

After installation, the following folders should appear in the selected directory:

  • Api: Contains the programming API description.

  • Bin: Contains the binary files.

    • Windows: Runtime libraries and applications.

    • Linux: Applications.

  • Config: Contains the configuration files.

  • Data: Contains the data files needed for correct runtime operation.

  • Doc: Contains the EULA documentation and the SDK version file.

  • Examples: Contains programming examples.

  • Lib: Contains the files and libraries needed for the build processes.

3.2 SDK Configuration

To make the libraries included in the SDK available on the system, it is necessary to perform the actions described below:

  • Create the FACEPHI_SELPHID_INSTALL_PATH environment variable

    The value of this environment variable must contain the selected installation directory in the previous point 3.1.

  • Add the library directory to the PATH environment variable

    Once the previous environment variable has been created, include the SDK's "bin" directory (for Windows) or "lib/lib" (for Linux) in the environment variable PATH (Windows) or LD_LIBRARY_PATH (Linux) of the system:

3.3 Environment variables

Different environment variables can be set to configure the SDK's operation:

  • FACEPHI_SELPHID_FACIAL_LICPATH_KEY (required). Path to the file license.lic. For example /opt/facephi/sdk/selphid/x.x.x.x/config/license.lic.

  • FACEPHI_SELPHID_DEBUGPATH_KEY (required). Path to the file where the log will be written. For example /opt/facephi/sdk/selphid/x.x.x.x/config/selphidDebug.log.

  • FACEPHI_SELPHID_USAGEPATH_KEY (required). Path where the usage data file will be stored. For example /opt/facephi/sdk/selphid/x.x.x.x/config/selphidUsage.db.

  • FACEPHI_SELPHID_FACIALLIVENESS_PATH_KEY (required). Path to the folder /data on your local file system. For example /opt/facephi/sdk/selphid/x.x.x.x/data.

  • FACEPHI_SELPHID_FACIALAUTHENTICATION_THRESHOLD (optional). Similarity value 0-100 to determine whether an authentication is positive or negative. Default 65.

  • FACEPHI_SELPHID_FACIALLIVENESS_THRESHOLD (optional). Threshold 0-100 to determine whether a liveness operation is positive (Live) or negative (NoLive). Default 50.

  • FACEPHI_SELPHID_FACIALEXTRACTOR_NUM_THREADS (optional) 1-8 Number of threads (cores) assigned to extraction and authentication operations. Default 4.

  • FACEPHI_SELPHID_FACIALLIVENESS_NUM_THREADS (optional) 1-8 Number of threads (cores) assigned to liveness operations. Default 4.

  • FACEPHI_SELPHID_FACIALLIVENESS_IAD (optional) (enable or disable) Enables the filters for Inyection Attack Detection for liveness operations. Default enable.

  • FACEPHI_SELPHID_FACIALLIVENESS_DEPTH (optional) (partial or full) Specifies the depth of the liveness checks: partial (FPAD Presentation Attack Detection), full (FPAD + FMAD Manipulation Attack Detection). Default partial.

  • FACEPHI_SELPHID_GALLERY_REMOVE_METHOD (optional) (erase or noerase) Specifies whether the gallery items will be completely removed through SelphIDIdentifier::RemoveWithGalleryIndex() or marked as invalid without being removed. Default erase.

  • FACEPHI_SELPHID_FUTURE_TIME_ALLOWED (optional) 0-N Specifies the time in seconds during which a token with a future date will be valid. This is a global value that can be overridden per operation using SelphIDVerifierOptions::SetFutureTimeAllowed(). Default 0, which means that all tokens with a future date will be rejected.

4. SDK Licensing

To license the SelphID SDK product, it is necessary to perform the actions described below:

4.1 Machine identifier generation

Machine identifiers can be obtained using a terminal and running the following command in the directory where the utility is located: FACEPHI_SELPHID_INSTALL_PATH\bin (both on Windows and Linux)

Starting from version 6.20.0, selphid-license-activator it runs as a standalone application, without needing to configure environment variables and without depending on SelphID-SDK.

SN is the serial number of the license to be activated and is provided by your licensing provider.

The format of the serial number "SN" is XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX.

Example with the above serial number:

Starting from version 6.15.0, licensing based on the MAC addresses of the network interfaces is enabled. In these cases, the MAC addresses of the interfaces involved in the licensing must be declared using the parameter -addr.

Once the machine identifiers have been obtained, the hostid.txt file must be sent to your licensing provider so that your license can be generated (file with .lic extension).

Starting from version 6.2.0, there is the possibility of online activation of the license. In this case, the licensing provider will provide you with a .lic file without needing to generate machine identifiers (it is not necessary to run selphid-license-activator).

4.2 License installation

The steps necessary for license installation are described below:

  • Copy the license to the config directory

    To install the license, simply copy the file license.lic that you will receive from your distributor into the directory config located in the SDK installation path: FACEPHI_SELPHID_INSTALL_PATH\config

  • Configure the license in the selphid.cfg file

    Once the license file has been copied, set the value of the variable contained in the selphid.cfg file to the value of the path where the license is located:

The directory config is the default directory for installing the license, although it is possible to install the license in another directory on the server. Simply, you will need to reflect that directory in the configuration file.

It is essential to verify that the values of the following variables are correctly configured with paths that exist in the operating system:

  • FACEPHI_SELPHID_FACIAL_LICPATH_KEY: Path to the file license.lic.

  • FACEPHI_SELPHID_FACIALLIVENESS_PATH_KEY: Path to the folder /data of the SelphID installation. Required for passive liveness detection.

  • FACEPHI_SELPHID_USAGEPATH_KEY: Path to the file where usage statistics are stored.

  • FACEPHI_SELPHID_DEBUGPATH_KEY: Path to the file where debugging information is stored. If omitted, debugging information will not be generated.

Likewise, it is necessary to check the license expiration date (it is found within the license file, in the "dateEnd" field) to ensure that the license is valid and has not expired.

4.3 Installation of the license service

The SelphID SDK license server is a terminal application that runs on Windows or Linux.

This application allows serving SelphID licenses to client nodes without static hostID. However, this server must run on a machine that has both hostID and a service port TCP/UDP static.

Requirements:

  • Hardware:

    • Static hostID

    • Static port

  • Software:

    • SelphID SDK

  • Running the license service in a Linux terminal

    Steps to run the license service in a user terminal in Linux:

    1. Unpack SelphID SDK. Example:

    2. Copy the server license to the server directory with permissions rw. Example:

    3. Export the SelphID SDK library path to LD_LIBRARY_PATH. Example:

    4. Run the license service application indicating the port (-port), the path to the server license file (-lic) and, optionally, the path to the license service log (-log).

      The license server must be started in administrator mode.

    • Example writing the log to disk and to the console:

      The parameter -log will refer to a directory and not to a file. This is due to the log rotation implementation.

    • Example with log in the console:

    1. The license server may have been configured for online or offline activation. The licensing mode will be embedded in the file .lic. In the case of offline activation, the server will provide an activation key the first time it starts.

    • This activation key must be sent to your licensing provider so that your license .lic can be updated.

    • The license update will include the activation code for the server, which can then be started without needing an Internet connection.

    In the case of the online activation, the server will start the first time without the file .lic requiring updates.

  • Running the license service as a Linux system service

    Steps to run the license service as a system service in Linux:

    1. Follow steps 1 and 2 of the previous instructions.

    2. Run the application as a system startup application by editing the crontab: $crontab -e:

  • Environment variable configuration

  • Run the SelphID license server on system restart

    1. Restart the system. Example: $sudo shutdown -r now

    2. Check in the log file that the licenses are being served correctly. Example:

PreviousInstallationNextInstallation and deployment of the service

Last updated