SCF_Card_exchangeAPDU(3SMARTCARD) Smartcard 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 construct-
ing a valid command and providing a receive buffer large enough to hold the reply. Generally, the command and reply will be ISO7816-format-
ted 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.
", replySize);
printf("SW1=0x%02.2x SW2=0x%02.2x
",
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 |
+-----------------------------+-----------------------------+
SEE ALSO
libsmartcard(3LIB), SCF_Card_lock(3SMARTCARD), SCF_Terminal_getCard(3SMARTCARD), attributes(5)
SunOS 5.10 15 May 2002 SCF_Card_exchangeAPDU(3SMARTCARD)