TABLE OF CONTENTS

 

[Modules] CalypsoSam

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.

[Functions] SPROX_CalypsoSam_Connect

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

[Functions] SPROX_CalypsoSam_DigestAuthenticate

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

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

[Functions] SPROX_CalypsoSam_DigestInit

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

[Functions] SPROX_CalypsoSam_DigestInit_Old

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

[Functions] SPROX_CalypsoSam_Disconnect

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

[Functions] SPROX_CalypsoSam_Exchange

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

[Functions] SPROX_CalypsoSam_GetChallenge

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

[Functions] SPROX_CalypsoSam_Select

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
   ...

[Functions] SPROX_CalypsoSam_SelectDiversifier

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

Generated from sprox_calypso_sam.c on Mon Aug 18 16:38:26 2014