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