NAME
DesfireAPI :: Using the Desfire card together with a NXP SAM AV2 smartcard
COPYRIGHT
(c) 2014 SpringCard - www.springcard.com
DESCRIPTION
Implementation of authentication using the SAM.
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
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
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
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
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