NAME
SpringProxAPI :: Working with Calypso SAMs
NOTES
Most parameters of the SPROX_CalypsoSam_xxx functions directly map to Calypso SAM internal functions. Please refer to Calypso official documentation for any details.
NAME
SPROX_CalypsoSam_Connect
DESCRIPTION
Connect to a Calypso SAM in the currently select slot SYNOPSYS SWORD SPROX_CalypsoSam_Connect(BYTE atr_buffer[], WORD *atr_length);
INPUTS
WORD *atr_length : max size for atr_buffer OUTPUTS BYTE atr_buffer[] : ATR of the found SAM (if one) WORD *atr_length : size of SAM's ATR
RETURNS
MI_OK : success Other code on any error
SEE ALSO
SPROX_CalypsoSam_Select SPROX_CalypsoSam_Disconnect
NAME
SPROX_CalypsoSam_DigestAuthenticate
DESCRIPTION
Verify the MAC returned by the card after closing the secure session SYNOPSYS SWORD SPROX_CalypsoSam_DigestAuthenticate(BYTE card_mac[4]);
INPUTS
BYTE card_mac[4] : the message authentication code provided by the Calypso card in answer to SPROX_Calypso_CloseSecureSession
RETURNS
MI_OK : success CALYPSO_WRONG_MAC : bad signature (invalid card_mac) Other code on any error
NOTES
Error CALYPSO_WRONG_MAC denotes a fatal security error. As this comes after a successfull call to SPROX_Calypso_CloseSecureSession, the card did accepted our cryptogram, but replied with an invalid one. This must mean that the card has been forged !!!
SEE ALSO
SPROX_Calypso_CloseSecureSession SPROX_CalypsoSam_DigestClose
NAME
SPROX_CalypsoSam_DigestClose
DESCRIPTION
Ask the SAM to generate the certificate to send to the card to close a session SYNOPSYS SWORD SPROX_CalypsoSam_DigestClose(BYTE sam_mac[4]); OUTPUTS BYTE sam_mac[] : MAC computed by the SAM, to be forwarded to the card through SPROX_Calypso_CloseSecureSession
RETURNS
MI_OK : success Other code on any error
SEE ALSO
SPROX_Calypso_CloseSecureSession SPROX_CalypsoSam_DigestOpen
NAME
SPROX_CalypsoSam_DigestInit
DESCRIPTION
Activates a session in the SAM, and initializes its digest SYNOPSYS SWORD SPROX_CalypsoSam_DigestInit(BYTE kif, BYTE kvc, BYTE card_resp_buffer[], WORD card_resp_length);
INPUTS
BYTE kif : key identifier BYTE kvc : key version (as returned by the card in answer to SPROX_Calypso_OpenSecureSession with P1's bit 7 set) BYTE card_resp_buffer[] : card's answer to SPROX_Calypso_OpenSecureSession WORD card_resp_length : size of card's answer
RETURNS
MI_OK : success Other code on any error
SEE ALSO
SPROX_CalypsoSam_DigestInit_Old SPROX_CalypsoSam_GetChallenge SPROX_Calypso_OpenSecureSession SPROX_CalypsoSam_DigestClose
NAME
SPROX_CalypsoSam_DigestInit_Old
DESCRIPTION
Activates a session in the SAM, and initializes its digest, using absolute record number to select the key SYNOPSYS SWORD SPROX_CalypsoSam_DigestInit_Old(BYTE key_record, BYTE card_resp_buffer[], WORD card_resp_length);
INPUTS
BYTE key_record : key record number BYTE card_resp_buffer[] : card's answer to SPROX_Calypso_OpenSecureSession WORD card_resp_length : size of card's answer
RETURNS
MI_OK : success Other code on any error
SEE ALSO
SPROX_CalypsoSam_DigestInit SPROX_CalypsoSam_GetChallenge SPROX_Calypso_OpenSecureSession SPROX_CalypsoSam_DigestClose
NAME
SPROX_CalypsoSam_Disconnect
DESCRIPTION
Disconnect from the currently active Calypso SAM SYNOPSYS SWORD SPROX_CalypsoSam_Disconnect(void);
RETURNS
MI_OK : success Other code on any error
SEE ALSO
SPROX_CalypsoSam_Connect
NAME
SPROX_CalypsoSam_Exchange
DESCRIPTION
Exchange an APDU with the currently active Calypso SAM SYNOPSYS SWORD SPROX_CalypsoSam_Exchange(BYTE send_buffer[], WORD send_length, BYTE recv_buffer[], WORD *recv_length);
INPUTS
BYTE send_buffer[] : APDU to be sent to the SAM WORD send_length : size of the APDU to be sent WORD *recv_length : max size for recv_buffer OUTPUTS BYTE recv_buffer[] : SAM's answer WORD *recv_length : size of SAM's answer
RETURNS
MI_OK : success Other code on any error
SIDE EFFECTS
Result of SPROX_CalypsoSam_SW is updated with last status word
SEE ALSO
SPROX_CalypsoSam_Connect
NAME
SPROX_CalypsoSam_GetChallenge
DESCRIPTION
Ask SAM to create a new nounce in order to open a secure session with a card SYNOPSYS SWORD SPROX_CalypsoSam_GetChallenge(BYTE sam_chal[4]); OUTPUTS BYTE sam_chal[4] : SAM's nounce, to be forwarded to the card in SPROX_Calypso_OpenSecureSession
RETURNS
MI_OK : success Other code on any error
SEE ALSO
SPROX_CalypsoSam_SelectDiversifier_Atr SPROX_Calypso_OpenSecureSession SPROX_CalypsoSam_DigestInit
NAME
SPROX_CalypsoSam_Select
DESCRIPTION
Select the smartcard slot where the Calypso SAM is to be found SYNOPSYS SWORD SPROX_CalypsoSam_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 ...
NAME
SPROX_CalypsoSam_SelectDiversifier
DESCRIPTION
Feed the SAM with current card's UID SYNOPSYS SWORD SPROX_CalypsoSam_SelectDiversifier(BYTE card_uid[8]);
INPUTS
BYTE card_uid[8] : serial number of the Calypso card, as returned by SPROX_Calypso_Connect
RETURNS
MI_OK : success Other code on any error
SEE ALSO
SPROX_CalypsoSam_GetChallenge