DocVal Server Installation Guide

DocVal Server – Installation Guide

The OVD Kinegram Document Validation Service is provided as a Docker Image.

The application is a Java program located at path /app/documentvalidation.jar inside the Docker container.

Docker Registry

To access the Docker image, you need to log in to the Kurz Digital Docker Registry:

$ docker login registry.kurzdigital.com -u  -p 

To pull the latest image run:

$ docker pull registry.kurzdigital.com/kta/kta-kinegram-document-validation-service:latest

Example Setup using Docker Compose

Configure the docker-compose.yml

Create a new file called docker-compose.yml in a folder where you want to run the service from and put this into it:

version: '2'
services:
  app:
    image: 'registry.kurzdigital.com/kta/kta-kinegram-document-validation-service:latest'
    ports:
      - "5000:8080"
    environment:
      - CLIENT_IDS=;;;
      - RESULT_SERVER_URLS=;;;
      - WS_ENDPOINT_INCLUDE_BINARY_FILES_IN_RESULT=false
    volumes:
	  - log:/app/log
volumes:
  log:
    external: true

The Document Validation Service Application will listen on container port 8080. In this example the container port 8080 is mapped to port 5000 on the host machine.

Server Logs

Create a folder called “log” next to where your docker-compose.yml is. This folder will receive the server log files.

Running the Docker container

With docker-compose.yml in place, you can start the Docker container in a local terminal:

$ docker-compose up

Environment Variables

Application Configuration

CLIENT_IDS
Holds a semicolon separated list of allowed client ids. These client ids function as API access keys. See the files websocket_api/API.html, rest_api/API.html on how to use these client ids.

RESULT_SERVER_URLS
Holds a semicolon separated list of result server URLs. For each client id one corresponding result server URL needs be configured. The result URL is important for clients that use the WebSocket API. See the file websocket_api/API.html for details.

WS_ENDPOINT_INCLUDE_BINARY_FILES_IN_RESULT
Either “true” or “false”. Whether the emrtd_passport in the Result JSON will contain the binary files (SOD and DataGroups). Defaults to “false”. See the files emrtd_result.html for details.

Proxy Configuration

Use the following environment variables for your proxy configuration (if needed).

HTTP_PROXY_HOST (optional)
The host name of the Proxy Server for outgoing HTTP requests.

HTTP_PROXY_PORT (optional)
The port of the Proxy Server for outgoing HTTP requests. Defaults to “80”.

HTTPS_PROXY_HOST (optional)
The host name of the Proxy Server for outgoing HTTPS requests.

HTTPS_PROXY_PORT (optional)
The port of the Proxy Server for outgoing HTTPS requests. Defaults to “443”.

NON_PROXY_HOSTS (optional)
List of hosts that should be reached directly, bypassing the proxy. This is a list of patterns separated by ‘|’. The patterns may start or end with a ‘*’ for wildcards.

CA Certificates Configuration

If your Proxy Server or your Result Server uses HTTPS with a non-public certificate, you can install additional trusted CA certificates by making the .crt file(s) available in the container at path /usr/local/share/ca-certificate using a Docker Volume.

When running the container, the update-ca-certificates program will be executed.

[…] all certificates with a .crt extension found below /usr/local/share/ca-certificates are also included as implicitly trusted.

— Debian update-ca-certificates

Need additional Configuration Options?

You can run java with custom arguments. To do this, override the entrypoint of the Docker container. This is how your custom entrypoint command could e.g. look like:

bash -c "update-ca-certificates; java  -jar documentvalidation.jar"

If you override the entrypoint, remember to follow the Java Networking and Proxies Guide to set up your proxy configuration.

Document Validation Service API

REST API

With the rest API endpoint v4/validate the raw data from an eMRTD NFC Chip can be parsed and its authenticity and integrity can be verified. See rest_api/API.html.

Your OVDK contact is able to provide you with an Android SDK and an iOS SDK called emrtd-sdk which provides the functionality to read the required data from the eMRTD NFC Chip.

WebSocket API

With the WebSocket endpoint reached at ws1/validate the raw data from an eMRTD can be parsed and its authenticity and integrity can be verified. Also, “Chip not cloned” can be verified if the eMRTD supports the corresponding protocols. See websocket_api/API.html.

Your OVDK contact is able to provide you with an Android SDK and an iOS SDK called emrtd-connector which provides the functionality to allow the Document Validation Server to connect to an eMRTD NFC Chip using the WebSocket interface.

Open Source Licenses

• de.digitalcollections.imageio Apache License 2.0
• OpenJPEG BSD
• org.bouncycastle Apache License 2.0
• org.jmrtd GNU Lesser General Public License
• org.json The JSON License
• org.springframework.boot Apache License 2.0

LGPL Compliance

In order to comply with LGPL the JMRTD Library can be exchanged. The following is an example of how it can be done.

The Document Validation Service application is located at path `/app/documentvalidation.jar` inside
the container.
Remove the existing jmrtd.jar from the application using:
$ zip -d documentvalidation.jar "BOOT-INF/lib/jmrtd-*.jar"
Insert the new jmrtd-*.jar using the [Jar Tool][jartool]:
$ jar u0f documentvalidation.jar BOOT-INF/lib/jmrtd-0.7.31.jar