uFCoder 2.62
Loading...
Searching...
No Matches
Machine Readable Travel Documents (MRTD) support

Functions

UFR_STATUS DL_API MRTDAppSelectAndAuthenticateBacM (UFR_HANDLE hndUFR, IN const uint8_t mrz_proto_key[25], OUT uint8_t ksenc[16], OUT uint8_t ksmac[16], VAR uint64_t *send_sequence_cnt)
 Multi reader support. 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 MRTDFileReadBacToHeapM (UFR_HANDLE hndUFR, IN const uint8_t *file_index, 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)
 Multi reader support. 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).
 
UFR_STATUS DL_API MRTDValidateM (UFR_HANDLE hndUFR, 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)
 Multi reader support. 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.
 

Detailed Description

Function Documentation

◆ MRTDAppSelectAndAuthenticateBacM()

UFR_STATUS DL_API MRTDAppSelectAndAuthenticateBacM ( UFR_HANDLE hndUFR,
IN const uint8_t mrz_proto_key[25],
OUT uint8_t ksenc[16],
OUT uint8_t ksmac[16],
VAR uint64_t * send_sequence_cnt )

Multi reader support. 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).

Parameters
hndUFRhandle of the uFR device
mrz_proto_keyMRZ proto-key acquired using prior call to MRTD_MRZDataToMRZProtoKey() or MRTD_MRZSubjacentToMRZProtoKey() function.
ksencThis array must have allocated at least 16 bytes prior to calling this function. This array will contain a session encryption key after successful function execution.
ksmacThis array must have allocated at least 16 bytes prior to calling this function. This array will contain a session key for calculating MAC after successful function execution.
send_sequence_cntAfter successful execution of this function, the pointer to this 64-bit value should be saved and forwarded at every subsequent call to MRTDFileReadBacToHeap() and/or other functions for reading eMRTD.
Returns
Operation status

◆ MRTDFileReadBacToHeapM()

UFR_STATUS DL_API MRTDFileReadBacToHeapM ( UFR_HANDLE hndUFR,
IN const uint8_t * file_index,
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 )

Multi reader support. 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
hndUFRhandle of the uFR device
file_indexfile index
outputbuffer that storese output
output_lengthlength of the returned output
ksencThis array must have allocated at least 16 bytes prior to calling this function. This array will contain a session encryption key after successful function execution.
ksmacThis array must have allocated at least 16 bytes prior to calling this function. This array will contain a session key for calculating MAC after successful function execution.
send_sequence_cntsend_sequence_cnt
Returns
Operation status

◆ MRTDValidateM()

UFR_STATUS DL_API MRTDValidateM ( UFR_HANDLE hndUFR,
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 )

Multi reader support. 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
hndUFRhandle of the uFR device
cert_storage_folderPointer to the zero terminated string which should contains path to the folder containing CSCA certificates and/or ICAO Master List files.
out_strAfter 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.
endlnPointer 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_levelOne 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, };
ksencSession encryption key acquired using prior call to MRTDAppSelectAndAuthenticateBac() function.
ksmacSession key for calculating MAC acquired using prior call to MRTDAppSelectAndAuthenticateBac() function.
send_sequence_cntThis 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