 |
|
|
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); |
| |
-
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.
|
| |
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).
|
| |
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.
|
| |
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.
|
| | 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]);
/* ... */
|
|
|
| |
See attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| Interface Stability | Evolving |
| MT-Level | MT-Safe |
|
Company Info
|
Contact
|
Copyright 2003 Sun Microsystems, Inc. All rights reserved.
Use is subject to license terms.
|
