Skip to content

Complete Server-Side Verification for Document Reader Web Service

Smartphones and edge devices can complete authenticity checks, but these checks might not be enough. Fraudsters can intercept and modify verification results on the same device.

Complete Server-Side Verification adds another layer of protection against this risk.

Steps to set up the Server-Side Verification:

Preparation

To start Server-Side Verification, the Document Reader Mobile SDK calls the /api/v2/transaction/start endpoint of the Document Reader Web Service to create a transaction. Make sure that this endpoint is accessible from the client. Otherwise, the process fails with an error.

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

Step 1: Enable Server-Side Verification

To enable the Server-Side Verification functionality, use:

config.yaml
service:
  sessionApi:
    enabled: true

You can configure the location of transaction records as described below:

config.yaml
service:
  sessionApi:
    enabled: true
    saveRequest: 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.
saveRequest boolean false Whether to save the incoming request to the Storage. See the configuration details in the Step 3: Connect Storage.
bucket string docreader-transactions The location (bucket) where to save encrypted processing results packages in the case of the Google Cloud Storage or Amazon S3.
container string docreader-transactions The location (container) where to save encrypted processing results in the case of the Microsoft Azure.
folder string docreader-transactions The folder where encrypted processing results are saved when using the local file system. May represent an absolute path.
prefix string — A single prefix line for all defined locations. When set, helps organize stored processing results regardless of the selected storage type.

Step 2: Connect Database

A database stores transaction information, public keys, and private keys. It is required for Server-Side Verification.

The Document Reader Web Service provides support for several database integration options:

Self-hosted databases

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 database connection, 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.

Connection to a multi-instance Oracle DB deployment is available only on Windows (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+oracledb://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:///C:/regula_docreader.db"
config.yaml
service:
  database:
    connectionString: "mssql+pymssql://<username>:<password>@127.0.0.1:1433/regula_docreader_db"
config.yaml
service:
  database:
    connectionString: "mongodb://<username>:<password>@127.0.0.1:27017/regula_docreader_db?authSource=admin"
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.

Cloud databases

Regula Document Reader Web Service supports Amazon DynamoDB, providing multi-regional capabilities to achieve high availability for globally distributed users.

You can set up the connection to DynamoDB by one of the two methods:

config.yaml
service:
   database:
     dynamodb:  
       tablePrefix: regula-docreader
  • If not using the AWS infrastructure, you need to explicitly define the configuration:
config.yaml
service:
  database:
    dynamodb:
      region: eu-central-1
      accessKey: exampleKey
      accessSecret: example#1Secret
      tablePrefix: regula-docreader

Note

Don't use both the connectionString and dynamodb configurations in the same config.yaml for the Web Service, but specify one of them for connecting to either a self-hosted database or to DynamoDB.

After the database startup, all required tables and indexes will be automatically created. For details explore the config.yaml.example file in the Document Reader Web Service installation directory.

Passwordless authentication

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 supports only Azure SQL Database.

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 the authentication process.

Step 3: Connect Storage

Storage is used to store requests, responses, document images, metadata, session keys, and RFID chip processing challenges.

It is required for Server-Side Verification.

How to connect Storage

Step 4: Configure Data Cleanup (Optional)

To perform the automatic cleanup of the outdated service and transaction-related data in both the storage and database, the HouseKeeper is used. For more details about the mechanism, see Cleaning Up Data.

By default, the houseKeeper is disabled, so the cleanup is not applied.

The HouseKeeper operates on a task-based system, where tasks are executed at regular intervals defined by the beatCadence parameter. During each interval, the system checks for any outdated data that needs to be cleaned up. The HouseKeeper is capable of synchronizing and distributing its tasks across multiple instances, even in multi-instance or multi-machine setups.

You can access statistics for the HouseKeeper tasks via the /api/task/statistics endpoint.

To set up the HouseKeeper mechanism, use:

config.yaml
service:
  houseKeeper:
    enabled: true
    beatCadence: 10    
    keepFor: 14400     
    sessionApi:
      enabled: true   
      keepFor: 31536000
Parameter Type Default Description
enabled boolean false Whether to enable the HouseKeeper cleanup mechanism.
beatCadence integer 10 Frequency at which the HouseKeeper will check for outdated data (in seconds).
keepFor integer 14400 Time for retaining the HouseKeeper statistics in the database (in seconds). By default it's 4 hours (14400 seconds).
sessionApi → enabled boolean false Whether to clean up the data related to Session API transactions.
sessionApi → keepFor integer 31536000 Time for retaining the Session API statistics in the database (in seconds). By default it's 1 year (31536000 seconds).

Step 5: Configure RFID Chip or mDL 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
rfid→chipVerification→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: "rfid_pkd"
config.yaml
sdk:
  rfid:
    PKD_PA: "C:\\Program Files\\Regula\\Document Reader Web API\\rfid_pkd"

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:
      - -1879047658
      - -1879047667
config.yaml
sdk:
  rfid:
    PKD_PA: "rfid_pkd"
    paSensitiveCodes:
      - -1879048190
      - -1879048189
    paIgnoreNotificationCodes:
      - -1879047658
      - -1879047667
config.yaml
sdk:
  rfid:
    PKD_PA: "C:\\Program Files\\Regula\\Document Reader Web API\\rfid_pkd"
    paSensitiveCodes:
      - -1879048190
      - -1879048189
    paIgnoreNotificationCodes:
      - -1879047658
      - -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). Note that some codes are safe to ignore, while others must be not as they represent severe issues. See the full list of notification codes with details by the link: ParsingNotificationCodes.

mDL session verification

To enable the mDL Strict Key Check in the received mDL data payload, use:

config.yaml
sdk:
  mDL:
    sessionVerification:
      enabled: true
Parameter Type Default Description
mDL→sessionVerification→enabled boolean false Whether to enable the session verification for mDL

Step 6: Configure Client Side

After the Document Reader Web Service is set up, configure the client side. Refer to the Document Reader Mobile SDK or Document Reader Web Components for instructions on how to do that.

Endpoints Usage

For communication between the client and server, the following endpoints must be accessible from the mobile device:

Example

The following example shows the contents of the config.yaml file. You can also download the YAML file.

config.yaml
sdk:
  rfid:
    chipVerification:
      enabled: true
#    PKD_PA: "rfid_pkd" # relative path to the directory with PKD certificates

  mDL:
    sessionVerification:
      enabled: true

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

    demoApp:
      enabled: true

    cors:
      origins: "*"
      headers: "Content-Type,X-Client-Key"
      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

  houseKeeper:
    enabled: true
    beatCadence: 10
    keepFor: 14400
    sessionApi:
      enabled: true
      keepFor: 31536000

  database:
    connectionString: "postgresql://regula:Regulapasswd#1@db-postgres:5432/regula_docreader_db"
#    dynamodb:
#      region: eu-central-1
#      accessKey: exampleKey
#      accessSecret: example#1Secret
#      tablePrefix: regula-docreader

If you use Docker Compose, you can mount the config.yaml file in the docker-compose.yml file. You can also download the Docker Compose YAML file.

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
#      - ./rfid_pkd:/app/rfid_pkd # relative path to the directory with PKD certificates
    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