TABLE OF CONTENTS

 

[Modules] calypso_card_session.c

NAME

   SpringCard Calypso API :: Card command set (security and transactions)

COPYRIGHT

AUTHOR

   Johann Dantant / PRO ACTIVE

HISTORY

   JDA 21/10/2008 : first public release
   JDA 04/01/2010 : implemented GetChallenge

[Functions] CalypsoCardCloseSecureSession

NAME

   CalypsoCardCloseSecureSession

DESCRIPTION

   Close a secure session

INPUTS

   CALYPSO_CTX_ST *ctx        : library context
   BOOL           ratify_now  : if set, the session is immediately ratified
   BYTE           sam_sign[4] : the signature provided by the Calypso SAM
   BYTE           resp[]      : buffer to receive the response
   BYTE           *respsize   : input  = size of the response buffer
                                output = actual length of the response
                                         (EXCLUDING the status word that must be 9000)

RETURNS

   CALYPSO_RC                 : 0 or an error code

NOTES

   This function is only a command sent to the card.
   The response is not interpreted by this function. It is up to the caller to
   1. check that the returned content is valid
   2. ask the SAM to verify card's signature
   For an automated implementation, use CalypsoCommitTransaction instead.

[Functions] CalypsoCardGetChallenge

NAME

   CalypsoCardGetChallenge

DESCRIPTION

   Ask the card to generate an 8-byte challenge

INPUTS

   CALYPSO_CTX_ST *ctx          : library context
   BYTE           challenge[8]  : the challenge returned by the card

RETURNS

   CALYPSO_RC                   : 0 or an error code

SEE ALSO

   CalypsoSamGiveRandom

[Functions] CalypsoCardOpenSecureSession1

NAME

   CalypsoCardOpenSecureSession1

DESCRIPTION

   Open a secure session, Revision 1 implementation

INPUTS

   CALYPSO_CTX_ST *ctx         : library context
   BYTE           resp[]       : buffer to receive the response
   CALYPSO_SZ     *respsize    : input  = size of the response buffer
                                 output = actual length of the response
                                          (EXCLUDING the status word that must be 9000)
   BYTE           key_no       : identifier of the cryptographic key
   BYTE           sfi          : identifier of the file to read (0 for current file)
   BYTE           rec_no       : identifier of the record to read (0 for none)
   const BYTE     sam_chal[4]  : challenge returned by the SAM (see CalypsoSamGetChallenge)
   BYTE           card_chal[4] : buffer to receive card's challenge
   BOOL           *ratified    : tells whether last card session was ratified or not
   BYTE           data[]       : buffer to receive record data (if some)
   CALYPSO_SZ     *datasize    : input  = size of the record data buffer
                                 output = actual length of record data

RETURNS

   CALYPSO_RC                  : 0 or an error code

[Functions] CalypsoCardOpenSecureSession2

NAME

   CalypsoCardOpenSecureSession2

DESCRIPTION

   Open a secure session, Revision 2 implementation

INPUTS

   CALYPSO_CTX_ST *ctx         : library context
   BYTE           resp[]       : buffer to receive the response
   CALYPSO_SZ     *respsize    : input  = size of the response buffer
                                 output = actual length of the response
                                          (EXCLUDING the status word that must be 9000)
   BYTE           key_no       : identifier of the cryptographic key
   BYTE           sfi          : identifier of the file to read (0 for current file)
   BYTE           rec_no       : identifier of the record to read (0 for none)
   const BYTE     sam_chal[4]  : challenge returned by the SAM (see CalypsoSamGetChallenge)
   BYTE           card_chal[4] : buffer to receive card's challenge
   BOOL           *ratified    : tells whether last card session was ratified or not
   BYTE           data[]       : buffer to receive record data (if some)
   CALYPSO_SZ     *datasize    : input  = size of the record data buffer
                                 output = actual length of record data
   BYTE           *kvc         : KVC specified by the card according to key_no

RETURNS

   CALYPSO_RC                  : 0 or an error code

[Functions] CalypsoCardOpenSecureSession3

NAME

   CalypsoCardOpenSecureSession3

DESCRIPTION

   Open a secure session, Revision 3 implementation

INPUTS

   CALYPSO_CTX_ST *ctx         : library context
   BYTE           resp[]       : buffer to receive the response
   CALYPSO_SZ     *respsize    : input  = size of the response buffer
                                 output = actual length of the response
                                          (EXCLUDING the status word that must be 9000)
   BYTE           key_no       : identifier of the cryptographic key
   BYTE           sfi          : identifier of the file to read (0 for current file)
   BYTE           rec_no       : identifier of the record to read (0 for none)
   const BYTE     sam_chal[4]  : challenge returned by the SAM (see CalypsoSamGetChallenge)
   BYTE           card_chal[4] : buffer to receive card's challenge
   BOOL           *ratified    : tells whether last card session was ratified or not
   BYTE           data[]       : buffer to receive record data (if some)
   CALYPSO_SZ     *datasize    : input  = size of the record data buffer
                                 output = actual length of record data
   BYTE           *kvc         : KVC specified by the card according to key_no
   BYTE           *kif         : KIF specified by the card according to key_no

RETURNS

   CALYPSO_RC                  : 0 or an error code

[Functions] CalypsoCardOpenSecureSessionEx

NAME

   CalypsoCardOpenSecureSessionEx

DESCRIPTION

   Open a secure session on the card, with user-defined parameters

INPUTS

   CALYPSO_CTX_ST *ctx        : library context
   BYTE           apdu_p1     : the P1 parameter
   BYTE           apdu_p2     : the P2 parameter
   BYTE           sam_chal[4] : the challenge provided by the Calypso SAM
                                     (see CalypsoSamSelectDiversifier)
   BYTE           resp[]      : buffer to receive the response
   BYTE           *respsize   : input  = size of the response buffer
                                    output = actual length of the response
                                             (EXCLUDING the status word that must be 9000)

RETURNS

   CALYPSO_RC                 : 0 or an error code

NOTES

   This function is only a command sent to the card.
   The response is not interpreted by this function. It is up to the caller to
   1. check that the returned content is valid
   2. feed the SAM with card's challenge
   3. use CalypsoSamDigestUpdate to feed the SAM with future exchanges
   For an automated implementation, use CalypsoStartTransaction instead.

[Functions] CalypsoCardSendRatificationFrame

NAME

   CalypsoCardSendRatificationFrame

DESCRIPTION

   Ask card to compute a challenge, specifying an invalid length
   (1 byte instead of 4). This command is used to ratify the session
   in a card not implementing the 'ratify on deselect' feature

INPUTS

   CALYPSO_CTX_ST *ctx : library context

RETURNS

   CALYPSO_RC          : 0 or an error code

Generated from calypso_card_session.c on Mon Jan 30 14:25:35 2012