Skip to content

SelphID SDK Installation Manual

1. Introduction

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

This product incorporates several libraries whose API enables to incorporate in its authentication and biometric identification solutions functionalities using images and/or facial templates, passive liveness diagnostic, data validation and extraction from identity documents.

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

2. SelphID SDK Content

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

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

  • Authentication (1:1) and Identification (1:N) of users by means of facial recognition, using images or templates.

  • Passive user liveness diagnostic using images (no user collaboration required).

The SelphID SDK contents are as follows:

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

  • Java Api and .Net Api documentation, both in html format, with information on all the methods supported in each of the classes.

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

  • Example of web services programming in .Net/Java.

  • C++ header files.

Different products are provided for Windows and Linux operating systems.

  • Products available for Windows.

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

  • Products available for Linux.

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

Note

x.x.x.x may vary, and it is the product version provided by FacePhi.

![](../../assets/images/arq_sdk.png)

3. SDK Installation

In this chapter the steps to install SelphID SDK are described.

3.1 Software Development Kit Installation

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

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

    • To decompress Windows SDK, you only need to decompress the zip in the indicated path.

  • Recommended Installation Directories on Linux: /opt/facephi/sdk/selphid/x.x.x.x

    • To decompress the Linux SDK, it is essential to do it on the same Linux server where symbolic links are created. For this purpose, use next command:

      $ tar -xvzf fphi-selphid-sdk-linux64-x.x.x.x.tar.gz

Note

Being "x.x.x.x" the version of the product supplied by FacePhi.


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

  • Api: Contains programming API description.

  • Bin: Contains binary files.

    • Windows: Execution libraries and applications.

    • Linux: Applications.

  • Config: Contains configuration files.

  • Data: Contains data files for the valid runtime.

  • Doc: Contains eula documentation and the sdk version file.

  • Examples: Contains programming examples.

  • Lib: Contains files and libraries needed for compilation processes.

3.2 SDK Configuration

In order to make the SDK-included libraries available in the system, it is necessary to perform the actions described below:

  • Create environment variable FACEPHI_SELPHID_INSTALL_PATH

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

    # Windows
set FACEPHI_SELPHID_INSTALL_PATH=C:\Program Files\FacePhi\Sdk\SelphId\x.x.x.x

    # Linux
export FACEPHI_SELPHID_INSTALL_PATH=/opt/facephi/sdk/selphid/x.x.x.x

  • Create environment variable LD_LIBRARY_PATH

    The value of this environment variable must contain the directory where the SDK libraries are located, using the installation directory selected by the previous variable.

    # Windows
set LD_LIBRARY_PATH=%FACEPHI_SELPHID_INSTALL_PATH%\bin

    # Linux
export LD_LIBRARY_PATH=$FACEPHI_SELPHID_INSTALL_PATH/lib/lib/

  • Add the library directory to the PATH environment variable

    Once the above environment variable is created, include the "bin" (for Windows) or "lib/lib" (for Linux) directory of the SDK in the system PATH environment variable. To do this, add the following value to the system PATH variable:

    # Windows ( value is %FACEPHI_SELPHID_INSTALL_PATH%\bin )
set PATH=%PATH%;%FACEPHI_SELPHID_INSTALL_PATH%\bin

    # Linux ( value is $FACEPHI_SELPHID_INSTALL_PATH/lib/lib )
export PATH=$PATH:$FACEPHI_SELPHID_INSTALL_PATH/lib/lib

4. SDK Licensing

To license the SelphID SDK product, you need to perform the actions described below:

4.1 Generate machine identifiers

Before running the following utility, it is necessary to set the environment variable LD_LIBRARY_PATH as explained in the previous section.

The machine identifiers can be obtained by using a terminal and executing the following command in the directory where the utility is located: FACEPHI_SELPHID_INSTALL_PATH\bin (for both, Windows and Linux)

# Windows ( selphid-license-activator.exe )
cd C:\Program Files\FacePhi\Sdk\SelphId\x.x.x.x\bin
selphid-license-activator.exe -hostid SN > hostid.txt

# Linux ( selphid-license-activator.sh )
$ cd /opt/facephi/sdk/selphid/x.x.x.x/bin
$ ./selphid-license-activator -hostid SN > hostid.txt

Important

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

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

Example with the above serial number:

# Windows ( selphid-license-activator.exe )
selphid-license-activator.exe -hostid XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX > hostid.txt

# Linux ( selphid-license-activator.sh )
$ ./selphid-license-activator -hostid XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX > hostid.txt

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

Important

Starting with version 6.2.0, there is the possibility of online activation of the license. In this case, the license 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 Install the license

