Skip to content

Complete Server-Side Verification

While it's true that all authenticity checks can be successfully completed on smartphones and edge devices, they alone might not suffice. There's a potential risk of verification results being intercepted and modified by fraudsters directly on the same device. In the "zero trust to mobile" approach, Regula applies an additional layer of protection against such a fraud through Complete Server-Side Verification.

Steps to set up the Server-Side Verification:

0. Preparation
1. Enable Server-Side Verification
2. Connect Database
3. Connect Storage
4. Configure RFID Chip Reprocessing (optional)
5. Configure Mobile Side

Preparation

To initiate the process of the Server-Side Verification, the Mobile SDK calls the /api/v2/transaction/start endpoint for the Web Service to create a transaction. So this endpoint needs to be accessible between the client and server, otherwise the process returns an error.

For details about all available transaction requests, see the Document Reader Web API specification.

Step 1: Enable Server-Side Verification

To enable the Server-Side Verification functionality, use:

config.yaml
service:
  sessionApi:
    enabled: true

Also, you can configure the location of transaction records as described below:

config.yaml
service:
  sessionApi:
    enabled: true
    transactions:
      location:
        bucket: "docreader-transactions"
        container: "docreader-transactions"
        folder: "docreader-transactions"
        prefix: "session-api"
Parameter Type Default Description
enabled boolean false Whether to enable the Session API too.
bucket string docreader-transactions Location (bucket) where to save encrypted processing results packages in the case of the Google Cloud Storage or Amazon S3.
container string docreader-transactions Location (container) where to save encrypted processing results in the case of the Microsoft Azure.
folder string docreader-transactions Location (folder) where to save processing encrypted results in the case of the local file system. May represent an absolute path.
prefix string — Single prefix line for all defined locations. When set, gives ability to keep the stored processing results in a more organized way regardless of the selected storage type.

Step 2: Connect Database

A database is used to collect the transaction information, public and private keys. It is required to be configured in case of the Server-Side Verification.

Supported database management systems:

  • PostgreSQL v14 and higher. If you use v13 and older, you need to add an extension by invoking the following script:
CREATE EXTENSION pgcrypto;

To set up the connection to database, use:

config.yaml
service:
  database:
    connectionString: "postgresql://<username>:<password>@127.0.0.1:5432/regula_docreader_db"
config.yaml
service:
  database:
    connectionString: "mysql+pymysql://<username>:<password>@127.0.0.1:3306/regula_docreader_db"
config.yaml
service:
  database:
    connectionString: "mysql+pymysql://<username>:<password>@127.0.0.1:3306/regula_docreader_db"

Single-Instance Deployment

A single-instance architecture consists of one database instance and one database.

For this kind of deployment, all you need is to define the connection string as follows:

config.yaml
service:
  database:
    connectionString: "oracle+oracledb://system:admin@localhost:1521/FREE"

Multi-Instance Deployment

An Oracle Real Application Clusters (Oracle RAC) architecture consists of multiple instances that run on separate server machines. All of them share the same database. In this case, the client is connected by the service name.

For now, the connection to multi-instance deployment of Oracle DB is available only on Windows OS (x86 and x64 architectures).

To connect to the database in multi-instance mode, follow the instructions:

  1. Download and install (unpack) the Oracle Instant Client for Windows.
  2. Add to the Windows PATH variable the location to the Client installed on the previous step. For example C:\oracle\instantclient\
  3. Define the connection string to database in the specific form as shown below.
config.yaml
service:
  database:
    connectionString: "oracle+cx_oracle://system:admin@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=127.0.0.1)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=FREE)))

Linux:

config.yaml
service:
  database:
    connectionString: "sqlite:////opt/regula/document-reader-webapi/regula_docreader.db"

Windows:

config.yaml
service:
  database:
    connectionString: "sqlite:///С:/regula_docreader.db"
config.yaml
service:
  database:
    connectionString: "mssql+pymssql://<username>:<password>@127.0.0.1:1433/regula_docreader_db"
Parameter Type Default Description
connectionString string — The connection string to the database by the pattern dialect://user:password@host/dbname[?key=value..]. Due to security reasons, has different order of precedence.

Passwordless Authentication

There is an alternative Passwordless cloud authentication mechanism is available for the database connection. In this case, instead of sending the username/password combination directly in the DB connection string, the specific driver obtains the access token from the cloud provider and attaches it to the SQL connection.

This authentication mechanism currently works only for Azure SQL Database, but it's expected to support more providers in future releases.

To set up the feature, use the passwordlessAuth section:

config.yaml
service:
  database:
    connectionString: "mssql+pyodbc://@<database>.database.windows.net/faceapi?driver=ODBC+Driver+18+for+SQL+Server"
    passwordlessAuth:
      enabled: true
      type: az
      az:
        scope: "https://database.windows.net/.default"
Parameter Type Default Description
enabled boolean false Whether to enable the passwordless authentication mechanism. If not set, but other parameters of the passwordlessAuth section are filled, then the mechanism is also applied.
type string — Type of cloud storage provider used for the passwordless authentication. Should be set to az for Azure.
az → scope string — Scope for which the access token is requested during authentication process.

Step 3: Connect Storage

A storage is used to collect the request, response, document images, metadata, session keys and challenges of the RFID chip processing.

It is required to be configured in case of the Server-Side Verification.

