DocVal Server Example eMRTD Result

Example

{
  "emrtd_passport": {
    "sod_info": {
      "hash_algorithm": "SHA-256",
      "hash_for_data_group": {
        "1": "B7ZYsPUdx6/77hON2QpI/7Hr36tlH5m+Am0WuzWDFn4=",
        "2": "b4xR1WNjbu5DY67seOpC8OAmkwErnwbsXkJIzTiCuas=",
        "7": "Rt0gaZ1pvAnp0CEcd+ir05fWCpT+cj7ecKxH+rWUDoo=",
        "11": "/oYfYTAHXtF5oZbb6kcMrq7BGoMVtmOWsqvM0ctyBCI=",
        "12": "IXIYTHM0l3EeCpu74Z1zHTGT1HQH1KRKU+2Dhu8OuRA=",
        "14": "w62EEvLa74fLyhBYiulDtrt/2vQmueFGAJM5s+UdtMM=",
        "15": "VjBncDBu+qGAcCoZFthMNuU3pmBR8ECLXejkKhjIM+A="
      }
    },
    "mrz_info": {
      "document_type": "TD3",
      "document_code": "P",
      "issuing_state": "UTO",
      "primary_identifier": "SAMPLE",
      "secondary_identifier": [
        "PIA", "ANGELA"
      ],
      "nationality": "UTO",
      "document_number": "A51284970",
      "date_of_birth": "810725",
      "gender": "FEMALE",
      "date_of_expiry": "200617",
      "optional_data1": "",
      "optional_data2": null
    },
    "face_photo": "/9j/4AAQ...",
    "signature_photos": [
      "/9j/4AAQ..."
    ],
    "additional_personal_details": {
      "full_name_of_holder": "PIA ANGELA SAMPLE",
      "other_names": [],
      "personal_number": null,
      "full_date_of_birth": "19810725",
      "place_of_birth": "UTOPIA",
      "permanent_address": null,
      "telephone": null,
      "profession": null,
      "title": null,
      "personal_summary": null,
      "proof_of_citizenship_image": null,
      "other_valid_travel_document_numbers": null,
      "custody_information": null
    },
    "additional_document_details": {
      "issuing_authority": "UTOPIA",
      "date_of_issue": "20100618",
      "names_of_other_persons": null,
      "endorsements_and_observations": null,
      "tax_or_exit_requirements": null,
      "image_of_front": null,
      "image_of_rear": null,
      "date_and_time_of_personalization": null,
      "personalization_system_serial_number": null
    },
    "passive_authentication": false,
    "passive_authentication_details": {
      "sod_signature_valid": true,
      "document_certificate_valid": false,
      "data_groups_checked": [
        1,
        2,
        7,
        11,
        12,
        14,
        15
      ],
      "data_groups_with_valid_hash": [
        1,
        2,
        7,
        11,
        12,
        14,
        15
      ],
      "error": null,
      "all_hashes_valid": true
    },
    "chip_authentication_result": "SUCCESS",
    "active_authentication_result": "UNAVAILABLE",
    "errors": [],
    "files_binary": {
      "dg7": "Z4IGqwIBAV9Dggaj/9j/4AAQSkZ...",
      "dg14": "bgIxAA...",
      "sod": "d4IKgjCCCn4GCSqGSIb3DQEHAqCCCm...",
      "dg12": "bDVcBF8ZXyZfGSFVTklURUQgU1RBVEVTIERFUEFSVE1FTlQgT0YgU1RBVEVfJggyMDA5MTExNg==",
      "dg11": "azpcBl8OXytfEV8OFVBFVEVSIEJFTkpBTUlOIFBBUktFUl8rCDIwMDEwODEwXxEMTkVXIFlPUksgVVNB",
      "dg2": "dYIGKH9hggYjAgEB...",
      "dg1": "YVtfH1hQPFVTQVBBUktFUjw8UEVURVI8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDVTMjgwODA2PDN..."
    }
  },
  "client_validation_id": "69fe774e-50d3-49fc-a285-6fab7665563e"
}

