TABLE OF CONTENTS

 

[Modules] ISO

NAME

   DesfireAPI :: ISO 7816-4 functions

COPYRIGHT

DESCRIPTION

   Implementation of DESFIRE ISO 7816-4 compliant functions.

[Functions] IsoAppendRecord

NAME

   IsoAppendRecord

DESCRIPTION

   Implementation of ISO 7816-4 APPEND RECORD command in Desfire EV1 flavour

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_IsoAppendRecord(const BYTE abData[],
                                       BYTE bLength,
                                       WORD *SW);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_IsoAppendRecord(SPROX_INSTANCE rInst,
                                        const BYTE abData[],
                                        BYTE bLength,
                                        WORD *SW);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_IsoAppendRecord(SCARDHANDLE hCard,
                                      const BYTE abData[],
                                      BYTE bLength,
                                      WORD *SW);

INPUTS

   const BYTE abData[] : buffer containing the data to write
   BYTE bLength        : size of data to be written in bytes
   WORD *SW            : optional pointer to retrieve the Status Word in
                         case an error occurs

RETURNS

   DF_OPERATION_OK     : success
   Other code if internal or communication error has occured. 

SEE ALSO

   IsoReadRecord

[Functions] IsoExternalAuthenticate

NAME

   IsoExternalAuthenticate

DESCRIPTION

   Implementation of ISO 7816-4 EXTERNAL AUTHENTICATE command in Desfire EV1 flavour

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_IsoExternalAuthenticate(BYTE bKeyAlgorithm,
                                               BYTE bKeyReference,
                                               BYTE bRndSize,
                                               const BYTE abRndCard1[],
                                               const BYTE abRndHost1[],
                                               const BYTE abKeyValue[],
                                               WORD *SW);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_IsoExternalAuthenticate(SPROX_INSTANCE rInst,
                                                BYTE bKeyAlgorithm,
                                                BYTE bKeyReference,
                                                BYTE bRndSize,
                                                const BYTE abRndCard1[],
                                                const BYTE abRndHost1[],
                                                const BYTE abKeyValue[],
                                                WORD *SW);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_IsoExternalAuthenticate(SCARDHANDLE hCard,
                                              BYTE bKeyAlgorithm,
                                              BYTE bKeyReference,
                                              BYTE bRndSize,
                                              const BYTE abRndCard1[],
                                              const BYTE abRndHost1[],
                                              const BYTE abKeyValue[],
                                              WORD *SW);

INPUTS

   BYTE bKeyAlgorithm         : algorithm to be used:
                                - 0x02 : DES or 3DES2K (16-byte key)
                                - 0x04 : 3DES3K (24-byte key)
                                - 0x09 : AES (16-byte key)
   BYTE bKeyReference         : reference to the key in the card
                                - 0x00 : card's master key (valid only on root application)
                                - 0x8n : application's key #n 
   BYTE bRndSize              : size of the challenge
                                (8 bytes for DES/3DES2K, 16 bytes for 3DES3K or AES)
   const BYTE abRndCard1[]    : card's first challenge (as returned by IsoGetChallenge - not involved in session key)
   const BYTE abRndHost1[]    : host's first challenge (choosen by the caller - involved in session key)
   const BYTE abKeyValue [16] : the key itself
   WORD *SW                   : optional pointer to retrieve the Status Word in
                                case an error occurs

RETURNS

   DF_OPERATION_OK    : success
   Other code if internal or communication error has occured. 

SEE ALSO

   IsoMutualAuthenticate
   IsoGetChallenge
   IsoInternalAuthenticate

[Functions] IsoGetChallenge

NAME

   IsoGetChallenge

DESCRIPTION

   Implementation of ISO 7816-4 GET CHALLENGE command in Desfire EV1 flavour

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_IsoGetChallenge(BYTE bKeyAlgorithm,
                                       BYTE bRndSize,
                                       BYTE abRndCard1[],
                                       WORD *SW);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_IsoGetChallenge(SPROX_INSTANCE rInst,
                                        BYTE bRndSize,
                                        BYTE abRndCard1[],
                                        WORD *SW);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_IsoGetChallenge(SCARDHANDLE hCard,
                                      BYTE bRndSize,
                                      BYTE abRndCard1[],
                                      WORD *SW);

INPUTS

   BYTE bRndSize              : size of the challenge
                                (8 bytes for DES/3DES2K, 16 bytes for 3DES3K or AES)
   BYTE abRndCard1[]          : card's first challenge (not involved in session key)
   WORD *SW                   : optional pointer to retrieve the Status Word in
                                case an error occurs

RETURNS

   DF_OPERATION_OK    : success
   Other code if internal or communication error has occured. 

