TABLE OF CONTENTS

 

[Modules] SamAuth

NAME

   DesfireAPI :: Using the Desfire card together with a NXP SAM AV2 smartcard

COPYRIGHT

DESCRIPTION

   Implementation of authentication using the SAM.

[Functions] SAM_Authenticate

NAME

   SAM_Authenticate

DESCRIPTION

   Perform DES/3DES authentication over the Desfire card or application, using the SAM.
   The underlying SAM command is SAM_AuthenticatePICC (80 0A ...).
   This function is an helper to compute the valid parameters to SAM_AuthenticateEx

SYNOPSIS

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_SAM_Authenticate(SCARDHANDLE hCard,
                                       BYTE bKeyNumberCard,
                                       BOOL fApplicationKeyNo,
                                       BYTE bKeyNumberSam,
                                       BYTE bKeyVersion,
                                       const BYTE pbDivInp[],
                                       BYTE bDivInpLength,
                                       BOOL fDivAv2Mode,
                                       BOOL fDivTwoRounds);

INPUTS

   BYTE bKeyNumberCard         : number of the key (KeyNo) within the Desfire card.
   BOOL fApplicationKeyNo      : set to TRUE if SAM_SelectApplication has been issued before and
                                 bKeyNumberSam is the Desfire Key Number within the currently selected
                                 application, or FALSE if bKeyNumberSam is the absolute Key Entry number.
   BYTE bKeyNumberSam          : number of the key (KeyNo) within the SAM.
                                 This could be either the Desfire Key Number when fApplicationKeyNo is
                                 TRUE, or the absolute Key Entry number when fApplicationKeyNo is FALSE.
   BYTE bKeyVersion            : version of the key (within the SAM).
   const BYTE pbDivInp[]       : optionnal diversification input. Set to NULL for no diversification.
   BYTE bDivInpLength          : length of the diversification input (must be 0 if pbDivInp is NULL).
   BOOL fDivAv2Mode            : set to TRUE to use AV2 method for key diversification (FALSE stands
                                 for AV1 method).
   BOOL fDivTwoRounds          : set to TRUE to use two encryption rounds instead of one if key type
                                 is 3DES2K. Must be FALSE for any other key type.

RETURNS

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

SEE ALSO

   SAM_SelectApplication
   SAM_AuthenticateIso
   SAM_AuthenticateAes
   SAM_AuthenticateEx
   SAM_ChangeKeyEx
   SAM_ChangeKey1
   SAM_ChangeKey2

[Functions] SAM_AuthenticateAes

NAME

   SAM_AuthenticateAes

DESCRIPTION

   Perform AES authentication over the Desfire card or application, using the SAM.
   The underlying SAM command is SAM_AuthenticatePICC (80 0A ...).
   This function is an helper to compute the valid parameters to SAM_AuthenticateEx

SYNOPSIS

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_SAM_AuthenticateAes(SCARDHANDLE hCard,
                                       BYTE bKeyNumberCard,
                                       BOOL fApplicationKeyNo,
                                       BYTE bKeyNumberSam,
                                       BYTE bKeyVersion,
                                       const BYTE pbDivInp[],
                                       BYTE bDivInpLength,
                                       BOOL fDivAv2Mode,
                                       BOOL fDivTwoRounds);

INPUTS

   BYTE bKeyNumberCard         : number of the key (KeyNo) within the Desfire card.
   BOOL fApplicationKeyNo      : set to TRUE if SAM_SelectApplication has been issued before and
                                 bKeyNumberSam is the Desfire Key Number within the currently selected
                                 application, or FALSE if bKeyNumberSam is the absolute Key Entry number.
   BYTE bKeyNumberSam          : number of the key (KeyNo) within the SAM.
                                 This could be either the Desfire Key Number when fApplicationKeyNo is
                                 TRUE, or the absolute Key Entry number when fApplicationKeyNo is FALSE.
   BYTE bKeyVersion            : version of the key (within the SAM).
   const BYTE pbDivInp[]       : optionnal diversification input. Set to NULL for no diversification.
   BYTE bDivInpLength          : length of the diversification input (must be 0 if pbDivInp is NULL).
   BOOL fDivAv2Mode            : set to TRUE to use AV2 method for key diversification (FALSE stands
                                 for AV1 method).
   BOOL fDivTwoRounds          : set to TRUE to use two encryption rounds instead of one if key type
                                 is 3DES2K. Must be FALSE for any other key type.

RETURNS

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

SEE ALSO

   SAM_SelectApplication
   SAM_Authenticate
   SAM_AuthenticateIso
   SAM_AuthenticateEx
   SAM_ChangeKeyEx
   SAM_ChangeKey1
   SAM_ChangeKey2

[Functions] SAM_AuthenticateEx

NAME

   SAM_AuthenticateEx

DESCRIPTION

   Perform authentication over the Desfire card or application, using the SAM.
   The underlying SAM command is SAM_AuthenticatePICC (80 0A ...)

