ID Chip Reader
Macros | Functions
bac_application.h File Reference

Header file for Basic Access Control (BAC) application functions. More...

#include "config.h"

Go to the source code of this file.

Macros

#define ACCESS_BAC_APPLICATION_H_
 

Functions

void KeySeedCalculate (unsigned char mrzInformation[], unsigned char mrzKeySeed[16])
 Calculate Key Seed for generating Session Key. More...
 
void SessionKeyGenerate (unsigned char keySeed[16], unsigned char encryptKeyBuf[16], unsigned char macKeyBuf[16])
 Generate Session Key from Key Seed. More...
 
long InitReader (void)
 Find, connect and start session on reader. More...
 
long SelectApplication (void)
 Select Application for Basic Access Control. More...
 
long GetChallenge (unsigned char getChallengeResponse[10], int getChallengeResponseSize)
 Get Challenge for Basic Access Control. More...
 
long ExternalAuthenticate (unsigned char getChallengeResponse[10], unsigned char encryptKey[16], unsigned char macKey[16], unsigned char sessionKeyEncrypt[16], unsigned char sessionKeyMac[16], unsigned char sendSequenceCounter[8])
 Performs the EXTERNAL AUTHENTICATE operation with the smart card. More...
 
long ReadEFCOM (unsigned char sessionKeyEncrypt[16], unsigned char sessionKeyMac[16], unsigned char sendSequenceCounter[8])
 
long ReadDG1 (unsigned char sessionKeyEncrypt[16], unsigned char sessionKeyMac[16], unsigned char sendSequenceCounter[8])
 Read DG1.COM to get basic holder's information. More...
 
long ReadDG2 (unsigned char sessionKeyEncrypt[16], unsigned char sessionKeyMac[16], unsigned char sendSequenceCounter[8], unsigned char imageFilePath[])
 Read DG2.COM to get holder's image. More...
 
long ReadDG13 (unsigned char sessionKeyEncrypt[16], unsigned char sessionKeyMac[16], unsigned char sendSequenceCounter[8])
 

Detailed Description

Header file for Basic Access Control (BAC) application functions.

Author
Khoa Nguyen

This header file contains function declarations for performing Basic Access Control (BAC) operations on a smart card, such as selecting applications, getting challenges, and reading data groups.

Macro Definition Documentation

◆ ACCESS_BAC_APPLICATION_H_

#define ACCESS_BAC_APPLICATION_H_

Function Documentation

◆ ExternalAuthenticate()

long ExternalAuthenticate ( unsigned char  getChallengeResponse[10],
unsigned char  encryptKey[16],
unsigned char  macKey[16],
unsigned char  sessionKeyEncrypt[16],
unsigned char  sessionKeyMac[16],
unsigned char  sendSequenceCounter[8] 
)

Performs the EXTERNAL AUTHENTICATE operation with the smart card.

This function sends an EXTERNAL AUTHENTICATE command to the smart card, which is used for mutual authentication between the card and the application. It computes necessary data, encrypts and decrypts information, verifies received data, and generates session keys (KS_Enc and KS_MAC) as well as the Send Sequence Counter (SSC).

Parameters
[in]getChallengeResponsePointer to a 10-byte array containing the response from a previous GET CHALLENGE command.
[in]encryptKeyPointer to a 16-byte array containing the encryption key (K_Enc).
[in]macKeyPointer to a 16-byte array containing the MAC key (K_MAC).
[out]sessionKeyEncryptPointer to a 16-byte array where the generated encryption session key (KS_Enc) will be stored.
[out]sessionKeyMacPointer to a 16-byte array where the generated MAC session key (KS_MAC) will be stored.
[out]sendSequenceCounterPointer to an 8-byte array where the initialized Send Sequence Counter (SSC) will be stored.
Returns
A long value representing the status code. APP_SUCCESS indicates successful reading, otherwise an error code is returned.

◆ GetChallenge()

long GetChallenge ( unsigned char  getChallengeResponse[10],
int  getChallengeResponseSize 
)

Get Challenge for Basic Access Control.

