NAME
DesfireAPI :: ISO 7816-4 functions
COPYRIGHT
(c) 2009 SpringCard - www.springcard.com
DESCRIPTION
Implementation of DESFIRE ISO 7816-4 compliant functions.
NAME
IsoAppendRecord
DESCRIPTION
Implementation of ISO 7816-4 APPEND RECORD command in Desfire EV1 flavour
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_IsoAppendRecord(const BYTE abData[], BYTE bLength, WORD *SW); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_IsoAppendRecord(SPROX_INSTANCE rInst, const BYTE abData[], BYTE bLength, WORD *SW); [[pcsc_desfire.dll]] LONG SCardDesfire_IsoAppendRecord(SCARDHANDLE hCard, const BYTE abData[], BYTE bLength, WORD *SW);
INPUTS
const BYTE abData[] : buffer containing the data to write BYTE bLength : size of data to be written in bytes WORD *SW : optional pointer to retrieve the Status Word in case an error occurs
RETURNS
DF_OPERATION_OK : success Other code if internal or communication error has occured.
SEE ALSO
IsoReadRecord
NAME
IsoExternalAuthenticate
DESCRIPTION
Implementation of ISO 7816-4 EXTERNAL AUTHENTICATE command in Desfire EV1 flavour
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_IsoExternalAuthenticate(BYTE bKeyAlgorithm, BYTE bKeyReference, BYTE bRndSize, const BYTE abRndCard1[], const BYTE abRndHost1[], const BYTE abKeyValue[], WORD *SW); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_IsoExternalAuthenticate(SPROX_INSTANCE rInst, BYTE bKeyAlgorithm, BYTE bKeyReference, BYTE bRndSize, const BYTE abRndCard1[], const BYTE abRndHost1[], const BYTE abKeyValue[], WORD *SW); [[pcsc_desfire.dll]] LONG SCardDesfire_IsoExternalAuthenticate(SCARDHANDLE hCard, BYTE bKeyAlgorithm, BYTE bKeyReference, BYTE bRndSize, const BYTE abRndCard1[], const BYTE abRndHost1[], const BYTE abKeyValue[], WORD *SW);
INPUTS
BYTE bKeyAlgorithm : algorithm to be used: - 0x02 : DES or 3DES2K (16-byte key) - 0x04 : 3DES3K (24-byte key) - 0x09 : AES (16-byte key) BYTE bKeyReference : reference to the key in the card - 0x00 : card's master key (valid only on root application) - 0x8n : application's key #n BYTE bRndSize : size of the challenge (8 bytes for DES/3DES2K, 16 bytes for 3DES3K or AES) const BYTE abRndCard1[] : card's first challenge (as returned by IsoGetChallenge - not involved in session key) const BYTE abRndHost1[] : host's first challenge (choosen by the caller - involved in session key) const BYTE abKeyValue [16] : the key itself WORD *SW : optional pointer to retrieve the Status Word in case an error occurs
RETURNS
DF_OPERATION_OK : success Other code if internal or communication error has occured.
SEE ALSO
IsoMutualAuthenticate IsoGetChallenge IsoInternalAuthenticate
NAME
IsoGetChallenge
DESCRIPTION
Implementation of ISO 7816-4 GET CHALLENGE command in Desfire EV1 flavour
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_IsoGetChallenge(BYTE bKeyAlgorithm, BYTE bRndSize, BYTE abRndCard1[], WORD *SW); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_IsoGetChallenge(SPROX_INSTANCE rInst, BYTE bRndSize, BYTE abRndCard1[], WORD *SW); [[pcsc_desfire.dll]] LONG SCardDesfire_IsoGetChallenge(SCARDHANDLE hCard, BYTE bRndSize, BYTE abRndCard1[], WORD *SW);
INPUTS
BYTE bRndSize : size of the challenge (8 bytes for DES/3DES2K, 16 bytes for 3DES3K or AES) BYTE abRndCard1[] : card's first challenge (not involved in session key) WORD *SW : optional pointer to retrieve the Status Word in case an error occurs
RETURNS
DF_OPERATION_OK : success Other code if internal or communication error has occured.
SEE ALSO
IsoMutualAuthenticate IsoExternalAuthenticate IsoInternalAuthenticate
NAME
IsoInternalAuthenticate
DESCRIPTION
Implementation of ISO 7816-4 INTERNAL AUTHENTICATE command in Desfire EV1 flavour
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_IsoInternalAuthenticate(BYTE bKeyAlgorithm, BYTE bKeyReference, BYTE bRndSize, const BYTE abRndHost2[], BYTE abRndCard2[], const BYTE abKeyValue[], WORD *SW); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_IsoInternalAuthenticate(SPROX_INSTANCE rInst, BYTE bKeyAlgorithm, BYTE bKeyReference, BYTE bRndSize, const BYTE abRndHost2[], BYTE abRndCard2[], const BYTE abKeyValue[], WORD *SW); [[pcsc_desfire.dll]] LONG SCardDesfire_IsoInternalAuthenticate(SCARDHANDLE hCard, BYTE bKeyAlgorithm, BYTE bKeyReference, BYTE bRndSize, const BYTE abRndHost2[], BYTE abRndCard2[], const BYTE abKeyValue[], WORD *SW);
INPUTS
BYTE bKeyAlgorithm : algorithm to be used: - 0x02 : DES or 3DES2K (16-byte key) - 0x04 : 3DES3K (24-byte key) - 0x09 : AES (16-byte key) BYTE bKeyReference : reference to the key in the card - 0x00 : card's master key (valid only on root application) - 0x8n : application's key #n BYTE bRndSize : size of the challenge (8 bytes for DES/3DES2K, 16 bytes for 3DES3K or AES) const BYTE abRndHost2[] : host's second challenge (choosen by the caller - not involved in session key) BYTE abRndCard2[] : card's second challenge (choosen by the card - involved in session key) const BYTE abKeyValue [16] : the key itself WORD *SW : optional pointer to retrieve the Status Word in case an error occurs
RETURNS
DF_OPERATION_OK : success Other code if internal or communication error has occured.
SEE ALSO
IsoMutualAuthenticate IsoGetChallenge IsoExternalAuthenticate
NAME
IsoMutualAuthenticate
DESCRIPTION
Perform a mutual-authentication using the Desfire ISO 7816-4 commands (IsoGetChallenge, IsoExternalAuthenticate, IsoInternalAuthenticate) using the specified key value. Depending on bKeyAlgorithm, the key is either DES/3DES2K (16 bytes), AES (16 bytes) or 3DES3K (24 bytes). The generated session key is afterwards used for ISO CMACing.
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_IsoMutualAuthenticate(BYTE bKeyAlgorithm, BYTE bKeyReference, const BYTE abKeyValue[], WORD *SW); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_IsoMutualAuthenticate(SPROX_INSTANCE rInst, BYTE bKeyAlgorithm, BYTE bKeyReference, const BYTE abKeyValue[], WORD *SW); [[pcsc_desfire.dll]] LONG SCardDesfire_IsoMutualAuthenticate(SCARDHANDLE hCard, BYTE bKeyAlgorithm, BYTE bKeyReference, const BYTE abKeyValue[], WORD *SW);
INPUTS
BYTE bKeyAlgorithm : algorithm to be used: - 0x02 : DES or 3DES2K (16-byte key) - 0x04 : 3DES3K (24-byte key) - 0x09 : AES (16-byte key) BYTE bKeyReference : reference to the key in the card - 0x00 : card's master key (valid only on root application) - 0x8n : application's key #n const BYTE abKeyValue [16] : the key itself WORD *SW : optional pointer to retrieve the Status Word in case an error occurs
RETURNS
DF_OPERATION_OK : authentication succeed Other code if internal or communication error has occured.
SEE ALSO
Authenticate AuthenticateAes AuthenticateIso24 AuthenticateIso IsoGetChallenge IsoExternalAuthenticate IsoInternalAuthenticate
NAME
IsoReadBinary
DESCRIPTION
Implementation of ISO 7816-4 READ BINARY command in Desfire EV1 flavour
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_IsoReadBinary(WORD wOffset, BYTE abData[], BYTE bWantLength, WORD *wGotLength, WORD *SW); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_IsoReadBinary(SPROX_INSTANCE rInst, WORD wOffset, BYTE abData[], BYTE bWantLength, WORD *wGotLength, WORD *SW); [[pcsc_desfire.dll]] LONG SCardDesfire_IsoReadBinary(SCARDHANDLE hCard, WORD wOffset, BYTE abData[], BYTE bWantLength, WORD *wGotLength, WORD *SW);
INPUTS
WORD wOffset : starting position for the read operation BYTE abData[] : buffer to receive the data BYTE bWantLength : maximum data length to read. Set to 0 to read 256 bytes. WORD *wGotLength : actual data length read WORD *SW : optional pointer to retrieve the Status Word in case an error occurs
RETURNS
DF_OPERATION_OK : success Other code if internal or communication error has occured.
NOTES
After a successfull authentication, a CMAC is added to card's response. The value of bWantLength must be choosen in consequence. This command checks the value of the CMAC in card's response and removes it from the data buffer.
SEE ALSO
IsoUpdateBinary IsoReadRecord
NAME
IsoReadRecord
DESCRIPTION
Implementation of ISO 7816-4 READ RECORD command in Desfire EV1 flavour
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_IsoReadRecord(BYTE bRecNum, BOOL fReadAll; BOOL abData[], WORD wMaxLength, WORD *wGotLength, WORD *SW); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_IsoReadRecord(SPROX_INSTANCE rInst, BYTE bRecNum, BOOL fReadAll; BOOL abData[], WORD wMaxLength, WORD *wGotLength, WORD *SW); [[pcsc_desfire.dll]] LONG SCardDesfire_IsoReadRecord(SCARDHANDLE hCard, BYTE bRecNum, BOOL fReadAll; BOOL abData[], WORD wMaxLength, WORD *wGotLength, WORD *SW);
INPUTS
BYTE bRecNum : first (or only) record to read BOOL fReadAll : TRUE : read all records (starting from bRecNum) FALSE : read only record # bRecNum BYTE abData[] : buffer to receive the data WORD wMaxLength : size of the buffer WORD *wGotLength : actual data length read WORD *SW : optional pointer to retrieve the Status Word in case an error occurs
RETURNS
DF_OPERATION_OK : success Other code if internal or communication error has occured.
NOTES
After a successfull authentication, a CMAC is added to card's response. This command checks the value of the CMAC in card's response and removes it from the data buffer.
SEE ALSO
IsoAppendRecord IsoReadBinary
NAME
IsoSelectApplet
DESCRIPTION
Send the ISO 7816-4 SELECT FILE command with the DESFIRE applet name as parameter (P2 = 0x04, DataIn = 0xD2, 0x76, 0x00, 0x00, 0x85, 0x01, 0x00 )
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_IsoSelectApplet(WORD *SW); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_IsoSelectApplet(SPROX_INSTANCE rInst, WORD *SW); [[pcsc_desfire.dll]] LONG SCardDesfire_IsoSelectApplet(SCARDHANDLE hCard, WORD *SW);
INPUTS
WORD *SW : optional pointer to retrieve the Status Word in case an error occurs
RETURNS
DF_OPERATION_OK : success Other code if internal or communication error has occured. SIDE EFFECT Wrapping mode is implicitly defined to DF_ISO_WRAPPING_CARD
NAME
IsoSelectDF
DESCRIPTION
Implementation of ISO 7816-4 SELECT FILE command using a Directory File ID (P2=0x02)
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_IsoSelectDF(WORD wFileID, BYTE abFci[], WORD wMaxFciLength, WORD *wGotFciLength, WORD *SW); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_IsoSelectDF(SPROX_INSTANCE rInst, WORD wFileID, BYTE abFci[], WORD wMaxFciLength, WORD *wGotFciLength, WORD *SW); [[pcsc_desfire.dll]] LONG SCardDesfire_IsoSelectDF(SCARDHANDLE hCard, WORD wFileID, BYTE abFci[], WORD wMaxFciLength, WORD *wGotFciLength, WORD *SW);
INPUTS
WORD wFileID : the identifier of the DF BYTE abFci[] : buffer to receive the FCI of the DF (if some) WORD wMaxFciLength : maximum length of FCI WORD *wGotFciLength : actual length of FCI WORD *SW : optional pointer to retrieve the Status Word in case an error occurs
RETURNS
DF_OPERATION_OK : success Other code if internal or communication error has occured.
NOTES
The abFci and wGotFciLength parameter could be set to NULL if no FCI is expected or if the caller doesn't care of the FCI. This function is also relevant for the root application (Master File -> wFileID = 0x3F00)
SEE ALSO
IsoSelectDFName IsoSelectEF
NAME
IsoSelectDFName
DESCRIPTION
Implementation of ISO 7816-4 SELECT FILE command using a Directory Name (P2=0x04)
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_IsoSelectDFName(const BYTE abDFName[], BYTE bDFNameLength, BYTE abFci[], WORD wMaxFciLength, WORD *wGotFciLength, WORD *SW); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_IsoSelectDFName(SPROX_INSTANCE rInst, const BYTE abDFName[], BYTE bDFNameLength, BYTE abFci[], WORD wMaxFciLength, WORD *wGotFciLength, WORD *SW); [[pcsc_desfire.dll]] LONG SCardDesfire_IsoSelectDFName(SCARDHANDLE hCard, const BYTE abDFName[], BYTE bDFNameLength, BYTE abFci[], WORD wMaxFciLength, WORD *wGotFciLength, WORD *SW);
INPUTS
const BYTE abDFName : the name of the DF BYTE bDFNameLength : the size of the name of the DF BYTE abFci[] : buffer to receive the FCI of the DF (if some) WORD wMaxFciLength : maximum length of FCI WORD *wGotFciLength : actual length of FCI WORD *SW : optional pointer to retrieve the Status Word in case an error occurs
RETURNS
DF_OPERATION_OK : success Other code if internal or communication error has occured.
NOTES
The abFci and wGotFciLength parameter could be set to NULL if no FCI is expected or if the caller doesn't care of the FCI.
SEE ALSO
IsoSelectDF IsoSelectEF
NAME
IsoSelectEF
DESCRIPTION
Implementation of ISO 7816-4 SELECT FILE command using a Elementary File ID (P2=0x02)
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_IsoSelectEF(WORD wFileID, WORD *SW); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_IsoSelectEF(SPROX_INSTANCE rInst, WORD wFileID, WORD *SW); [[pcsc_desfire.dll]] LONG SCardDesfire_IsoSelectEF(SCARDHANDLE hCard, WORD wFileID, WORD *SW);
INPUTS
WORD wFileID : the identifier of the EF WORD *SW : optional pointer to retrieve the Status Word in case an error occurs
RETURNS
DF_OPERATION_OK : success Other code if internal or communication error has occured.
SEE ALSO
IsoSelectDF
NAME
IsoUpdateBinary
DESCRIPTION
Implementation of ISO 7816-4 UPDATE BINARY command in Desfire EV1 flavour
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_IsoUpdateBinary(WORD wOffset, const BYTE abData[], BYTE bLength, WORD *SW); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_IsoUpdateBinary(SPROX_INSTANCE rInst, WORD wOffset, const BYTE abData[], BYTE bLength, WORD *SW); [[pcsc_desfire.dll]] LONG SCardDesfire_IsoUpdateBinary(SCARDHANDLE hCard, WORD wOffset; const BYTE abData[], BYTE bLength, WORD *SW);
INPUTS
WORD wOffset : starting position for the write operation in bytes const BYTE abData[] : buffer containing the data to write BYTE bLength : size of data to be written in bytes WORD *SW : optional pointer to retrieve the Status Word in case an error occurs
RETURNS
DF_OPERATION_OK : success Other code if internal or communication error has occured.
SEE ALSO
IsoReadBinary