uFCoder 2.62
|
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. | |
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).
hndUFR | handle of the uFR device |
mrz_proto_key | MRZ proto-key acquired using prior call to MRTD_MRZDataToMRZProtoKey() or MRTD_MRZSubjacentToMRZProtoKey() function. |
ksenc | This 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. |
ksmac | This 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_cnt | After 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. |
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).
hndUFR | handle of the uFR device |
file_index | file index |
output | buffer that storese output |
output_length | length of the returned output |
ksenc | This 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. |
ksmac | This 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_cnt | send_sequence_cnt |
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.
hndUFR | handle of the uFR device |
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. |