Requests a challenge from the smart card for BAC authentication. Returns a status code indicating success or failure in getting the challenge *

Parameters
[out]getChallengeResponseThe received challenge as an array of 10 unsigned chars.
[in]getChallengeof getChallengeResponse array (should be 10).
Returns
A long value representing the status code. APP_SUCCESS indicates successful retrieval, otherwise an error code is returned.

◆ InitReader()

long InitReader ( void  )

Find, connect and start session on reader.

Initializes the reader by finding it, connecting to it, and starting a session. Returns a status code indicating success or failure in initializing the reader.

Returns
A long value representing the status code. APP_SUCCESS indicates successful initialization, otherwise an error code is returned.

◆ KeySeedCalculate()

void KeySeedCalculate ( unsigned char  mrzInformation[],
unsigned char  mrzKeySeed[16] 
)

Calculate Key Seed for generating Session Key.

Given MRZ information, this function calculates the key seed used to generate the session key.

Parameters
[in]mrzInformationThe MRZ information as an array of unsigned chars.
[out]mrzKeySeedThe calculated key seed as an array of 16 unsigned chars.

◆ ReadDG1()

long ReadDG1 ( unsigned char  sessionKeyEncrypt[16],
unsigned char  sessionKeyMac[16],
unsigned char  sendSequenceCounter[8] 
)

Read DG1.COM to get basic holder's information.

Reads the DG1 data group from the smart card, which contains basic information about the holder.

Parameters
[in]sessionKeyEncryptThe session encryption key as an array of 16 unsigned chars for secure messaging.
[in]sessionKeyMacThe session MAC key as an array of 16 unsigned chars for secure messaging.
[in,out]sendSequenceCounterThe send sequence counter as an array of 8 unsigned chars for secure messaging, updated after each command/response exchange with the smart card.
Returns
A long value representing the status code. APP_SUCCESS indicates successful reading, otherwise an error code is returned.

◆ ReadDG13()

long ReadDG13 ( unsigned char  sessionKeyEncrypt[16],
unsigned char  sessionKeyMac[16],
unsigned char  sendSequenceCounter[8] 
)

◆ ReadDG2()

long ReadDG2 ( unsigned char  sessionKeyEncrypt[16],
unsigned char  sessionKeyMac[16],
unsigned char  sendSequenceCounter[8],
unsigned char  imageFilePath[] 
)

Read DG2.COM to get holder's image.

Reads the DG2 data group from the smart card, which contains the holder's image (in JPEG format). Saves the retrieved image as a JPEG file in the imageFilePath.

Parameters
[in]sessionKeyEncryptThe session encryption key as an array of 16 unsigned chars for secure messaging.
[in]sessionKeyMacThe session MAC key as an array of 16 unsigned chars for secure messaging.
[in,out]sendSequenceCounterThe send sequence counter as an array of 8 unsigned chars for secure messaging, updated after each command/response exchange with the smart card.
[in]imageFilePathThe path to the image file to be saved.
Returns
A long value representing the status code. APP_SUCCESS indicates successful reading and saving of the image, otherwise an error code is returned.

◆ ReadEFCOM()

long ReadEFCOM ( unsigned char  sessionKeyEncrypt[16],
unsigned char  sessionKeyMac[16],
unsigned char  sendSequenceCounter[8] 
)

◆ SelectApplication()

long SelectApplication ( void  )

Select Application for Basic Access Control.

Sends a command to select the BAC application on the smart card. Returns a status code indicating success or failure in selecting the application.

Returns
A long value representing the status code. APP_SUCCESS indicates successful selection, otherwise an error code is returned.

◆ SessionKeyGenerate()

void SessionKeyGenerate ( unsigned char  keySeed[16],
unsigned char  encryptKeyBuf[16],
unsigned char  macKeyBuf[16] 
)

Generate Session Key from Key Seed.

Given a key seed, this function generates the session encryption and MAC keys.

Parameters
[in]keySeedThe key seed as an array of 16 unsigned chars.
[out]encryptKeyBufThe generated session encryption key as an array of 16 unsigned chars.
[out]macKeyBufThe generated session MAC key as an array of 16 unsigned chars.