WebSocket API (deprecated)

Deprecated

This API has been deprecated in favor of the new WebSocket API v2.

The DocVal Server will directly communicate (End-to-End encrypted) with the eMRTD.

The DocVal Server is able to read the data (like MRZ info or photo of face) and verify the authenticity and integrity of the data.

If the eMRTD supports the Active Authentication or the Chip Authentication protocol, the DocVal Server will additionally be able to verify that the chip was not cloned.

The Result (Data and Check Results) will be posted (using an HTTP POST Request) to the configured Result Server. The server will retry up to 3 times (with 3-second timeout per attempt) if the POST fails due to network or connection errors. HTTP error responses other than 408, 429, and 5xx are not retried.

WebSocket API Endpoint /ws1/validate

The client connects to the WebSocket endpoint to enable the DocVal Server to communicate with the eMRTD.

/ws1/validate?return_result=true

Set the query parameter return_result to true if you want the result to be returned to the client.

1) Session begins with the Start Message

The client starts the process by sending a JSON-encoded Start Message as a text message.

Start Message Field	Type	Description
client_id	String	Used as an API Access key and selects the Result Server.
validation_id	String	Unique identifier provided to map the result to a user/session.
access_key	JSON	Access Key as described in the table below
nfc_adapter_supports_extended_length	Boolean	Indication if the NFC Adapter supports extended-length-APDUs.
max_command_bytes	Integer	(Optional) The maximum number of bytes in a command APDU.
max_response_bytes	Integer	(Optional) The maximum number of bytes in a response APDU.
platform	String	Client's platform identifier, e.g., "android", "ios".
enable_diagnostics	Boolean	(Optional) When enabled, the DocVal Server collects additional debugging data.

Access Key Field	Type	Description
document_number	String	The document number.
date_of_birth	String	Date of birth (yyMMdd).
date_of_expiry	String	Date of expiry (yyMMdd).
can	String	The 6-digit Card Access Number (CAN).

• The validation_id will be passed through to the Result Server with the result.
• To Access the chip either the 6 digit "CAN" or the "MRZ Info" is needed. The MRZ Info consists of the Document Number, the Date of Birth and the Date of Expiry.
• By providing values for max_command_bytes and max_resoponse_bytes the session duration is slightly shorter.
• With enable_diagnostics active, the DocVal Server attaches additional data to OpenTelemetry traces that can help debugging issues when reading passports. The data may contain personal information.

Examples

{
  "client_id": "YOUR CLIENT ID",
  "validation_id": "cf847daa-a548-4509-bdeb-4edd51aee448",
  "access_key": {
    "can": "153036"
  },
  "nfc_adapter_supports_extended_length": true,
  "platform": "android"
}

{
  "client_id": "YOUR CLIENT ID",
  "validation_id": "cf847daa-a548-4509-bdeb-4edd51aee448",
  "access_key": {
    "document_number": "123465789",
    "date_of_birth": "970825",
    "date_of_expiry": "251008"
  },
  "nfc_adapter_supports_extended_length": true,
  "platform": "ios"
}

2a) APDU Communication Between DocVal Server and eMRTD

The client device relays binary APDU commands between the DocVal Server and the eMRTD.

2b) Progress Updates

The DocVal Server sends status updates to the client as JSON text messages.

{
  "status": "READ_DG1"
}

The following status messages are to be expected (in this order):

Status Value	Description
"READ_ATR_INFO"	Reading file ATR/INFO.
"ACCESS_CONTROL"	Performing Access Control using the Access Key.
"READ_SOD"	Reading file SOD.
"READ_DG14"	Reading file DG14 (only if present).
"CHIP_AUTHENTICATION"	Performing Chip Authentication (only if supported).
"READ_DG15"	Reading file DG15 (only if present).
"ACTIVE_AUTHENTICATION"	Performing Active Authentication (only if supported).
"READ_DG1"	Reading file DG1.
"READ_DG2"	Reading file DG2.
"READ_DG7"	Reading file DG7 (only if present).
"READ_DG11"	Reading file DG11 (only if present).
"READ_DG12"	Reading file DG12 (only if present).
"PASSIVE_AUTHENTICATION"	Verifying the authenticity and integrity of the data.
"DONE"	Process is finished

• Some files are optional and may not be present in all passports.
• The Active Authentication and the Chip Authentication protocol are optional and not supported on all eMRTDs.

3) Result is posted to the Result Server

The DocVal Server will post the result to the Result Server. The Result Server Url can be configured for each client_id.

This architecture is chosen to avoid storing sensitive eMRTD data on the DocVal Server.

Field	Type	Description
emrtd_passport	JSON	The eMRTD.
client_validation_id	String	The id provided by the client with the Start Message.

{
  "emrtd_passport": {
    ...
  },
  "client_validation_id": "cf847daa-a548-4509-bdeb-4edd51aee448"
}

4) Client receives the Result (conditional)

Depending on the return_result query parameter, the result will additionally be sent to the client, which is useful if the client needs to display the results.

5a) WebSocket session close

There is an issue with iOS 13 and 14's URLSessionWebSocketTask, where the Close DelegateFunction is not always triggered despite Wireshark showing the close is indeed confirmed. This issue does not appear in iOS 15.

To circumvent this issue, the close code and close reason are (unconventionally) sent as a json encoded text message.

Example

{
  "close_code": 1011,
  "close_reason": "POST_TO_RESULT_SERVER_FAILED"
}

Client implementations that are reliably able to handle WebSocket-Session-Closes may in good conscience ignore this text message.

5b) WebSocket is closed

Upon successful completion without errors, the DocVal Server will close the WebSocket connection using Close Code 1000, without specifying a Close-Reason-Phrase.

Errors During the Process

If an error occurs, the DocVal Server will close the WebSocket connection with the following possible Close-Reason-Phrases.

Close-Reason-Phrase used by the DocVal Server	Description
TIMEOUT_WHILE_WAITING_FOR_START_MESSAGE	No Start Message received in time.
TIMEOUT_WHILE_WAITING_FOR_RESPONSE	No APDU Response received in time.
INVALID_CLIENT_ID	Invalid Client ID provided.
INVALID_START_MESSAGE	Incorrectly encoded Start Message.
UNEXPECTED_MESSAGE	Unexpected Text Message received.
INVALID_ACCESS_KEY_VALUES	Wrong Access Key values provided.
ACCESS_CONTROL_FAILED	An Error occurred during Access Control.
EMRTD_PASSPORT_READER_ERROR	An Error during the eMRTD session.
FILE_READ_ERROR	An Error occurred while reading a file.
COMMUNICATION_FAILED	WebSocket communication (network) failure.
POST_TO_RESULT_SERVER_FAILED	Failed to post result to Result Server.
SERVER_ERROR	Server side exception occurred.
MAX_SESSION_TIME_EXCEEDED	Session exceeded maximum time.

The Close-Codes are from the WebSocket Protocol which is defined in RFC6455. Because of this there can be multiple phrases for a single Close-Code.

Test With the kinegram.digital DocVal Server Instance

kinegram.digital instance of the DocVal Server.
See Privacy Notice.

wss://docval.kurzdigital.com