EMRTD Result JSON

The field emrtd_passport contains the Result about the document.

SOD Info

The sod_info contains the hashes for all available Data Groups (hash_for_data_group) and the hash algorithm (hash_algorithm) used to calculate those hashes.

You can use these values to verify the authenticity and integrity of each Data Group without sending sensitive data to the Document Validation Server. (Only applicable when using the REST API)

The following steps would be necessary:

1. Verify that the passive_authentication was successful.
2. Recalculate the hash for each Data Group using the specified hash_algorithm.
3. Compare the calculated hash with the expected hash for each Data Group.

MRZ Info

Will be null The Data Group 1 contains the MRZ Info, which will be parsed and returned as mrz_info . Please note mrz_info may be null if the file could not be parsed. Please refer to ICAO Doc9303 for details on those MRZ fields.

• document_type
  Type of Document. Passports are mostly in format “TD3”. Possible Values are “TD1”, “TD2”, “TD3”. See ICAO Doc9303 for a detailed descriptions of the formats.
• document_code
  Document Code. Passports will have “P”. See ICAO Doc9303 for all possible values.
• issuing_state
  Issuing State as specified in Doc 9303-3. Usually a three-letter country code. An exception is the german passport which uses only one letter D.
• primary_identifier
  The issuing State or organization shall establish which part of the name is the primary identifier. This may be the family name, the maiden name or the married name, the main name, the surname, and in some cases, the entire name where the holders name cannot be divided into two parts.
• secondary_identifier
  The remaining parts of the name are the secondary identifier.
• nationality
  Nationality of the holder. The three-letter code specified in Doc9303-3 is used, except for the german passport that is using D as the country code for holders with german nationality.
• document_number
  As given by the issuing State or organization to uniquely identify the document from all other MRTDs issued by the State or organization.
• date_of_birth
  Date of birth. The structure is as follows: yyMMdd.
• gender
  The gender. One of the following: “FEMALE”, “MALE”, “UNSPECIFIED”.
• date_of_expiry
  Date of expiry. The structure is as follows: yyMMdd.
• optional_data1
  For optional use.
• optional_data2
  For use of the issuing State or organization. (TD1 only)

Note to the Date of Expiry (date_of_expiry) in the MRZ Info (Data Group 1): The Date of Expiry from the MRZ is often before the Not After-Date of the Document Certificate. Hence, To check if a document is expired, check the Date of Expiry from the MRZ/DG1.

Face Photo

The Data Group 2 contains at least one photo of the face of the document holder. This photo will be extracted and returned as a Base64 encoded JPEG. Please note face_photo may be null if the file could not be parsed.

Signature Photos

The Data Group 7 will contain one or more photo(s) of the signature or usual mark. This/These photo(s) will be extracted and returned as signature_photos. The photos will be Base64 encoded JPEGs.

Additional Personal Details

The Data Group 11 will contain additional personal details. This details will be parsed and returned as additional_personal_details.

Additional Document Details

The Data Group 12 will contain additional document details. This details will be parsed and returned as additional_document_details.

Passive Authentication

The overall result of passive Authentication will be returned in field passive_authentication.

passive_authentication
Overall Passive Authentication result. Whether the integrity and authenticity of the data could be verified using a trusted country certificate.
Possible values: {true, false}

The details of each Passive Authentication step will be returned as passive_authentication_details .

• document_certificate_valid
  Whether the document certificate was issued by a trusted country certificate authority.
  Possible values: {true, false, null}
• sod_signature_valid
  Whether the signature of the Document Security Object (SOD) could be verified with the public key of the document certificate.
  Possible values: {true, false, null}
• data_groups_checked
  List of Data Groups that have been checked.
  Possible values: List of Integers or null
• data_groups_with_valid_hash
  List of Data Groups, with a correct hash value. The contents of these Data Groups are authentic and unchanged.
  Possible values: List of Integers or null
