|
| UFR_STATUS DL_API | MRTD_MRZDataToMRZProtoKey (IN const char *doc_number, IN const char *date_of_birth, IN const char *date_of_expiry, OUT uint8_t mrz_proto_key[25]) |
| | In order to get the MRZ Proto Key needed in subsequent steps, you can call this function and pass it null terminated strings containing document number, document holder date of birth and document expiration date.
|
| |
| UFR_STATUS DL_API | MRTDAppSelectAndAuthenticateBac (IN const uint8_t mrz_proto_key[25], OUT uint8_t ksenc[16], OUT uint8_t ksmac[16], VAR uint64_t *send_sequence_cnt) |
| | Use this function to authenticate to the eMRTD NFC tag using BAC. This function establishes a security channel for communication. Security channel is maintained using send_sequence_cnt parameter and channel session keys are ksenc (for encryption) and ksmac (for calculating MAC).
|
| |
| UFR_STATUS DL_API | MRTDFileReadBacToHeap (IN const uint8_t file_index[2], VAR uint8_t **output, OUT uint32_t *output_length, IN const uint8_t ksenc[16], IN const uint8_t ksmac[16], VAR uint64_t *send_sequence_cnt) |
| | Use this function to read files from the eMRTD NFC tag.
|
| |
| uint32_t DL_API | MRTDGetDgIndex (uint8_t dg_tag) |
| | Use this function to get an index of the data groups from EF.DG1 to DG16 i.e. 1 to 16. For EF.COM, EF.SOD and invalid tag function returns 0.
|
| |
| c_string DL_API | MRTDGetDgName (uint8_t dg_tag) |
| | Use this function to get a name of the data group. Function returns pointer to the zero terminated string ("EF.COM", “EF.DG1”, “EF.DG2”, … , “EF.SOD”). For invalid tag function returns zero terminated string “NOT DEFINED”.
|
| |
| UFR_STATUS DL_API | MRTDGetDGTagListFromCOM (IN const uint8_t *com, uint32_t com_len, VAR uint8_t **dg_list, VAR uint8_t *dg_list_cnt) |
| |
| UFR_STATUS DL_API | MRTDGetImageFromDG2 (IN const uint8_t *dg2, uint32_t dg2_size, VAR uint8_t **image, VAR uint32_t *image_size, VAR uint32_t *img_type) |
| | Use this function to extract the facial image from the EF.DG2 content.
|
| |
| UFR_STATUS DL_API | MRTDGetImageFromDG2ToFile (IN const uint8_t *dg2, uint32_t dg2_size, IN const char *file_name_without_extension) |
| | Use this function to extract facial image from the EF.DG2 content and save it to file on the file system.
|
| |
| UFR_STATUS DL_API | MRTDParseDG1ToHeap (VAR char **sbuffer, IN const char *newln, IN const uint8_t *dg1, uint8_t dg1_len) |
| | Use this function to get verbose “printout” string containing MRZ (Machine Readable Zone) parsed data from the content of the EF.DG1 MRTD file.
|
| |
| UFR_STATUS DL_API | MRTDValidate (IN const char *cert_storage_folder, VAR char **out_str, IN const char *endln, uint32_t verbose_level, OUT uint8_t ksenc[16], OUT uint8_t ksmac[16], VAR uint64_t *send_sequence_cnt) |
| | This function validates data groups read from the eMRTDocument.
|
| |
| UFR_STATUS DL_API MRTDFileReadBacToHeap |
( |
IN const uint8_t | file_index[2], |
|
|
VAR uint8_t ** | output, |
|
|
OUT uint32_t * | output_length, |
|
|
IN const uint8_t | ksenc[16], |
|
|
IN const uint8_t | ksmac[16], |
|
|
VAR uint64_t * | send_sequence_cnt ) |
Use this function to read files from the eMRTD NFC tag.
You can call this function only after successfully established security channel by the previously called MRTDAppSelectAndAuthenticateBac() function. Session keys ksenc and ksmac, and also parameter send_sequence_cnt are acquired by the previously called MRTDAppSelectAndAuthenticateBac() function. After the successful call to this function, *output points to the file data read from an eMRTD file specified by the file_index parameter. Buffer, in which the data is stored, is automatically allocated on the memory heap during function execution. Maximum amount of data allocated can be 32KB. User is obligated to cleanup allocated data space, occupied by the *output, after use (e.g. by calling DLFree() or directly free() from the C/C++ code).
- Parameters
-
| file_index | Parameter that specifies the file we want to read from the eMRTD. This is a pointer to byte array containing exactly two bytes designating eMRTD file. Those two bytes are file identificator (FID) and there is a list of FIDs: EF.COM = {0x01, 0x1E} EF.DG1 = {0x01, 0x01} EF.DG2 = {0x01, 0x02} EF.DG3 = {0x01, 0x03} EF.DG4 = {0x01, 0x04} EF.DG5 = {0x01, 0x05} EF.DG6 = {0x01, 0x06} EF.DG7 = {0x01, 0x07} EF.DG8 = {0x01, 0x08} EF.DG9 = {0x01, 0x09} EF.DG10 = {0x01, 0x0A} EF.DG11 = {0x01, 0x0B} EF.DG12 = {0x01, 0x0C} EF.DG13 = {0x01, 0x0D} EF.DG14 = {0x01, 0x0E} EF.DG15 = {0x01, 0x0F} EF.DG16 = {0x01, 0x10} EF.SOD = {0x01, 0x1D} |
| output | After the successful call to this function, this pointer will point to the pointer on the file data read from an eMRTD file specified by the file_index parameter. Buffer, in which the data is stored, is automatically allocated during function execution. Maximum amount of data allocated can be 32KB. There is a programmer responsibility to cleanup allocated data (e.g. by calling DLFree(cert) or directly free(cert) from the C/C++ code). |
| output_length | After the successful call to this function, this pointer is pointed to the size of the file data read from an eMRTD file specified by the file_index parameter. |
| ksenc | Session encryption key acquired using prior call to MRTDAppSelectAndAuthenticateBac() function. |
| ksmac | Session key for calculating MAC acquired using prior call to MRTDAppSelectAndAuthenticateBac() function. |
| send_sequence_cnt | This pointer should point to a 64-bit value initialized by the previously successful call to MRTDAppSelectAndAuthenticateBac() function. Pointer to this 64-bit value should be saved and forwarded at every subsequent call to this function and/or other functions used for reading eMRTD. |
- Returns
- Operation status
| UFR_STATUS DL_API MRTDParseDG1ToHeap |
( |
VAR char ** | sbuffer, |
|
|
IN const char * | newln, |
|
|
IN const uint8_t * | dg1, |
|
|
uint8_t | dg1_len ) |
Use this function to get verbose “printout” string containing MRZ (Machine Readable Zone) parsed data from the content of the EF.DG1 MRTD file.
Function supports TD1, TD2 and TD3 Data Group 1 formats as defined in the ICAO Doc 9303-10 (seventh edition, 2015). Function automatically allocates memory on the heap, which *sbuffer parameter will point to after successful execution. User is obligated to cleanup allocated memory space, occupied by the *sbuffer, after use (e.g. by calling DLFree(sbuffer) or directly free(sbuffer) from the C/C++ code).
- Parameters
-
| sbuffer | After successful function execution, this pointer will point to the pointer on the zero terminated string containing verbose printout of the parsed EF.DG1 data |
| newln | Pointer to the zero terminated string which contains the new line escape sequence for the target system. In the general case it should be "\n" but on some systems can be "\r" or "\r\n". |
| dg1 | Pointer to the buffer containing EF.DG1 content. |
| dg1_len | Length of the EF.DG1 content. |
- Returns
- Operation status
| UFR_STATUS DL_API MRTDValidate |
( |
IN const char * | cert_storage_folder, |
|
|
VAR char ** | out_str, |
|
|
IN const char * | endln, |
|
|
uint32_t | verbose_level, |
|
|
OUT uint8_t | ksenc[16], |
|
|
OUT uint8_t | ksmac[16], |
|
|
VAR uint64_t * | send_sequence_cnt ) |
This function validates data groups read from the eMRTDocument.
All the elements needed for a validation are recorded into the eMRTD and additional CSCA certificate (Country Signing Certificate Authority). During function execution, hash values of the data groups are validated. Data groups hash values have to be the same as those values embedded in the SOD file which is signed by the private key corresponding to the DS certificate. The DS certificate has to be included in the SOD file too. SOD content is a special case of the PKCS#7 ASN.1 DER encoded structure. Finally, DS certificate signature is validated by the external CSCA certificate which is proof of the valid certificates chain of thrust. The countries provided their CSCA certificates on the specialized Internet sites. CSCA certificates can be in PEM (base64 encoded) or binary files (there having extensions such as PEM, DER, CER, CRT…). Some countries have Master List files that include certificates from other countries with which they have bilateral agreements. Those Master List files have an “.ml” file extension. Additionally, the ICAO Public Key Directory (PKD) is a central repository for exchanging the information required to authenticate ePassports. For more details you can visit the ICAO PKD web site.
- Parameters
-
| cert_storage_folder | Pointer to the zero terminated string which should contains path to the folder containing CSCA certificates and/or ICAO Master List files. |
| out_str | After successful function execution, this pointer will point to the pointer on the zero terminated string containing verbose printout of the validation steps. Various printout details are determined by the value of the verbose_level function parameter. |
| endln | Pointer to the zero terminated string which contains the new line escape sequence for the target system. In the general case it should be "\n" but on some systems can be "\r" or "\r\n". |
| verbose_level | One of the values defined in the E_PRINT_VERBOSE_LEVELS enumeration: enum E_PRINT_VERBOSE_LEVELS { PRINT_NONE, PRINT_ESSENTIALS, PRINT_DETAILS, PRINT_ALL_PLUS_STATUSES, }; |
| ksenc | Session encryption key acquired using prior call to MRTDAppSelectAndAuthenticateBac() function. |
| ksmac | Session key for calculating MAC acquired using prior call to MRTDAppSelectAndAuthenticateBac() function.\ |
| send_sequence_cnt | This pointer should point to a 64-bit value initialized by the previously successful call to MRTDAppSelectAndAuthenticateBac() function. Pointer to this 64-bit value should be saved and forwarded at every subsequent call to this function and/or other functions used for reading eMRTD. |
- Returns
- Operation status
