man pages section 3: Extended Library Functions

SCF_Card_exchangeAPDU(3SMARTCARD)

Name

SCF_Card_exchangeAPDU– send a command APDU to a card and read the card's response

Synopsis

cc [ flag… ] file… -lsmartcard [ library…] 
#include <smartcard/scf.h>

SCF_Status_t SCF_Card_exchangeAPDU(SCF_Card_t card,
     const uint8_t *sendBuffer, size_t sendLength,
     uint8_t *recvBuffer, size_t *recvLength);

Parameters

card: The card (from SCF_Terminal_getCard(3SMARTCARD)) to communicate with.
sendBuffer: A pointer to a buffer containing the command APDU.
sendLength: The number of bytes in the sendBuffer (that is, the size of the command APDU).
recvBuffer: A pointer to a buffer in which the card's reply APDU should be stored. This buffer can be the same as the sendBuffer to allow the application to conserve memory usage. The buffer must be large enough to store the expected reply.
recvLength: The caller specifies the maximum size of the recvBuffer in recvLength. The library uses this value to prevent overflowing the buffer. When the reply is received, the library sets recvLength to the actual size of the reply APDU that was stored in the recvBuffer.

Description

The SCF_Card_exchangeAPDU() function sends a binary command to the card and reads the reply. The application is responsible for constructing a valid command and providing a receive buffer large enough to hold the reply. Generally, the command and reply will be ISO7816-formatted APDUs (Application Protocol Data Units), but the SCF library does not examine or verify the contents of the buffers.

If the caller needs to perform a multi-step transaction that must not be interrupted, SCF_Card_lock(3SMARTCARD) should be used to prevent other applications from communicating with the card during the transaction. Similarly, calls to SCF_Card_exchangeAPDU() must be prepared to retry the call if SCF_STATUS_CARDLOCKED is returned.

An ISO7816-formatted command APDU always begins with a mandatory 4 byte header (CLA, INS, P1, and P2), followed by a variable length body (zero or more bytes). For details on the APDUs supported by a specific card, consult the documentation provided by the card manufacturer or applet vendor.

An ISO7816-formatted reply APDU consists of zero or more bytes of data, followed by a manditory 2 byte status trailer (SW1 and SW2).

Return Values

If the APDU is successfully sent and a reply APDU is successfully read, SCF_STATUS_SUCCESS is returned with recvBuffer and recvLength set appropriately. Otherwise, an error value is returned and both recvBuffer and recvLength remain unaltered.

Errors

The SCF_Card_exchangeAPDU() function will fail if:

SCF_STATUS_BADARGS: Neither sendBuffer, recvBuffer, nor recvLength can be null pointers. The value of recvLength must be at least 2.
SCF_STATUS_BADHANDLE: The card has been closed or is invalid.
SCF_STATUS_CARDLOCKED: The APDU cannot be sent because the card is locked by another application.
SCF_STATUS_CARDREMOVED: The card object cannot be used because the card represented by the SCF_Card_t has been removed
SCF_STATUS_COMMERROR: The connection to the server was closed.
SCF_STATUS_FAILED: An internal error occurred.
SCF_STATUS_NOSPACE: The specified size of recvBuffer is too small to hold the complete reply APDU.

Examples

Example 1 Send a command to the card.

SCF_Status_t status;
SCF_Card_t myCard;
uint8_t commandAPDU[] = {0x00, 0xa4, 0x00, 0x00, 0x02, 0x3f, 0x00};
uint8_t replyAPDU[256];
uint32_t commandSize = sizeof(commandAPDU);
uint32_t replySize = sizeof(replyAPDU);
/* (...call SCF_Terminal_getCard to open myCard...) */
 
/* Send the ISO7816 command to select the card's MF. */
status = SCF_Card_exchangeAPDU(myCard, commandAPDU, commandSize,
    replyAPDU, &replySize);
if (status != SCF_STATUS_SUCCESS) exit(1);
 
printf("Received a %d byte reply.\n", replySize);
printf("SW1=0x%02.2x SW2=0x%02.2x\n",
    replyAPDU[replySize-2], replyAPDU[replySize-1]);
 
/* ... */

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving
MT-Level	MT-Safe