sprox_calypso_card.c
NAME
SpringProxAPI :: Working with Calypso cards (application level)
NOTES
Most parameters of the SPROX_Calypso_xxx functions directly map to Calypso
card internal functions.
Please refer to Calypso official documentation for any details.
NAME
SPROX_Calypso_CloseSecureSession
DESCRIPTION
Close a secure session with the currently active card
SYNOPSYS
SWORD SPROX_Calypso_CloseSecureSession(BYTE sam_mac[4],
BYTE card_mac[4]);
INPUTS
BYTE sam_mac[4] : the message authentication code provided by the Calypso SAM
in answer to SPROX_CalypsoSam_DigestClose
OUTPUTS
BYTE card_mac[4] : card's answer (without the status word)
RETURNS
MI_OK : success
CALYPSO_WRONG_MAC : bad signature (invalid sam_mac)
Other code on any error
NOTES
Error CALYPSO_WRONG_MAC denotes a fatal security error.
Most of the time, this is caused by SAM and card not sharing the same key (p1 and p2
parameters for SPROX_Calypso_OpenSecureSession not matching kif parameter for
SPROX_CalypsoSam_DigestInit, or bad kvc provided to SPROX_CalypsoSam_DigestInit,
or why not card and SAM not coming from the same network).
This can also be caused by an erronous exchange betwen application, card, and SAM
(for example an exchange with the card not correctly forwared to the SAM).
Whatever the reason, transaction is cancelled by the card (and must be cancelled
by application as well).
On success, card_mac shall be passed to SPROX_CalypsoSam_DigestAuthenticate, to check
that the card really knows the key, and isn't cheating.
SEE ALSO
SPROX_Calypso_OpenSecureSession
SPROX_Calypso_Exchange
SPROX_CalypsoSam_DigestAuthenticate
NAME
SPROX_Calypso_Connect
DESCRIPTION
Connect to a Calypso card in the currently select slot
SYNOPSYS
SWORD SPROX_Calypso_Connect(BYTE card_uid[8]);
OUTPUTS
BYTE uid[8] : UID of the found card (if one)
RETURNS
MI_OK : success
Other code on any error
NOTES
This function tries to connect using the slot selected by
SPROX_Calypso_Select.
Contactless Calypso card may answer both to the CALYPSO_ISO14443_SLOT
slot and to the CALYPSO_LEGACYRF_SLOT.
Upper layer software must cope with this and ignore the second answer
in necessary.
SEE ALSO
SPROX_Calypso_Select
SPROX_Calypso_Disconnect
NAME
SPROX_Calypso_Disconnect
DESCRIPTION
Disconnect from the currently active Calypso card
SYNOPSYS
SWORD SPROX_Calypso_Disconnect(void);
RETURNS
MI_OK : success
Other code on any error
SEE ALSO
SPROX_Calypso_Connect
NAME
SPROX_Calypso_Exchange
DESCRIPTION
Exchange an APDU with the currently active Calypso card
SYNOPSYS
SWORD SPROX_Calypso_Exchange(BYTE send_buffer[],
WORD send_length,
BYTE recv_buffer[],
WORD *recv_length);
INPUTS
BYTE send_buffer[] : APDU to be sent to the card
WORD send_length : size of the APDU to be sent
WORD *recv_length : max size for recv_buffer
OUTPUTS
BYTE recv_buffer[] : card's answer
WORD *recv_length : size of card's answer
RETURNS
MI_OK : success
Other code on any error
SIDE EFFECTS
This function implicitly forward exchanged data with the SAM if a
a secure session is active. See SPROX_Calypso_OpenSecureSession
Result of SPROX_Calypso_SW is updated with last status word
SEE ALSO
SPROX_Calypso_Connect
NAME
SPROX_Calypso_OpenSecureSession
DESCRIPTION
Open a secure session on the currently active card
SYNOPSYS
SWORD SPROX_Calypso_OpenSecureSession(BYTE p1,
BYTE p2,
BYTE sam_chal[4],
BYTE card_resp[],
WORD *card_resp_size);
INPUTS
BYTE p1 : the P1 parameter for open secure session command,
as defined in Calypso card's specification
BYTE p2 : the P2 parameter for open secure session command,
as defined in Calypso card's specification
BYTE sam_chal[4] : the challenge provided by the Calypso SAM in answer
to SPROX_CalypsoSam_GetChallenge
WORD *card_resp_length : max size for card_resp_buffer
OUTPUTS
BYTE card_resp_buffer[] : card's answer (without the status word)
WORD *card_resp_length : size of card's answer
RETURNS
MI_OK : success
Other code on any error
SIDE EFFECTS
Once a secure session has been opened, any exchange between card and application
(through SPROX_Calypso_Exchange) are implicitly forwarded to the SAM
SEE ALSO
SPROX_CalypsoSam_DigestInit
SPROX_Calypso_CloseSecureSession
SPROX_Calypso_Exchange
NAME
SPROX_Calypso_Select
DESCRIPTION
Select the smartcard slot for Calypso operation
SYNOPSYS
SWORD SPROX_Calypso_Select(BYTE slot);
INPUTS
BYTE slot : smarcard slot number
RETURNS
MI_OK : success
Other code on any error
NOTES
Slot # 0 to 8 map to contact slots :
0 = main slot (ISO 7816 size)
1 = first SAM slot (micro SIM size)
2 = second SAM slot
...
For contactless operation, choose either
CALYPSO_LEGACYRF_SLOT = Legacy Calypso protocol (Innovatron or type B')
CALYPSO_ISO14443_SLOT = ISO-14443 protocol (type B)
SEE ALSO
CALYPSO_ISO14443_SLOT
CALYPSO_LEGACYRF_SLOT
Generated from
sprox_calypso_card.c on Tue Jan 24 12:33:50 2012