• all_hashes_valid
  Whether all Data Groups that were checked have a correct hash value. Possible values: {true, false, null}
• error
  Error while performing Passive Authentication.
  Possible values: {null, “FAILED_TO_PARSE_SOD”, “DATA_GROUPS_HASHED_WITH_UNSUPPORTED_ALGORITHM”, “SIGNATURE_VERIFY_EXCEPTION”}
  In case of “SIGNATURE_VERIFY_EXCEPTION”, the field sod_signature_valid will be false. However, the signature could not be verified because of an exception.

Please note that some fields may be null, if one of the errors {“FAILED_TO_PARSE_SOD”, “DATA_GROUPS_HASHED_WITH_UNSUPPORTED_ALGORITHM” or “SIGNATURE_VERIFY_EXCEPTION”} occurred.

Please see security_mechanisms.html and for a detailed description of Passive Authentication.

Chip Authentication Result

Verifies that the Chip is not cloned. The Chip Authentication protocol is optional and may not be supported by all eMRTDs.

Possible Values are: { “SUCCESS”, “FAILED”, “UNAVAILABLE” }. If the eMRTD does not support Chip Authentication the result will be “UNAVAILABLE”.

The Chip Authentication Result is only meaningful if the integrity and authenticity of DG14 is confirmed (passive_authentication must be true!!).

Please see security_mechanisms.html and for a detailed description of Chip Authentication.

The field chip_authentication_result is not present in the response of the REST endpoint v4/validate, because Chip Authentication requires the server to access to the Chip directly.

Active Authentication Result

Verifies that the Chip is not cloned. The Active Authentication protocol is optional and may not be supported by all eMRTDs.

Possible Values are: { “SUCCESS”, “FAILED”, “UNAVAILABLE” }. If the eMRTD does not support Active Authentication the result will be “UNAVAILABLE”.

The Active Authentication Result is only valid if the integrity and authenticity of DG15 (and DG14 if present) is confirmed (passive_authentication must be true!!).

Please see security_mechanisms.html and for a detailed description of Active Authentication.

The field active_authentication_result is not present in the response of the REST endpoint v4/validate.

Errors

The field errors may contain other general errors that occurred while processing the data.
Possible values are explained below:

• "FAILED_TO_PARSE_SOD"
  SOD File could not be parsed.
• "FAILED_TO_PARSE_DG1", "FAILED_TO_PARSE_DG2", "FAILED_TO_PARSE_DG7", "FAILED_TO_PARSE_DG11", "FAILED_TO_PARSE_DG12"
  The Data Group File could not be parsed.
• FAILED_TO_ENCODE_FACE_PHOTO_AS_JPEG
  The Face Photo could not be encoded as a normal JPEG. The raw image bytes are returned as Base64 String in the field face_photo anyways.
• FAILED_TO_ENCODE_SIGNATURE_PHOTO_AS_JPEG
  One or more Signature Photo(s) could not be encoded as a normal JPEG. The raw image bytes are returned as Base64 String in the field signature_photos anyway.

Files Binary

The field files_binary contains the SOD and the DataGroup files in binary form, base64 encoded. Please refer to ICAO Doc9303 – Part 10 if you are interested in the encoding of these files.

The field files_binary is only present if the corresponding environment variable is set to “true”. Please see INSTALL.html.

The field files_binary is not present in the response of the REST endpoint v4/validate.

Additional JSON Fields may be added in the future

This emrtd_passport JSON is designed to contain all relevant infos about a ICAO eMRTD documents and the relevant infos about Check Results (Passive Authentication, Chip Authentication, Active Authentication).

However, we might add further additional fields to this result JSON in the future. Your Parser of the emrtd_passport JSON Object should be implemented in a way, that additional fields do not break it. In the case a field is added, we will provide an updated Documentation to you.

Client Validation ID

The field client_validation_id is a (unique) transaction id to identify the verification and to map the result to a user/session. This is the validation_id the WebSocket client used.

The field client_validation_id is not present in the response of the REST endpoint v4/validate.