Smart Card API: Difference between revisions

Revision as of 08:48, 16 April 2018

Functions

query_max_number and query_presence are independent of open and close .

If the card inserted is a CPU card, the normally calling sequence is: open>power_on>transmit>power_off>close

If the card inserted is a memory card, the normally calling sequence is: open>power_on>mc_verify>mc_read/mc_write>power_off>close

open

int smart_card_open(int nSlotIndex, SMART_CARD_NOTIFIER pNotify, void* pUserData)

Open the specified slot of the smart card reader. This operation should be used before other operations. A notifier is registered after this api is called.

Parameters

nSlotIndex	Slot index, from 0 to MAX - 1
pNotify	Notifier of smart card reader
pUserData	User data

typedef void (*SMART_CARD_NOTIFIER) nEvent:

define SMART_CARD_EVENT_INSERT_CARD 0
define SMART_CARD_EVENT_REMOVE_CARD 1
define SMART_CARD_EVENT_POWER_ON 2
define SMART_CARD_EVENT_POWER_OFF 3

Returns

The result code, >= 0, success,value as handle of this device; <0 error code.

close

 int smart_card_close(int nHandle)

Close the specified slot of the smart card reader which is opened before. The open and close apis are pair operations. If you don’t want to use this device, you should call the close api to release this device. The nSlotIndex of open and close should be all the same.

Parameters

nHandle

Handle of this device, returned from open

Returns

The result code, >= 0, success; <0 error code.

query_max_number

 int smart_card_query_max_number()

Query the max slot in this smart card reader. Normally the IC card slot index is 0, other slots are used for PSAM card.

Parameters

Returns

The result code, > 0, number of slot; = 0, not defined; <0 error code.

query_presence

 int smart_card_query_presence(int nSlotIndex)

Query whether the smart card is existent in the selected slot. Attention: not every slot can support this function. This api can be used before open operation.

Parameters

nSlotIndex

int

Slot index, from 0 to MAX - 1

Returns

The result code, > 0, exist; = 0, not exist; <0 error code.

set_slot_info

 int smart_card_set_slot_info(int nHandle, SMART_CARD_SLOT_INFO* pSlotInfo)

The function set the slot control information.

Parameters

nHandle	int	Handle of this device, returned from open
pSlotInfo	SMART_CARD_SLOT_INFO*	slot information

typedef struct smart_card_slot_info
{
    /** \show initializer Speed communication (parameter TA1 of ISO 7816-3) */
    unsigned char FIDI;

    /** \show initializer Extra Guard Time (parameter TC1 or N of ISO 7816-3) */
    unsigned char EGT;

    /**  \show initializer
     * If protocol T=0 is selected, the parameter indicates the Waiting
     * Integer (parameter TC2 of ISO 7816-3 - the default value is 10)
     * If the protocol T=1 is selected, the parameter indicates the
     * Block and Character Waiting Time Integer (parameter TB3 of ISO 7816-3)
     */
    unsigned char WI;

     /** \show initializer If the protocol T=1 is selected, the parameter indicates the
      * Waiting Time Extention (the default value is 1). */
    unsigned char WTX;

    /** \show initializer If the protocol T=1 is selected, the parameter indicates the computing
     * mode for EDC : HAL_SCS_EDC_LRC or HAL_SCS_EDC_CRC (The default value
     * is an LRC) */
    unsigned char EDC;

    /** \show initializer The parameter indicates the selected protocol :
     *  HAL_SCS_PROTOCOL_T0
     *  HAL_SCS_PROTOCOL_T1 */
    unsigned char protocol;


    /** \show initializer The power supply value :
     *  HAL_SCS_POWER_1_8V
     *  HAL_SCS_POWER_3V
     *  HAL_SCS_POWER_5V
     */
    unsigned char power;

    /** \show initializer Convention used to transfer byte :
     *  HAL_SCS_CONV_DIRECT
     *  HAL_SCS_CONV_INVERSE */
    unsigned char conv;

    /** \show initializer If the protocol T=1 is selected, the parameter indicates the Information
     * Field Size for the Card (parameter TA3 of ISO 7816-3). */
    unsigned char IFSC;
    unsigned char reserved[3];
    /** \show initializer Possibility to set Character Waiting Time */
    unsigned int cwt;
    /** \show initializer Possibility to set Block Waiting Time */
    unsigned int bwt;
    /*
     * OR of these items:
     * 		SMART_CARD_SLOT_INFO_FIDI		(1 << 0)
	 *		SMART_CARD_SLOT_INFO_EGT		(1 << 1)
	 *		SMART_CARD_SLOT_INFO_WI			(1 << 2)
	 *		SMART_CARD_SLOT_INFO_WTX		(1 << 3)
	 *		SMART_CARD_SLOT_INFO_EDC		(1 << 4)
	 *		SMART_CARD_SLOT_INFO_PROTOCOL	(1 << 5)
	 *		SMART_CARD_SLOT_INFO_POWER		(1 << 6)
	 *		SMART_CARD_SLOT_INFO_CONV		(1 << 7)
	 *		SMART_CARD_SLOT_INFO_IFSC		(1 << 8)
	 * 		SMART_CARD_SLOT_INFO_CWT		(1 << 9)
	 *		SMART_CARD_SLOT_INFO_BWT		(1 << 10)
     *
     */
    unsigned int nSlotInfoItem;
}SMART_CARD_SLOT_INFO;