SEE ALSO

   IsoMutualAuthenticate
   IsoExternalAuthenticate
   IsoInternalAuthenticate

[Functions] IsoInternalAuthenticate

NAME

   IsoInternalAuthenticate

DESCRIPTION

   Implementation of ISO 7816-4 INTERNAL AUTHENTICATE command in Desfire EV1 flavour

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_IsoInternalAuthenticate(BYTE bKeyAlgorithm,
                                               BYTE bKeyReference,
                                               BYTE bRndSize,
                                               const BYTE abRndHost2[],
                                               BYTE abRndCard2[],
                                               const BYTE abKeyValue[],
                                               WORD *SW);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_IsoInternalAuthenticate(SPROX_INSTANCE rInst,
                                                BYTE bKeyAlgorithm,
                                                BYTE bKeyReference,
                                                BYTE bRndSize,
                                                const BYTE abRndHost2[],
                                                BYTE abRndCard2[],
                                                const BYTE abKeyValue[],
                                                WORD *SW);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_IsoInternalAuthenticate(SCARDHANDLE hCard,
                                              BYTE bKeyAlgorithm,
                                              BYTE bKeyReference,
                                              BYTE bRndSize,
                                              const BYTE abRndHost2[],
                                              BYTE abRndCard2[],
                                              const BYTE abKeyValue[],
                                              WORD *SW);

INPUTS

   BYTE bKeyAlgorithm         : algorithm to be used:
                                - 0x02 : DES or 3DES2K (16-byte key)
                                - 0x04 : 3DES3K (24-byte key)
                                - 0x09 : AES (16-byte key)
   BYTE bKeyReference         : reference to the key in the card
                                - 0x00 : card's master key (valid only on root application)
                                - 0x8n : application's key #n 
   BYTE bRndSize              : size of the challenge
                                (8 bytes for DES/3DES2K, 16 bytes for 3DES3K or AES)
   const BYTE abRndHost2[]    : host's second challenge (choosen by the caller - not involved in session key)
   BYTE abRndCard2[]          : card's second challenge (choosen by the card - involved in session key)
   const BYTE abKeyValue [16] : the key itself
   WORD *SW                   : optional pointer to retrieve the Status Word in
                                case an error occurs

RETURNS

   DF_OPERATION_OK    : success
   Other code if internal or communication error has occured. 

SEE ALSO

   IsoMutualAuthenticate
   IsoGetChallenge
   IsoExternalAuthenticate

[Functions] IsoMutualAuthenticate

NAME

   IsoMutualAuthenticate

DESCRIPTION

   Perform a mutual-authentication using the Desfire ISO 7816-4 commands (IsoGetChallenge,
   IsoExternalAuthenticate, IsoInternalAuthenticate) using the specified key value.
   Depending on bKeyAlgorithm, the key is either DES/3DES2K (16 bytes), AES (16 bytes)
   or 3DES3K (24 bytes).
   The generated session key is afterwards used for ISO CMACing.

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_IsoMutualAuthenticate(BYTE bKeyAlgorithm,
                                             BYTE bKeyReference,
                                             const BYTE abKeyValue[],
                                             WORD *SW);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_IsoMutualAuthenticate(SPROX_INSTANCE rInst,
                                              BYTE bKeyAlgorithm,
                                              BYTE bKeyReference,
                                              const BYTE abKeyValue[],
                                              WORD *SW);
   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_IsoMutualAuthenticate(SCARDHANDLE hCard,
                                            BYTE bKeyAlgorithm,
                                            BYTE bKeyReference,
                                            const BYTE abKeyValue[],
                                            WORD *SW);

INPUTS

   BYTE bKeyAlgorithm         : algorithm to be used:
                                - 0x02 : DES or 3DES2K (16-byte key)
                                - 0x04 : 3DES3K (24-byte key)
                                - 0x09 : AES (16-byte key)
   BYTE bKeyReference         : reference to the key in the card
                                - 0x00 : card's master key (valid only on root application)
                                - 0x8n : application's key #n 
   const BYTE abKeyValue [16] : the key itself
   WORD *SW                   : optional pointer to retrieve the Status Word in
                                case an error occurs

RETURNS

   DF_OPERATION_OK    : authentication succeed
   Other code if internal or communication error has occured. 

SEE ALSO

   Authenticate
   AuthenticateAes
   AuthenticateIso24
   AuthenticateIso
   IsoGetChallenge
   IsoExternalAuthenticate
   IsoInternalAuthenticate

[Functions] IsoReadBinary

NAME

   IsoReadBinary

