NAME
DesfireAPI :: Key management functions
COPYRIGHT
(c) 2009 SpringCard - www.springcard.com
DESCRIPTION
Implementation of management functions to change keys or key settings withing a DESFIRE application.
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
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
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
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
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
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