DocVal Server REST API

Best Practice DocVal Server – REST API

1. Transfer the required files to your Server

Transfer the eMRTD passport files SOD, and the Data Groups in raw binary form to your Server. See the readme of the Mobile SDKs on how to access these files.

2. Your Server sends those files to the Document Validation Server

To validate the document using the document validation service, your Server needs to send a POST request to the Document Validation Server (DocVal Server).

The OVDK Instance of the Document Validation Server can be reached via the following url:

https://kinegramdocval.lkis.de/v4/validate

Set the Content-Type of the POST request to multipart/form-data and provide the following values:

client_id      text/plain                    Client ID
sod            application/octet-stream      SOD File
dg1            application/octet-stream      Data Group 1 File
dg2            application/octet-stream      Data Group 2 File
...            ...                           ...
dg16           application/octet-stream      Data Group 16 File

The fields client_id and sod are mandatory!

The Data Groups (dg1, dg2, …) are optional.

• client_id functions as an API Access key. Is configured by you, if the DocVal Service runs On-Premise. CUSTOMER may use Client ID “YOUR CLIENT ID” with the OVDK Instance of the DocVal Server.
• sod is the SOD File from the chip in raw binary form.
• dg1 is the Data Group 1 File from the chip in raw binary form.
• dg2 is the Data Group 2 File from the chip in raw binary form.
• dg3, dg4, …, dg16 accordingly, for all further Data Groups

3. The Document Validation Server performs Passive Authentication and parses the files

With Passive Authentication the integrity and authenticity of the data (like MRZ info, photo of face) can be verified based on a list of trusted country certificates.

The DocVal server performs Passive Authentication. The integrity and authenticity of all Data Groups that are present in the request will be verified.

For each Data Group that is not present in the request, the integrity and authenticity of the Data Group can be verified using the information available in SOD Info.

See security_mechanisms.html for a detailed description of Passive Authentication.

The DocVal server parses the SOD. The Data Groups (1, 2, 7, 11, 12), that are present, in the request will be parsed as described in ICAO Doc9303 Part 10.

4. The Document Validation Server returns the results to your Server

The result consists of the passive authentication result and the parsed files. See the file emrtd_result.html for an explanation of the result. At that point all data about a passport will be deleted. The DocVal server is designed to not store any passport data longer than needed.

Testing the v4/validate Endpoint

You may test the endpoint with the resources in directory passport_pia_sample.

curl --request POST \
    --url https://kinegramdocval.lkis.de/v4/validate \
    --header 'Content-Type: multipart/form-data' \
    --form client_id="YOUR CLIENT ID" \
    --form sod=@passport_pia_sample/sod.ef \
    --form dg1=@passport_pia_sample/dg1.ef \
    --form dg2=@passport_pia_sample/dg2.ef

Or with the resources in directory passport_peter_parker.

curl --request POST \
    --url https://kinegramdocval.lkis.de/v4/validate \
	--header 'Content-Type: multipart/form-data' \
	--form client_id="YOUR CLIENT ID" \
	--form sod=@passport_peter_parker/sod.ef \
	--form dg1=@passport_peter_parker/dg1.ef \
	--form dg2=@passport_peter_parker/dg2.ef \
	--form dg7=@passport_peter_parker/dg7.ef \
	--form dg11=@passport_peter_parker/dg11.ef \
	--form dg12=@passport_peter_parker/dg12.ef \
	--form dg14=@passport_peter_parker/dg14.ef \
	--form dg15=@passport_peter_parker/dg15.ef

Please note that with these test resources (passport_pia_sample, passport_peter_parker) the correct result for passive_authentication is false as the document certificate in the sod file is not valid because it was not issued by a trusted country certificate authority.

Or with the SOD resource in the directory passport_tim_vogel:

curl --request POST \
    --url https://kinegramdocval.lkis.de/v4/validate \
    --header 'Content-Type: multipart/form-data' \
    --form client_id="YOUR CLIENT ID" \
    --form sod=@passport_tim_vogel/sod.ef

This sod is from a genuine german passport. The correct result for passive_authentication is therefore true. The result contains the hashes for the available Data Groups and the hash algorithm used (sod_info). The authenticity and integrity of the Data Groups can be verified by your server.