DESCRIPTION

   Implementation of ISO 7816-4 READ BINARY command in Desfire EV1 flavour

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_IsoReadBinary(WORD wOffset,
                                     BYTE abData[],
                                     BYTE bWantLength,
                                     WORD *wGotLength,
                                     WORD *SW);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_IsoReadBinary(SPROX_INSTANCE rInst,
                                      WORD wOffset,
                                      BYTE abData[],
                                      BYTE bWantLength,
                                      WORD *wGotLength,
                                      WORD *SW);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_IsoReadBinary(SCARDHANDLE hCard,
                                    WORD wOffset,
                                    BYTE abData[],
                                    BYTE bWantLength,
                                    WORD *wGotLength,
                                    WORD *SW);

INPUTS

   WORD wOffset      : starting position for the read operation
   BYTE abData[]     : buffer to receive the data
   BYTE bWantLength  : maximum data length to read. Set to 0 to read 256 bytes.
   WORD *wGotLength  : actual data length read
   WORD *SW          : optional pointer to retrieve the Status Word in
                       case an error occurs

RETURNS

   DF_OPERATION_OK   : success
   Other code if internal or communication error has occured. 

NOTES

   After a successfull authentication, a CMAC is added to card's response.
   The value of bWantLength must be choosen in consequence.
   This command checks the value of the CMAC in card's response and removes
   it from the data buffer.

SEE ALSO

   IsoUpdateBinary
   IsoReadRecord

[Functions] IsoReadRecord

NAME

   IsoReadRecord

DESCRIPTION

   Implementation of ISO 7816-4 READ RECORD command in Desfire EV1 flavour

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_IsoReadRecord(BYTE bRecNum,
                                     BOOL fReadAll;
                                     BOOL abData[],
                                     WORD wMaxLength,
                                     WORD *wGotLength,
                                     WORD *SW);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_IsoReadRecord(SPROX_INSTANCE rInst,
                                      BYTE bRecNum,
                                      BOOL fReadAll;
                                      BOOL abData[],
                                      WORD wMaxLength,
                                      WORD *wGotLength,
                                      WORD *SW);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_IsoReadRecord(SCARDHANDLE hCard,
                                    BYTE bRecNum,
                                    BOOL fReadAll;
                                    BOOL abData[],
                                    WORD wMaxLength,
                                    WORD *wGotLength,
                                    WORD *SW);

INPUTS

   BYTE bRecNum      : first (or only) record to read
   BOOL fReadAll     : TRUE  : read all records (starting from bRecNum)
                       FALSE : read only record # bRecNum
   BYTE abData[]     : buffer to receive the data
   WORD wMaxLength   : size of the buffer
   WORD *wGotLength  : actual data length read
   WORD *SW          : optional pointer to retrieve the Status Word in
                       case an error occurs

RETURNS

   DF_OPERATION_OK   : success
   Other code if internal or communication error has occured. 

NOTES

   After a successfull authentication, a CMAC is added to card's response.
   This command checks the value of the CMAC in card's response and removes
   it from the data buffer.

SEE ALSO

   IsoAppendRecord
   IsoReadBinary

[Functions] IsoSelectApplet

NAME

   IsoSelectApplet

DESCRIPTION

   Send the ISO 7816-4 SELECT FILE command with the DESFIRE applet name as parameter
   (P2 = 0x04, DataIn = 0xD2, 0x76, 0x00, 0x00, 0x85, 0x01, 0x00 )

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_IsoSelectApplet(WORD *SW);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_IsoSelectApplet(SPROX_INSTANCE rInst, 
                                        WORD *SW);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_IsoSelectApplet(SCARDHANDLE hCard,
                                      WORD *SW);

INPUTS

   WORD *SW            : optional pointer to retrieve the Status Word in
                         case an error occurs

RETURNS

   DF_OPERATION_OK   : success
   Other code if internal or communication error has occured. 

 SIDE EFFECT
   Wrapping mode is implicitly defined to DF_ISO_WRAPPING_CARD

[Functions] IsoSelectDF

NAME

   IsoSelectDF

DESCRIPTION

   Implementation of ISO 7816-4 SELECT FILE command using a Directory File ID (P2=0x02)

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_IsoSelectDF(WORD wFileID,
                                   BYTE abFci[],
                                   WORD wMaxFciLength,
                                   WORD *wGotFciLength,
                                   WORD *SW);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_IsoSelectDF(SPROX_INSTANCE rInst, 
                                    WORD wFileID,
                                    BYTE abFci[],
                                    WORD wMaxFciLength,
                                    WORD *wGotFciLength,
                                    WORD *SW);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_IsoSelectDF(SCARDHANDLE hCard,
                                  WORD wFileID,
                                  BYTE abFci[],
                                  WORD wMaxFciLength,
                                  WORD *wGotFciLength,
                                  WORD *SW);