SYNOPSIS

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_SAM_AuthenticateEx(SCARDHANDLE hCard,
                                         BYTE bAuthMethod,
                                         BYTE bKeyNumberCard,
                                         BYTE bSamParamP1,
                                         BYTE bSamParamP2,
                                         BYTE bKeyNumberSam,
                                         BYTE bKeyVersion,
                                         const BYTE pbDivInp[],
                                         BYTE bDivInpLength);

INPUTS

   BYTE bAuthMethod            : authentication method. Correct values are 0A (Authenticate)
                                 1A (Authenticate ISO) and AA (Authenticate AES)
   BYTE bKeyNumberCard         : number of the key (KeyNo) within the Desfire card.
   BYTE bSamParamP1            : P1 parameter to the SAM_AuthenticatePICC command.
   BYTE bSamParamP2            : P2 parameter to the SAM_AuthenticatePICC command.
   BYTE bKeyNumberSam          : number of the key (KeyNo) within the SAM.
                                 this could be either the Desfire Key Number within the application
                                 if SAM_SelectApplication has been issued before, or the absolute
                                 Key Entry number of no SAM_SelectApplication has been issued before.
   BYTE bKeyVersion            : version of the key (within the SAM).
   const BYTE pbDivInp[]       : optionnal diversification input. Set to NULL for no diversification.
   BYTE bDivInpLength          : length of the diversification input (must be 0 if pbDivInp is NULL).

RETURNS

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

NOTES

   P1 xxxxxxxx
             +-- 0 : no diversification
                 1 : key diversified by pbDivInp
            +--- 0 : key selection by Key Entry number
                 1 : key selection by Desfire Key Number (after SAM_SelectApplication)
           +---- RFU, must be 0
          +----- 3DES2K : 0 : diversify using two encryption rounds
                          1 : diversify using one encryption rounds
                 3DES3K, AES : RFU, must be 0
         +------ 0 : use AV1 method for key diversification
                 1 : use AV2 method for key diversification
      +++------- RFU, must be 000

   P2 xxxxxxxx
      ++++++++-- RFU, must be 00000000

   Valid values for bDivInpLength are :
   - 8 when AV1 method is used with a DES, 3DES2K or 3DES3K key
   - 16 when AV1 method is used with an AES key
   - any length between 1 and 31 when AV2 method is used

   Please refer to the documentation of NXP SAM AV2 for more details (P5DF081 data sheet, § 11.7.1)

SEE ALSO

   SAM_SelectApplication
   SAM_Authenticate
   SAM_AuthenticateIso
   SAM_AuthenticateAes
   SAM_ChangeKeyEx
   SAM_ChangeKey1
   SAM_ChangeKey2

[Functions] SAM_AuthenticateIso

NAME

   SAM_AuthenticateIso

DESCRIPTION

   Perform Iso authentication over the Desfire card or application, using the SAM.
   The underlying SAM command is SAM_AuthenticatePICC (80 0A ...).
   This function is an helper to compute the valid parameters to SAM_AuthenticateEx

SYNOPSIS

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_SAM_AuthenticateIso(SCARDHANDLE hCard,
                                       BYTE bKeyNumberCard,
                                       BOOL fApplicationKeyNo,
                                       BYTE bKeyNumberSam,
                                       BYTE bKeyVersion,
                                       const BYTE pbDivInp[],
                                       BYTE bDivInpLength,
                                       BOOL fDivAv2Mode,
                                       BOOL fDivTwoRounds);

INPUTS

   BYTE bKeyNumberCard         : number of the key (KeyNo) within the Desfire card.
   BOOL fApplicationKeyNo      : set to TRUE if SAM_SelectApplication has been issued before and
                                 bKeyNumberSam is the Desfire Key Number within the currently selected
                                 application, or FALSE if bKeyNumberSam is the absolute Key Entry number.
   BYTE bKeyNumberSam          : number of the key (KeyNo) within the SAM.
                                 This could be either the Desfire Key Number when fApplicationKeyNo is
                                 TRUE, or the absolute Key Entry number when fApplicationKeyNo is FALSE.
   BYTE bKeyVersion            : version of the key (within the SAM).
   const BYTE pbDivInp[]       : optionnal diversification input. Set to NULL for no diversification.
   BYTE bDivInpLength          : length of the diversification input (must be 0 if pbDivInp is NULL).
   BOOL fDivAv2Mode            : set to TRUE to use AV2 method for key diversification (FALSE stands
                                 for AV1 method).
   BOOL fDivTwoRounds          : set to TRUE to use two encryption rounds instead of one if key type
                                 is 3DES2K. Must be FALSE for any other key type.

RETURNS

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

SEE ALSO

   SAM_SelectApplication
   SAM_Authenticate
   SAM_AuthenticateAes
   SAM_AuthenticateEx
   SAM_ChangeKeyEx
   SAM_ChangeKey1
   SAM_ChangeKey2

[Functions] SAM_SelectApplication

NAME

   SAM_SelectApplication

DESCRIPTION

   Selects one specific application within the SAM

SYNOPSIS

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_SAM_SelectApplication(SCARDHANDLE hCard,
                                            DWORD aid);

INPUTS

   DWORD aid                   : Application IDentifier

RETURNS

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

SEE ALSO

   SelectApplication
   SAM_AuthenticateEx
   SAM_Authenticate

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