The steps required for the license installation are described below:

  • Copy the license in the config directory

    To install the license, just copy the license.lic file that you will receive from your distributor in the config directory located in the installation path of the SDK: 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 with the value of the path where the license is located:

    # Windows
FACEPHI_SELPHID_FACIAL_LICPATH_KEY=C:\Program Files\FacePhi\Sdk\SelphId\x.x.x.x\config\license.lic

    # Linux
FACEPHI_SELPHID_FACIAL_LICPATH_KEY=/opt/facephi/sdk/selphid/x.x.x.x/config/license.lic

Note

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


Important

It is essential to verify that the values of the following variables are properly configured to existing paths in the operating system:

  • FACEPHI_SELPHID_FACIAL_LICPATH_KEY: Path to license.lic file.
  • FACEPHI_SELPHID_FACIALLIVENESS_PATH_KEY: Path to /data folder of SelphID intallation. Required for passive liveness.
  • FACEPHI_SELPHID_USAGEPATH_KEY: Path to file where usage statistics are stored.
  • FACEPHI_SELPHID_DEBUGPATH_KEY: Path to file where debug info is stored. If omitted, no debug info will be generate.

Also, it is necessary to check the license expiration date (can be found inside the license file, in the "dateEnd" field) to assert that the license is valid and not expired.

4.3 Install license service

SelphID SDK license server is a terminal app to run on Windows or Linux.

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

Requeriments:

  • Hardware:

    • Static HostID
    • Static port

  • Software:

    • SelphID SDK

  • Running license service in Linux terminal

    Steps running license service in user terminal in Linux:

    1. Unzip SelphID SDK. Example:

      $ /opt/fphi-selphid-sdk-linux64_X.X.X

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

      $ /opt/facephi/fphi-selphid-sdk-linux64_X.X.X/bin

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

      $ export \
    LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/facephi/fphi-selphid-sdk-linux64_X.X.X/lib/lib/

    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 path (-log).

      Important

      The license server must be launched in administrator mode. 

        $ sudo LD_LIBRARY_PATH="$LD_LIBRARY_PATH" ./selphid-license-server -lic license-server.lic -port 15000

    5. Example with writing the log to disk and console:

      $ cd /opt/facephi/fphi-selphid-sdk-linux64_X.X.X/bin
$ sudo LD_LIBRARY_PATH="$LD_LIBRARY_PATH" ./selphid-license-server -lic license-server.lic -port 15000 -log /home/user/serverlogs

      Important

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

    6. Example with console log:

      $ cd /home/user/facephi/fphi-selphid-sdk-linux64_X.X.X/bin
$ sudo LD_LIBRARY_PATH="$LD_LIBRARY_PATH" ./selphid-license-server -lic license-server.lic -port 15000

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

      $ sudo LD_LIBRARY_PATH="$LD_LIBRARY_PATH" ./selphid-license-server -lic license-server.lic -port 15000 -log /home/user/serverlogs

Activation code
---------------
eZPm5npMD2pYwV71uRDcWBcv7wLSoPh/4de763Lo5V7IPYMnhjj03foGyqTu180dT...

    8. This activation key has to be sent to your license provider, so that your license .lic can be updated.

    9. The license update will include the activation code for the server, which can now be started without having an Internet connection.

      $ sudo LD_LIBRARY_PATH="$LD_LIBRARY_PATH" ./selphid-license-server -lic license-server.lic -port 15000 -log /home/user/serverlogs

[2023-10-03 15:44:47+02:00] INF Starting floating license server...
[2023-10-03 15:44:47+02:00] INF Total number of available floating licenses: 20
[2023-10-03 15:44:47+02:00] INF Listening on port: 15000

    Important

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

  • Running license service as a Linux system service

    Steps running license service as a system service on Linux:

    1. Follow steps 1 and 2 from previous instructions.

    2. Run the app as a system boot app editing the crontab: $crontab -e:

  • Setting up environment variables

    $ export \
    LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/facephi/fphi-selphid-sdk-linux64_X.X.X/lib/lib/

  • Run SelphID License Server on system reboot

    $ @reboot \
    /opt \
    /facephi/fphi-selphid-sdk-linux64_X.X.X/bin/selphid-license-server \
    -lic /opt/ facephi/fphi-selphid-sdk-linux64_X.X.X/bin/license-server.lic \
    -port 15000 \
    -log /opt/facephi/fphi-selphid-sdk-linux64_X.X.X/bin/logFile.txt

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

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

      $ cat \
    /opt/facephi/fphi-selphid-sdk-linux64_X.X.X/bin/logFile.txt

# Output
<Date> - Listening: 127.0.0.1:15000
<Date> - Listening: \<IP>:15000