TABLE OF CONTENTS

 

[Modules] Keys

NAME

   DesfireAPI :: Key management functions

COPYRIGHT

DESCRIPTION

   Implementation of management functions to change keys or
   key settings withing a DESFIRE application.

[Functions] ChangeKey

NAME

   ChangeKey

DESCRIPTION

   Change a DES, or 3DES2K key in the selected Desfire application.

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_ChangeKey(BYTE key_number,
                                 const BYTE new_key[16],
                                 const BYTE old_key[16]);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_ChangeKey(SPROX_INSTANCE rInst,
                                  BYTE key_number,
                                  const BYTE new_key[16],
                                  const BYTE old_key[16]);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_ChangeKey(SCARDHANDLE hCard,
                                BYTE key_number,
                                const BYTE new_key[16],
                                const BYTE old_key[16]);

INPUTS

   BYTE key_number        : number of the key (KeyNo)
   const BYTE new_key[16] : 16-byte New Key (DES/3DES keys)
   const BYTE old_key[16] : 16-byte Old Key (DES/3DES keys)

RETURNS

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

NOTES

   Both DES and 3DES keys are stored in strings consisting of 16 bytes :
   * If the 2nd half of the key string is equal to the 1st half, the key is
   handled as a single DES key by the DesFire card.
   * If the 2nd half of the key string is NOT equal to the 1st half, the key
   is handled as a 3DES key.

   After a successful change of the key used to reach the current authentication status, this
   authentication is invalidated, an authentication with the new key is necessary for subsequent
   operations.

   If authentication has been performed before calling ChangeKey with the old key,
   use NULL instead of old_key.

SEE ALSO

   ChangeKey24
   ChangeKeyAes
   Authenticate
   ChangeKeySettings
   GetKeySettings
   GetKeyVersion

[Functions] ChangeKey24

NAME

   ChangeKey24

DESCRIPTION

   Change a 3DES3K key in the selected Desfire application.

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_ChangeKey24(BYTE key_number,
                                   const BYTE new_key[24],
                                   const BYTE old_key[24]);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_ChangeKey24(SPROX_INSTANCE rInst,
                                    BYTE key_number,
                                    const BYTE new_key[24],
                                    const BYTE old_key[24]);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_ChangeKey24(SCARDHANDLE hCard,
                                  BYTE key_number,
                                  const BYTE new_key[24],
                                  const BYTE old_key[24]);

INPUTS

   BYTE key_number        : number of the key (KeyNo)
   const BYTE new_key[24] : 24-byte New Key (3DES keys)
   const BYTE old_key[24] : 24-byte Old Key (3DES keys)

RETURNS

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

SEE ALSO

   ChangeKey16
   ChangeKeyAes
   Authenticate
   ChangeKeySettings
   GetKeySettings
   GetKeyVersion

[Functions] ChangeKeyAes

NAME

   ChangeKeyAes

DESCRIPTION

   Change an AES key in the selected Desfire application.

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_ChangeKeyAes(BYTE key_number,
                                    BYTE key_version,
                                    const BYTE new_key[16],
                                    const BYTE old_key[16]);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_ChangeKeyAes(SPROX_INSTANCE rInst,
                                     BYTE key_number,
                                     BYTE key_version,
                                     const BYTE new_key[16],
                                     const BYTE old_key[16]);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_ChangeKeyAes(SCARDHANDLE hCard,
                                   BYTE key_number,
                                   BYTE key_version,
                                   const BYTE new_key[16],
                                   const BYTE old_key[16]);

INPUTS

   BYTE key_number        : number of the key (KeyNo)
   BYTE key_version       : version number to be stored together with the key
   const BYTE new_key[16] : 16-byte New Key (AES key)
   const BYTE old_key[16] : 16-byte Old Key (AES key)

RETURNS

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

SEE ALSO

   ChangeKey
   ChangeKey24
   Authenticate
   ChangeKeySettings
   GetKeySettings
   GetKeyVersion

[Functions] ChangeKeySettings

NAME

   ChangeKeySettings

DESCRIPTION

   Changes the key settings of the currently selected application
   (or of card's master key if root application is selected)

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_ChangeKeySettings (BYTE key_settings);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_ChangeKeySettings(SPROX_INSTANCE rInst,
                                          BYTE key_settings);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_ChangeKeySettings  (SCARDHANDLE hCard,
                                          BYTE key_settings);

INPUTS

   BYTE key_settings  : new key settings (see chapter 4.3.2 of datasheet of mifare
                        DesFire MF3ICD40 for more information)

RETURNS

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

SEE ALSO

   Authenticate
   GetKeySettings
   ChangeKey
   GetKeyVersion

[Functions] GetKeySettings

NAME

   GetKeySettings

DESCRIPTION

   Gets information on the DesFire card and application master key settings. In addition it returns
   the maximum number of keys which can be stored within the selected application.

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_GetKeySettings (BYTE *key_settings,
                                       BYTE *key_count);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_GetKeySettings(SPROX_INSTANCE rInst,
                                       BYTE *key_settings,
                                       BYTE *key_count);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_GetKeySettings  (SCARDHANDLE hCard,
                                       BYTE *key_settings,
                                       BYTE *key_count);

INPUTS

   BYTE *key_settings          : master key settings (see chapter 4.3.2 of datasheet of mifare
                                 DesFire MF3ICD40 for more information)
   BYTE *key_count             : maximum number of keys

RETURNS

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

SEE ALSO

   Authenticate
   ChangeKeySettings
   ChangeKey
   GetKeyVersion

[Functions] GetKeyVersion

NAME

   GetKeyVersion

DESCRIPTION

   Reads out the current key version of any key stored on the PICC

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_GetKeyVersion(BYTE bKeyNumber,
                                     BYTE *pbKeyVersion);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_GetKeyVersion(SPROX_INSTANCE rInst,
                                      BYTE bKeyNumber,
                                      BYTE *pbKeyVersion);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_GetKeyVersion(SCARDHANDLE hCard,
                                    BYTE bKeyNumber,
                                    BYTE *pbKeyVersion);

INPUTS

   BYTE bKeyNumber             : number of the key (KeyNo)
   BYTE *pbKeyVersion          : current version of the specified key

RETURNS

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

NOTES

   This command can be issued without valid authentication.

SEE ALSO

   Authenticate
   GetKeySettings
   ChangeKeySettings
   ChangeKey

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