TABLE OF CONTENTS

 

[Modules] CalypsoCard

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.

[Functions] SPROX_Calypso_CloseSecureSession

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

[Functions] SPROX_Calypso_Connect

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

[Functions] 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

[Functions] SPROX_Calypso_Exchange

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

[Functions] SPROX_Calypso_OpenSecureSession

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

[Functions] SPROX_Calypso_Select

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 Mon Aug 18 16:38:26 2014