 |
uFCoder 2.58
|
|
uFCoder 2.58
|
Functions | |
| 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) |
| 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) |
| 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) |
| 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]) |
| UFR_STATUS DL_API | MRTDParseDG1ToHeap (VAR char **sbuffer, IN const char *newln, IN const uint8_t *dg1, uint8_t dg1_len) |
| 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) |
| UFR_STATUS DL_API | MRTDGetImageFromDG2ToFile (IN const uint8_t *dg2, uint32_t dg2_size, IN const char *file_name_without_extension) |
| uint32_t DL_API | MRTDGetDgIndex (uint8_t dg_tag) |
| 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) |
| c_string DL_API | MRTDGetDgName (uint8_t dg_tag) |
| 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).
| 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 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).
| 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. |
| 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.
| 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. |
| 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. After successful function execution MRZ Proto Key will be stored in a mrz_proto_key 25-byte array.
| doc_number | Pointer to a null terminated string containing exactly 9 characters document number. |
| date_of_birth | Pointer to a null terminated string containing exactly 6 characters representing the date of birth in the “YYMMDD” format. |
| date_of_expiry | Pointer to a null terminated string containing exactly 6 characters representing expiration date in the “YYMMDD” format. |
| mrz_proto_key | This byte array will contain a calculated MRZ proto-key after successful function execution. This array must have allocated at least 25 bytes prior to calling this function. |
| 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).
| 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. |
| 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. This function receives EF.DG2 content through *dg2 parameter, parse it and searches for facial image data. Pointer *image points to facial image data within *dg2 memory buffer, after successful function execution.
| dg2 | Pointer to the buffer containing EF.DG2 content. |
| dg2_size | Length of the EF.DG2 content. |
| image | After successful function execution, this pointer will point to the pointer on the image data which is physically located in the dg2 buffer. |
| image_size | After successful function execution, the variable on which this pointer points to, will contain image data length. |
| img_type | After successful function execution, the variable on which this pointer points to, will contain image type. Image type can be one of the values defined in the E_MRTD_IMG_TYPE enumeration: enum E_MRTD_IMG_TYPE { MRTD_IMG_JPEG = 0, MRTD_IMG_JP2 = 1, MRTD_IMG_JPEG2000 = 1, // Alias for the MRTD_IMG_JP2 |
| 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. This function receives EF.DG2 content through *dg2 parameter, parse it and searches for facial image data. After successful function execution, file with path and name specified with an file_name_without_extension parameter is saved. File extension is determined automatically according to the image type.
| dg2 | Pointer to the buffer containing EF.DG2 content. |
| dg2_size | Length of the EF.DG2 content. |
| file_name_without_extension | Pointer to the zero terminated string containing file path and name without an extension which is automatically determined according to the image type. |
| 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.
| dg_tag | Data Group tag: * tag of the EF.COM is 0x60 * tag of the EF.DG1 is 0x61 * tag of the EF.DG2 is 0x75 * tag of the EF.DG3 is 0x63 * tag of the EF.DG4 is 0x76 * tag of the EF.DG5 is 0x65 * tag of the EF.DG6 is 0x66 * tag of the EF.DG7 is 0x67 * tag of the EF.DG8 is 0x68 * tag of the EF.DG9 is 0x69 * tag of the EF.DG10 is 0x6a * tag of the EF.DG11 is 0x6b * tag of the EF.DG12 is 0x6c * tag of the EF.DG13 is 0x6d * tag of the EF.DG14 is 0x6e * tag of the EF.DG15 is 0x6f * tag of the EF.DG16 is 0x70 * tag of the EF.SOD is 0x77 |
| 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 ) |
Multi reader support.
| com | Pointer to the buffer containing EF.COM content. |
| com_len | Length of the EF.COM content. |
| dg_list | After the successful call to this function, this pointer will point to the pointer on the dg_list. |
| dg_list_cnt | After successful function execution, this pointer will point to the variable containing the size of the dg_list in bytes i.e. data groups count. |
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”.
| dg_tag | Data Group tag: * tag of the EF.COM is 0x60 * tag of the EF.DG1 is 0x61 * tag of the EF.DG2 is 0x75 * tag of the EF.DG3 is 0x63 * tag of the EF.DG4 is 0x76 * tag of the EF.DG5 is 0x65 * tag of the EF.DG6 is 0x66 * tag of the EF.DG7 is 0x67 * tag of the EF.DG8 is 0x68 * tag of the EF.DG9 is 0x69 * tag of the EF.DG10 is 0x6a * tag of the EF.DG11 is 0x6b * tag of the EF.DG12 is 0x6c * tag of the EF.DG13 is 0x6d * tag of the EF.DG14 is 0x6e * tag of the EF.DG15 is 0x6f * tag of the EF.DG16 is 0x70 * tag of the EF.SOD is 0x77 |
1.10.0