How to connect Storage

Step 4: Configure RFID Chip Reprocessing (Optional)

Chip Verification

Chip Verification as part of RFID chip reprocessing includes Chip Authentication and Active Authentication.

To set up the Chip Verification, use:

config.yaml
sdk:
  rfid:
    chipVerification:
      enabled: true
Parameter Type Default Description
enabled boolean false Whether to enable the server-side chip verification

Passive Authentication

To enable the Passive Authentication as part of the RFID chip reprocessing, define the path to the folder where the certificate files are located:

config.yaml
sdk:
  rfid:
    PKD_PA: "rfid_pkd"
config.yaml
sdk:
  rfid:
    PKD_PA: "C:\\Program Files\\Regula\\Document Reader Web API\\rfid_pkd"

Also, you can configure the additional processing parameters of RFID Passive Authentication as described below:

config.yaml
sdk:
  rfid:
    PKD_PA: "rfid_pkd"
    paSensitiveCodes:
      - -1879048190
      - -1879048189
    paIgnoreNotificationCodes:
      - -1879047913
      - -1879047667
config.yaml
sdk:
  rfid:
    PKD_PA: "C:\\Program Files\\Regula\\Document Reader Web API\\rfid_pkd"
    paSensitiveCodes:
      - -1879048190
      - -1879048189
    paIgnoreNotificationCodes:
      - -1879047913
      - -1879047667
Parameter Type Default Description
PKD_PA string — Custom folder prepopulated with master lists for the RFID public key directory. If the parameter is present, the corresponding checks are performed. Note, that Windows requires the fully-qualified absolute path, while for Linux you can use either absolute or relative. RFIDPKDResourceType enum contains the list of supported certificate files.
paSensitiveCodes array of integers — List of error codes, considered as critical during processing. See the full list of available notification codes by the link: eLDS_ParsingErrorCodes enumeration.
paIgnoreNotificationCodes array of integers — List of notification codes that should be ignored during passive authentication (PA). See the full list of available notification codes by the link: eLDS_ParsingNotificationCodes enumeration.

Step 5: Configure Mobile Side

After the Web Service is set up, you need to configure the Document Reader Mobile SDK. Refer to the Mobile SDK section for instructions on how to do that.

Example

Below, see the contents' example of the config.yaml file or download it.

config.yaml
sdk:
  rfid:
    chipVerification:
      enabled: true

service:
  webServer:
    port: 8080
    workers: 1
    timeout: 30

    demoApp:
      enabled: true

    cors:
      origins: "*"
      headers: "Content-Type"
      methods: "POST,PUT,GET,DELETE,PATCH,HEAD"

    ssl:
      enabled: false
      cert: certs/tls.crt
      key: certs/tls.key
      tlsVersion: 1.2

    logging:
      level: INFO
      formatter: text

      access:
        console: true
        path: logs/docreader-access.log

      app:
        console: true
        path: logs/docreader-app.log

  processing:
    enabled: true
    results:
      location:
        bucket: docreader-processing
        container: docreader-processing
        folder: docreader-processing
        prefix: ""

  sessionApi:
    enabled: true
    saveRequest: true
    transactions:
      location:
        bucket: "docreader-transactions"
        container: "docreader-transactions"
        folder: "docreader-transactions"
        prefix: ""

  storage:
    type: s3

    s3:
      accessKey: minioadmin
      accessSecret: minioadmin
      endpointUrl: http://s3-storage:9000
      region: eu-central-1
      secure: true

  database:
    connectionString: "postgresql://regula:Regulapasswd#1@db-postgres:5432/regula_docreader_db"

If you use Docker Compose, you can mount the config.yaml in the docker-compose.yml file. See the example below or download it.

docker-compose.yml
version: "3.7"

services:
  docreader:
    container_name: docreader
    image: regulaforensics/docreader:latest
    volumes:
      - ./regula.license:/app/extBin/unix/regula.license
      - ./config.yaml:/app/config.yaml
    networks:
      - docreader-network
    healthcheck:
      test: curl -f http://127.0.0.1:8080/api/ping
      interval: 60s
      start_period: 60s
      timeout: 30s
      retries: 5
    depends_on:
      - s3-storage
      - db-postgres
    ports:
      - "8080:8080"

  # Storage
  s3-storage:
    image: quay.io/minio/minio:RELEASE.2023-10-25T06-33-25Z
    command: server --console-address ":9001" /data
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      MINIO_ACCESS_KEY: minioadmin
      MINIO_SECRET_KEY: minioadmin
    volumes:
      - minio-data:/data
    networks:
      - docreader-network
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://localhost:9000/minio/health/live" ]
      interval: 30s
      timeout: 20s
      retries: 3

  # Database
  db-postgres:
    image: postgres:latest
    restart: always
    volumes:
      - postgre-data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: "regula_docreader_db"
      POSTGRES_USER: "regula"
      POSTGRES_PASSWORD: "Regulapasswd#1"
    networks:
      - docreader-network
    ports:
      - "5432:5432"

volumes:
  minio-data:
  postgre-data:

networks:
  docreader-network:
    driver: bridge

To set the license, place the regula.license file into the same folder where the downloaded docker-compose.yml is located.

To start the Docker container, invoke:

sudo docker-compose up -d

To check the status, run:

sudo docker-compose ps

Next Steps