Returns

The result code, >= 0, success; <0 error code.

power_on

 int smart_card_power_on(int nHandle, unsigned char* pATR, unsigned int* pATRLength, SMART_CARD_SLOT_INFO* pSlotInfo)

Power on the smart card in the slot opened before.

Parameters

nHandle	int	Handle of this device, returned from open
pATR	unsigned char*	ATR from IC card
pATRLength	unsigned int*	Length of ATR
pSlotInfo	SMART_CARD_SLOT_INFO*	slot information

Returns

The result code, >= 0, success; <0 error code.

power_off

 int smart_card_power_off(int nHandle)

Power off the smart card in the slot opened before. This api should be used after power_on. Power_on and power_off are pair operations.

Parameters

nHandle

int

Handle of this device, returned from open

Returns

The result code, >= 0, success; <0 error code.

transmit

 int smart_card_transmit(int nHandle, unsigned char* pAPDU, unsigned int nAPDULength, unsigned char* pResponse, unsigned int *pResponseLength)

The function sends a command Application Protocol Data Unit(APDU) to a card and retrieve the response APDU, plus the status words SW1 and SW2. his api should be used between power_on and power_off. If the inserted card is a CPU card, call power_on, transmit, power_off after open.

Parameters

nHandle	int	Handle of this device, returned from open
pAPDU	unsigned char*	Command of APDU
nAPDULength	unsigned int	Length of command
pResponse	unsigned char*	Card response of APDU command
pResponseLength	unsigned int	Length of response

Returns

The result code, >= 0, success; <0 error code.

mc_verify

 int smart_card_mc_verify_data(int nHandle, unsigned char* pData, unsigned int nDataLength)

If the inserted card is a memory card, verify its password.

Parameters

nHandle	int	Handle of this device, returned from open
pData	unsigned char*	Key data
nDataLength	unsigned int	Length of key

Returns

The result code, >= 0, success; <0 error code.

mc_read

 int smart_card_mc_read(int nHandle, unsigned int nAreaType, unsigned char* pDataBuffer, unsigned int nDataLength, unsigned char cStartAddress)

The function is responsible for reading memory card information.

Parameters

nHandle	int	Handle of this device, returned from open
nAreaType	unsigned int	Area type: 0--main memory,1--protected memory,2--security momory
pDataBuffer	unsigned char*	Data buffer
nDataLength	unsigned int	Data length of expecting reading
cStartAddress	unsigned char	Starting address to read

Returns

The result code, >= 0, success; <0 error code.

mc_write

 int smart_card_mc_write(int nHandle, unsigned int nAreaType, unsigned char* pData, unsigned int nDataLength, unsigned char cStartAddress)

The function is responsible for writing data to memory card. The mc_read and mc_write APIs are used after mc_verify. If the inserted card is a memory card, call mc_verify, mc_read, mc_writeafter open

Parameters

nHandle	int	Handle of this device, returned from open
nAreaType	unsigned int	Area type: 0--main memory,1--protected memory,2--security momory
pData	unsigned char*	Data buffer
nDataLength	unsigned int	Data length of expecting writing
cStartAddress	unsigned char	Starting address to write

Returns

The result code, >= 0, success; <0 error code.