SCF_Card_exchangeAPDU(3SMASmartcard Library FSCF_Card_exchangeAPDU(3SMARTCARD)NAMESCF_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 transac‐
tion. 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 │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOlibsmartcard(3LIB), SCF_Card_lock(3SMARTCARD), SCF_Terminal_get‐
Card(3SMARTCARD), attributes(5)SunOS 5.10 15 May 2002SCF_Card_exchangeAPDU(3SMARTCARD)
