TABLE OF CONTENTS

 

[Modules] SamKeys

NAME

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

COPYRIGHT

DESCRIPTION

   Implementation of key management using the SAM.

[Functions] SAM_ChangeKey1

NAME

   SAM_ChangeKey1

DESCRIPTION

   Perform authentication over the Desfire card or application, using the SAM.
   The underlying SAM command is SAM_ChangeKeyPICC (80 C4 ...)
   This function is an helper to compute the valid parameters to SAM_ChangeKeyEx when
   only the new key is involved (i.e. when the ChangeKey key of the targeting application
   is 0E, or the master key itself is changed).

SYNOPSIS

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_SAM_ChangeKey1(SCARDHANDLE hCard,
                                     BYTE bKeyNumberCard,
                                     BOOL fIsCardMasterKey,
                                     BYTE bNewKeyNumberSam,
                                     BYTE bNewKeyVersion,
                                     const BYTE pbDivInp[],
                                     BYTE bDivInpLength,
                                     BOOL fDivAv2Mode,
                                     BOOL fNewDivEnable,
                                     BOOL fNewDivTwoRounds);

INPUTS

   BYTE bKeyNumberCard         : number of the key (KeyNo) within the Desfire card.
   BOOL fIsCardMasterKey       : set to TRUE to change the Desfire card master key (key 00 in application
                                 000000).
   BYTE bNewKeyNumberSam       : Key Entry number of new key (within the SAM).
   BYTE bNewKeyVersion         : version of the new 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 fNewDivEnable          : set to TRUE to diversify the new key using pbDivInp.
   BOOL fNewDivTwoRounds       : set to TRUE to use two encryption rounds instead of one if key type
                                 for new key 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_AuthenticateEx
   SAM_Authenticate
   SAM_ChangeKeyEx
   SAM_ChangeKey2

[Functions] SAM_ChangeKey2

NAME

   SAM_ChangeKey2

DESCRIPTION

   Perform authentication over the Desfire card or application, using the SAM.
   The underlying SAM command is SAM_ChangeKeyPICC (80 C4 ...)
   This function is an helper to compute the valid parameters to SAM_ChangeKeyEx when
   both the new and the current keys are involved (i.e. when the ChangeKey key of the
   targeting application 00 to 0D, and the key to be changed is not the master key).

SYNOPSIS

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_SAM_ChangeKey2(SCARDHANDLE hCard,
                                     BYTE bKeyNumberCard,
                                     BOOL fIsCardMasterKey,
                                     BYTE bOldKeyNumberSam,
                                     BYTE bOldKeyVersion,
                                     BYTE bNewKeyNumberSam,
                                     BYTE bNewKeyVersion,
                                     const BYTE pbDivInp[],
                                     BYTE bDivInpLength,
                                     BOOL fDivAv2Mode,
                                     BOOL fOldDivEnable,
                                     BOOL fOldDivTwoRounds,
                                     BOOL fNewDivEnable,
                                     BOOL fNewDivTwoRounds);

INPUTS

   BYTE bKeyNumberCard         : number of the key (KeyNo) within the Desfire card.
   BYTE bOldKeyNumberSam       : Key Entry number of current key (within the SAM).
   BYTE bOldKeyVersion         : version of the current key (within the SAM).
   BYTE bNewKeyNumberSam       : Key Entry number of new key (within the SAM).
   BYTE bNewKeyVersion         : version of the new 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 fOldDivEnable          : set to TRUE to diversify the current key using pbDivInp.
   BOOL fOldDivTwoRounds       : set to TRUE to use two encryption rounds instead of one if key type
                                 for current key is 3DES2K. Must be FALSE for any other key type.
   BOOL fNewDivEnable          : set to TRUE to diversify the new key using pbDivInp.
   BOOL fNewDivTwoRounds       : set to TRUE to use two encryption rounds instead of one if key type
                                 for new key 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_AuthenticateEx
   SAM_Authenticate
   SAM_ChangeKeyEx
   SAM_ChangeKey1

[Functions] SAM_ChangeKeyEx

NAME

   SAM_ChangeKeyEx

DESCRIPTION

   Perform authentication over the Desfire card or application, using the SAM.
   The underlying SAM command is SAM_ChangeKeyPICC (80 C4 ...)

SYNOPSIS

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_SAM_ChangeKeyEx(SCARDHANDLE hCard,
                                      BYTE bKeyNumberCard,
                                      BYTE bSamParamP1,
                                      BYTE bSamParamP2,
                                      BYTE bOldKeyNumberSam,
                                      BYTE bOldKeyVersion,
                                      BYTE bNewKeyNumberSam,
                                      BYTE bNewKeyVersion,
                                      const BYTE pbDivInp[],
                                      BYTE bDivInpLength);

INPUTS

   BYTE bKeyNumberCard         : number of the key (KeyNo) within the Desfire card.
   BYTE bSamParamP1            : P1 parameter to the SAM_ChangeKeyPICC command.
   BYTE bSamParamP2            : P2 parameter to the SAM_ChangeKeyPICC command.
   BOOL fUseOldKey             : Flag indicating if current key is needed
   BYTE bOldKeyNumberSam       : Key Entry number of current key (within the SAM).
   BYTE bOldKeyVersion         : version of the current key (within the SAM).
   BYTE bNewKeyNumberSam       : Key Entry number of new key (within the SAM).
   BYTE bNewKeyVersion         : version of the new 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 : the ChangeKey key of the targeting application is 00 to 0D, and the key to
                     be changed is not the master key.
                 1 : the ChangeKey key of the targeting application is 0E, or the master key
                     itself is changed. In this case only the new key is involved, parameters
                     bOldKeyNumberSam and bOldKeyVersion are ignored.
            +--- 0 : no diversification for new key
                 1 : new key diversified by pbDivInp
           +---- 0 : no diversification for current key
                 1 : current key diversified by pbDivInp
          +----- if new key is 3DES2K : 0 : diversify new key using two encryption rounds
                                        1 : diversify new key using one encryption rounds
                 if new key is 3DES3K, AES : RFU, must be 0
         +------ if current key is 3DES2K : 0 : diversify current key using two encryption rounds
                                            1 : diversify current key using one encryption rounds
                 if current key 3DES3K, AES : RFU, must be 0
        +------- 0 : use AV1 method for key diversification (both current and new)
                 1 : use AV2 method for key diversification (both current and new)
      ++-------- RFU, must be 00

   P2 xxxxxxxx
           +++-- number of the key (KeyNo) within the Desfire card (must be the same as bKeyNumberCard)
          +----- 0 : for every key but the Desfire card master key
                 1 : to change the Desfire card master key
      ++++------ RFU, must be 0000

   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

   The command will not succeed if the two involved key entries are not of the same key type within
   the SAM.

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

SEE ALSO

   SAM_SelectApplication
   SAM_Authenticate
   SAM_AuthenticateEx
   SAM_ChangeKey1
   SAM_ChangeKey2

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