INPUTS

   WORD wFileID        : the identifier of the DF
   BYTE abFci[]        : buffer to receive the FCI of the DF (if some)
   WORD wMaxFciLength  : maximum length of FCI
   WORD *wGotFciLength : actual length of FCI
   WORD *SW            : optional pointer to retrieve the Status Word in
                         case an error occurs

RETURNS

   DF_OPERATION_OK   : success
   Other code if internal or communication error has occured. 

NOTES

   The abFci and wGotFciLength parameter could be set to NULL if no FCI is expected
   or if the caller doesn't care of the FCI.
   This function is also relevant for the root application (Master File -> wFileID = 0x3F00)

SEE ALSO

   IsoSelectDFName
   IsoSelectEF

[Functions] IsoSelectDFName

NAME

   IsoSelectDFName

DESCRIPTION

   Implementation of ISO 7816-4 SELECT FILE command using a Directory Name (P2=0x04)

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_IsoSelectDFName(const BYTE abDFName[],
                                       BYTE bDFNameLength,
                                       BYTE abFci[],
                                       WORD wMaxFciLength,
                                       WORD *wGotFciLength,
                                       WORD *SW);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_IsoSelectDFName(SPROX_INSTANCE rInst, 
                                       const BYTE abDFName[],
                                       BYTE bDFNameLength,
                                       BYTE abFci[],
                                       WORD wMaxFciLength,
                                       WORD *wGotFciLength,
                                       WORD *SW);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_IsoSelectDFName(SCARDHANDLE hCard,
                                      const BYTE abDFName[],
                                      BYTE bDFNameLength,
                                      BYTE abFci[],
                                      WORD wMaxFciLength,
                                      WORD *wGotFciLength,
                                      WORD *SW);

INPUTS

   const BYTE abDFName : the name of the DF
   BYTE bDFNameLength  : the size of the name of the DF
   BYTE abFci[]        : buffer to receive the FCI of the DF (if some)
   WORD wMaxFciLength  : maximum length of FCI
   WORD *wGotFciLength : actual length of FCI
   WORD *SW            : optional pointer to retrieve the Status Word in
                         case an error occurs

RETURNS

   DF_OPERATION_OK   : success
   Other code if internal or communication error has occured. 

NOTES

   The abFci and wGotFciLength parameter could be set to NULL if no FCI is expected
   or if the caller doesn't care of the FCI.

SEE ALSO

   IsoSelectDF
   IsoSelectEF

[Functions] IsoSelectEF

NAME

   IsoSelectEF

DESCRIPTION

   Implementation of ISO 7816-4 SELECT FILE command using a Elementary File ID (P2=0x02)

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_IsoSelectEF(WORD wFileID,
                                   WORD *SW);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_IsoSelectEF(SPROX_INSTANCE rInst, 
                                    WORD wFileID,
                                    WORD *SW);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_IsoSelectEF(SCARDHANDLE hCard,
                                  WORD wFileID,
                                  WORD *SW);

INPUTS

   WORD wFileID      : the identifier of the EF
   WORD *SW          : optional pointer to retrieve the Status Word in
                       case an error occurs

RETURNS

   DF_OPERATION_OK   : success
   Other code if internal or communication error has occured. 

SEE ALSO

   IsoSelectDF

[Functions] IsoUpdateBinary

NAME

   IsoUpdateBinary

DESCRIPTION

   Implementation of ISO 7816-4 UPDATE BINARY command in Desfire EV1 flavour

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_IsoUpdateBinary(WORD wOffset,
                                       const BYTE abData[],
                                       BYTE bLength,
                                       WORD *SW);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_IsoUpdateBinary(SPROX_INSTANCE rInst,
                                        WORD wOffset,
                                        const BYTE abData[],
                                        BYTE bLength,
                                        WORD *SW);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_IsoUpdateBinary(SCARDHANDLE hCard,
                                      WORD wOffset;
                                      const BYTE abData[],
                                      BYTE bLength,
                                      WORD *SW);

INPUTS

   WORD wOffset        : starting position for the write operation in bytes
   const BYTE abData[] : buffer containing the data to write
   BYTE bLength        : size of data to be written in bytes
   WORD *SW            : optional pointer to retrieve the Status Word in
                         case an error occurs

RETURNS

   DF_OPERATION_OK     : success
   Other code if internal or communication error has occured. 

SEE ALSO

   IsoReadBinary

Generated from sprox_desfire_iso.c on Mon Jan 30 14:25:28 2012