NAME
SpringProxAPI :: Mifare
DESCRIPTION
Implementation of Philips Mifare functions (Mifare Standard and Mifare UltraLite)
NAME
ACC_AUTH_NORMAL
DESCRIPTION
Recommended access condition for a Mifare sector trailer : - key 'A' doesn't give access to sector trailer - key 'B' gives full access to sector trailer (sectors' master key)
NOTES
This constant is to be used as parameter ac3 of SPROX_MifStUpdateAccessBlock.
NAME
ACC_AUTH_TRANSPORT
DESCRIPTION
"Transport" access condition of a Mifare sector trailer : - key 'A' gives full access to sector trailer (sectors' master key) - key 'B' is not used for authentication (and thus readable with key 'A')
NOTES
This constant is to be used as parameter ac3 of SPROX_MifStUpdateAccessBlock.
NAME
ACC_BLOCK_COUNT
DESCRIPTION
Recommended access condition for a Mifare block used as a counter : - key 'A' offers read and decrement only access - key 'B' offers read, write, decrement and increment access
NOTES
This constant is to be used as parameter ac0, ac1 and ac2 of SPROX_MifStUpdateAccessBlock.
NAME
ACC_BLOCK_VALUE
DESCRIPTION
Recommended access condition for a Mifare block used as data storage : - key 'A' offers read only access - key 'B' offers read and write access
NOTES
This constant is to be used as parameter ac0, ac1 and ac2 of SPROX_MifStUpdateAccessBlock.
NAME
SPROX_MifLastAuthKey
DESCRIPTION
Returns the last Mifare key that has allowed a successfull read or write operation.
INPUTS
BYTE *info : pointer to a byte to return the expected information
RETURNS
MI_OK : success, data have been read Other code if internal or communication error has occured.
NOTES
Returned value for info is a bit-field coded as follow : xxxxxxxx +++++-- key number : offset of the key in RAM or EEPROM +------- key type : 1 for a 'B' key, 0 for an 'A' key ++-------- key provider : 10 for a key found in reader's RAM 01 for a key found in RC chipset's EEPROM 11 if the key has been passed directly to the function (no automatic discovery). 00 is RFU
NAME
SPROX_MifLoadKey
DESCRIPTION
Load Mifare key into the reader. It will be used by every function performing automatic key trying.
INPUTS
BOOL eeprom : set to TRUE for EEPROM storage set to FALSE for temporary RAM storage BYTE key_type : set to 'A' for a Mifare A key set to 'B' for a Mifare B key BYTE key_offset : index of the key into the memory - 0 to 15 for EEPROM storage - 0 to 3 for RAM storage const BYTE key_data[6] : value of the key
RETURNS
MI_OK : success, key has been written Other code if internal or communication error has occured.
WARNING
EEPROM keys are stored in the RC chipset EEPROM. Do not write the keys "too often" since an EEPROM has a limited lifetime depending on the write operations count. Typically, load your application keys in EEPROM once at product install, then forget it...
NOTES
There's not mean to read back the loaded keys. Highest performance will be achieved when the right authentication key for a block or a sector is available at the beginning of the RAM or of the EEPROM !
SEE ALSO
SPROX_MifLastAuthKey
NAME
SPROX_MifRead
DESCRIPTION
Read one 16-byte block of a Mifare card. No implicit authentication is performed ; this is typically the appropriate function to read from a Mifare UltraLight card.
WARNING
On a Mifare Standard card, authentication is mandatory, use SPROX_MifStReadBlock.
INPUTS
const BYTE snr[4] : 4-byte UID of the Mifare card to read If NULL, the reader will work with currently selected card BYTE address : address to read BYTE data[16] : 16-byte buffer to receive the data
RETURNS
MI_OK : success, data have been read MI_NOTAGERR : the required card is not available in the RF field Other code if internal or communication error has occured.
SEE ALSO
SPROX_MifWrite SPROX_MifStReadBlock
NAME
SPROX_MifStDecrementCounter
DESCRIPTION
Decrement a Mifare tag counter, using given key or internally available keys for authentication.
INPUTS
const BYTE snr[4] : 4-byte UID of the Mifare card If NULL, the reader will work with currently selected tag BYTE bloc : address of the block holding the counter DWORD value : number of units the counter is to be decremented const BYTE key[6] : The Mifare access key of the sector (either A or B) If NULL, the reader will try all the preloaded keys
WARNING
This function works only on Mifare blocks that have been explicitly defined as counter (access condition ACC_BLOCK_COUNT) and that have been previously correctly initialized through SPROX_MifStWriteCounter. For more details, please refer to specific tag documentation.
RETURNS
MI_OK : success, data have been read MI_NOTAGERR : the required tag is not available in the RF field, or the supplied key has been denied MI_AUTHERR : access to the block has been denied Other code if internal or communication error has occured.
NOTES
The automatic key trying sequence is the same as in SPROX_MifStReadBlock.
SEE ALSO
SPROX_MifStReadCounter SPROX_MifStWriteCounter
NAME
SPROX_MifStHalt
WARNING
This function is deprecated. Use SPROX_A_Halt instead.
INPUTS
none
RETURNS
MI_OK : success, card halted Other code if internal or communication error has occured.
SEE ALSO
SPROX_A_Halt
NAME
SPROX_MifStReadBlock
DESCRIPTION
Read one 16-byte block of a Mifare tag, using given key or internally available keys for authentication.
INPUTS
const BYTE snr[4] : 4-byte UID of the Mifare card to read If NULL, the reader will work with currently selected tag BYTE bloc : address of the block to read BYTE data[16] : 16-byte buffer to receive the data const BYTE key[6] : The Mifare access key of the sector (either A or B) If NULL, the reader will try all the preloaded keys
WARNING
The number of blocks available on a Mifare tag depends on the tag type. For example, a Mifare classic 1k tag stores 64 blocks (address 0 to 63), a Mifare classic 4k tag stores 256 blocks (address 0 to 255). The last block of each Mifare classic sector is known as security block (or sector trailer) and holds the access keys to the sector. This functions allows reading of those specific blocks, but the keys are masked by Mifare integrated security features. For more details, please refer to specific tag documentation.
RETURNS
MI_OK : success, data have been read MI_NOTAGERR : the required tag is not available in the RF field, or the supplied key has been denied MI_AUTHERR : access to the block has been denied Other code if internal or communication error has occured.
NOTES
If key is not NULL, it is tried first as an 'A' key, then on failure as a 'B' key. If not Mifare key is supplied, the reader automatically tries every keys available in its memory. If key is NULL, the key trying sequence is performed in this order : - 4 'A' keys stored in reader's RAM (if no key has been loaded into RAM since reader's last reset, this is skipped), - 4 'B' keys stored in reader's RAM (if no key has been loaded into RAM since reader's last reset, this is skipped), - 16 'A' keys stored in the RC chipset's EEPROM - 16 'B' keys stored in the RC chipset's EEPROM Highest performance will be achieved when the right authentication key for this block is available at the beginning of this sequence ! After a succesfull read action, you can retrieve the key that has been used with SPROX_MifLastAuthKey.
SEE ALSO
SPROX_MifLoadKey SPROX_MifStReadSector
NAME
SPROX_MifStReadCounter
DESCRIPTION
Read a Mifare tag counter, using given key or internally available keys for authentication.
INPUTS
const BYTE snr[4] : 4-byte UID of the Mifare card If NULL, the reader will work with currently selected tag BYTE bloc : address of the block holding the counter SDWORD *value : pointer to receive current counter value const BYTE key[6] : The Mifare access key of the sector (either A or B) If NULL, the reader will try all the preloaded keys
WARNING
This function works only on Mifare blocks that have been explicitly defined as counter (access condition ACC_BLOCK_COUNT) and that have been previously correctly initialized through SPROX_MifStWriteCounter. For more details, please refer to specific tag documentation.
RETURNS
MI_OK : success, data have been read MI_NOTAGERR : the required tag is not available in the RF field, or the supplied key has been denied MI_AUTHERR : access to the block has been denied Other code if internal or communication error has occured.
NOTES
The automatic key trying sequence is the same as in SPROX_MifStReadBlock.
SEE ALSO
SPROX_MifStWriteCounter SPROX_MifStDecrementCounter
NAME
SPROX_MifStReadSector
DESCRIPTION
Read one sector of a Mifare tag, using given key or internally available keys for authentication.
INPUTS
const BYTE snr[4] : 4-byte UID of the Mifare card to read If NULL, the reader will work with currently selected tag BYTE sect : address of the sector to read BYTE data[48/240] : 48-byte or 240-byte buffer to receive the data const BYTE key[6] : The Mifare access key of the sector (either A or B) If NULL, the reader will try all the preloaded keys
WARNING
The number of sectors available on a Mifare tag depends on the tag type. The size of each sector depends both on the tag type and on the sector number. For example, a Mifare classic 1k tag has 16 sectors (address 0 to 15). Each sector has a size of 3+1 blocks (48 bytes of data). A Mifare classic 4k tag has 40 sectors (address 0 to 39). Sectors 0 to 31 have a size of 3+1 blocks (48 bytes of data), while sectors 32 to 39 have a size of 15+1 blocks (240 bytes of data). For more details, please refer to specific tag documentation. This function never returns the last block of each sector (security block or sector trailer). Explicitly use SPROX_MifStReadBlock to access those blocks.
RETURNS
MI_OK : success, data have been read MI_NOTAGERR : the required tag is not available in the RF field, or the supplied key has been denied MI_AUTHERR : access to the sector has been denied Other code if internal or communication error has occured.
NOTES
The automatic key trying sequence is the same as in SPROX_MifStReadBlock.
SEE ALSO
SPROX_MifStReadBlock
NAME
SPROX_MifStReadTag768
DESCRIPTION
Read a whole Mifare 1k tag (768 bytes), using internally available keys for authentication.
INPUTS
const BYTE snr[4] : 4-byte UID of the Mifare card to read If NULL, the reader will work with currently selected tag WORD *sectors : pointer to a WORD used as bit-array - in input, bit b(i) set means that sector i must be read - in output, bit b(i) set means that sector i has been successfully read BYTE data[768] : 768-byte buffer to receive the data
RETURNS
MI_OK : success, some data have been read. Check the *sectors bit- array to see which sectors have been read MI_NOTAGERR : the required tag is not available in the RF field, or the supplied key has been denied Other code if internal or communication error has occured.
NOTES
The automatic key trying sequence is the same as in SPROX_MifStWriteBlock.
SEE ALSO
SPROX_MifStReadBlock SPROX_MifStReadSector
NAME
SPROX_MifStSelectAgain
DESCRIPTION
Allow to re-select an ISO 14443-A card, provided its serial number (the card must be available in the RF field, either in the IDLE or HALTed state).
WARNING
This function is deprecated. Use SPROX_A_SelectAgain instead.
INPUTS
const BYTE snr[4] : 4-byte Unique ID of the card to wake-up
RETURNS
MI_OK : success, card selected MI_NOTAGERR : the required card is not available in the RF field Other code if internal or communication error has occured.
SEE ALSO
SPROX_A_SelectAgain
NAME
SPROX_MifStSelectAny
WARNING
This function is deprecated. Use SPROX_A_SelectAny instead.
INPUTS
BYTE snr[4] : 4-byte buffer to receive card's Unique ID BYTE atq[2] : 2-byte buffer to receive card's Answer To Query BYTE sak[1] : 1-byte buffer to receive card's Select AcKnowledge
RETURNS
MI_OK : success, card selected MI_NOTAGERR : no card available in the RF field Other code if internal or communication error has occured.
NOTES
Despite the name of the function, it doesn't check the returned card type (i.e., any ISO 14443-A card will be selected, not only Mifare cards). Please refer to Philips "Mifare Type Identification Procedure" documentation for atq and sak explanation. The Unique ID size is to be found in atq[0] : (atq[0] & 0xC0 == 0x00) --> single size UID (snr is 4-byte long) (atq[0] & 0xC0 == 0x40) --> double size UID (snr is 7-byte long) (atq[0] & 0xC0 == 0x80) --> triple size UID (snr is 10-byte long)
SEE ALSO
SPROX_A_SelectAny SPROX_MifStSelectIdle
NAME
SPROX_MifStSelectIdle
WARNING
This function is deprecated. Use SPROX_A_SelectIdle instead.
DESCRIPTION
Same as SPROX_MifStSelectAny, but will return only a card that is in the IDLE state. This allow discovering all ISO 14443-A available in the RF field : - call SPROX_MifStSelectIdle to discover the first card - halt this card calling SPROX_MifStHalt - call SPROX_MifStSelectIdle again to discover next card, and so on...
INPUTS
BYTE snr[4] : 4-byte buffer to receive card's Unique ID BYTE atq[2] : 2-byte buffer to receive card's Answer To Query BYTE sak[1] : 1-byte buffer to receive card's Select AcKnowledge
RETURNS
MI_OK : success, card selected MI_NOTAGERR : no IDLE card available in the RF field Other code if internal or communication error has occured.
NOTES
Despite the name of the function, it doesn't check the returned card type (i.e., any ISO 14443-A card will be selected, not only Mifare cards).
SEE ALSO
SPROX_A_SelectIdle SPROX_MifStSelectAny
NAME
SPROX_MifStUpdateAccessBlock
DESCRIPTION
Write one a "correctly formated" sector trailer in a Mifare tag.
INPUTS
const BYTE snr[4] : 4-byte UID of the Mifare card If NULL, the reader will work with currently selected tag BYTE sect : address of the sector (not of the block !!!) const BYTE old_key[6] : current Mifare access key of the sector (either B or A) If NULL, the reader will try all the preloaded keys const BYTE new_key_A[6] : new A access key of the sector const BYTE new_key_A[B] : new B access key of the sector BYTE ac0 : access condition for block 0 BYTE ac1 : access condition for block 1 BYTE ac2 : access condition for block 2 BYTE ac3 : access condition for block 3 (sector trailer itself)
WARNING
Please refer to specific tag documentation for explanation of ac0, ac1, ac2 and ac3, or use only the values enumerated below : - ACC_BLOCK_VALUE or ACC_BLOCK_COUNT for ac0, ac1 and ac2 - ACC_AUTH_TRANSPORT or ACC_AUTH_NORMAL for ac3 You can also read ClassicAccessConditions for more details. Setting bogus access conditions can irremediably lock the sector !
RETURNS
MI_OK : success, access condition have been written MI_NOTAGERR : the required tag is not available in the RF field, or the supplied key has been denied MI_AUTHERR : access to the sector has been denied Other code if internal or communication error has occured.
NOTES
The automatic key trying sequence is the same as in SPROX_MifStWriteBlock. If new_key_A is NULL, the reader will write Mifare default 'A' base key ( 0xA0,0xA1,0xA2,0xA3,0xA4,0xA5 ). If new_key_B is NULL, the reader will write Mifare default 'B' base key ( 0xB0,0xB1,0xB2,0xB3,0xB4,0xB5 ).
SEE ALSO
SPROX_MifLoadKey
NAME
SPROX_MifStWriteBlock
DESCRIPTION
Write one 16-byte block of a Mifare tag, using given key or internally available keys for authentication.
INPUTS
const BYTE snr[4] : 4-byte UID of the Mifare card to read If NULL, the reader will work with currently selected tag BYTE bloc : address of the block to write const BYTE data[16] : 16-byte buffer of data const BYTE key[6] : The Mifare access key of the sector (either B or A) If NULL, the reader will try all the preloaded keys
WARNING
The last block of each Mifare classic sector is known as security block (or sector trailer) and holds the access keys to the sector. This functions allows writing of those specific blocks, but a malformed block will irremediatly lock the sector. We strongly recommend to use SPROX_MifStUpdateAccessBlock instead. For more details, please refer to specific tag documentation.
RETURNS
MI_OK : success, data have been written MI_NOTAGERR : the required tag is not available in the RF field, or the supplied key has been denied MI_AUTHERR : access to the block has been denied Other code if internal or communication error has occured.
NOTES
If key is not NULL, it is tried first as an 'B' key, then on failure as a 'A' key. If not Mifare key is supplied, the reader automatically tries every keys available in its memory. If key is NULL, the key trying sequence is performed in this order : - 4 'B' keys stored in reader's RAM (if no key has been loaded into RAM since reader's last reset, this is skipped), - 4 'A' keys stored in reader's RAM (if no key has been loaded into RAM since reader's last reset, this is skipped), - 16 'B' keys stored in the RC chipset's EEPROM - 16 'A' keys stored in the RC chipset's EEPROM Highest performance will be achieved when the right authentication key for this block is available at the beginning of this sequence ! After a succesfull read action, you can retrieve the key that has been used with SPROX_MifLastAuthKey.
SEE ALSO
SPROX_MifLoadKey SPROX_MifStWriteSector
NAME
SPROX_MifStWriteCounter
DESCRIPTION
Write a Mifare tag counter, using given key or internally available keys for authentication.
INPUTS
const BYTE snr[4] : 4-byte UID of the Mifare card If NULL, the reader will work with currently selected tag BYTE bloc : address of the block holding the counter SDWORD value : new counter value const BYTE key[6] : The Mifare access key of the sector (either B or A) If NULL, the reader will try all the preloaded keys
WARNING
This function works only on Mifare blocks that have been explicitly defined as counter (access condition ACC_BLOCK_COUNT). For more details, please refer to specific tag documentation.
RETURNS
MI_OK : success, data have been read MI_NOTAGERR : the required tag is not available in the RF field, or the supplied key has been denied MI_AUTHERR : access to the block has been denied Other code if internal or communication error has occured.
NOTES
The automatic key trying sequence is the same as in SPROX_MifStWriteBlock.
SEE ALSO
SPROX_MifStReadCounter SPROX_MifStDecrementCounter
NAME
SPROX_MifStWriteSector
DESCRIPTION
Write one sector of a Mifare tag, using given key or internally available keys for authentication.
INPUTS
const BYTE snr[4] : 4-byte UID of the Mifare card to read If NULL, the reader will work with currently selected tag BYTE bloc : address of the sector to write const BYTE data[48/240] : 48-byte or 240-byte buffer of data const BYTE key[6] : The Mifare access key of the sector (either B or A) If NULL, the reader will try all the preloaded keys
WARNING
The number of sectors available on a Mifare tag depends on the tag type. The size of each sector depends both on the tag type and on the sector number. For more details, please see SPROX_MifStReadSector or refer to specific tag documentation. This function never writes the last block of each sector (security block or sector trailer). Explicitly use SPROX_MifStUpdateAccessBlock to write those blocks.
RETURNS
MI_OK : success, data have been written MI_NOTAGERR : the required tag is not available in the RF field, or the supplied key has been denied MI_AUTHERR : access to the sector has been denied Other code if internal or communication error has occured.
NOTES
The automatic key trying sequence is the same as in SPROX_MifStWriteBlock.
SEE ALSO
SPROX_MifStWriteBlock
NAME
SPROX_MifStWriteTag768
DESCRIPTION
Write a whole Mifare 1k tag (768 bytes), using internally available keys for authentication.
INPUTS
const BYTE snr[4] : 4-byte UID of the Mifare card to write If NULL, the reader will work with currently selected tag WORD *sectors : pointer to a WORD used as bit-array - in input, bit b(i) set means that sector i must be written - in output, bit b(i) set means that sector i has been successfully writen const BYTE data[768] : 768-byte buffer of data
RETURNS
MI_OK : success, some data have been written. Check the *sectors bit- array to see which sectors have been written MI_NOTAGERR : the required tag is not available in the RF field, or the supplied key has been denied Other code if internal or communication error has occured.
NOTES
The automatic key trying sequence is the same as in SPROX_MifStWriteBlock.
SEE ALSO
SPROX_MifStWriteBlock SPROX_MifStWriteSector
NAME
SPROX_MifWrite
DESCRIPTION
Write one 16-byte block of a Mifare card. No implicit authentication is performed ; this is typically the appropriate function to read from a Mifare UltraLight card.
WARNING
Mifare UltraLight cards accept this command, but only the 4 first bytes are actually written (same behaviour as SPROX_MifWrite4). On a Mifare Standard card, authentication is mandatory, use SPROX_MifStWriteBlock.
INPUTS
const BYTE snr[4] : 4-byte UID of the Mifare card to read If NULL, the reader will work with currently selected card BYTE address : address to write const BYTE data[16] : data to be written
RETURNS
MI_OK : success, data have been written MI_NOTAGERR : the required card is not available in the RF field Other code if internal or communication error has occured.
SEE ALSO
SPROX_MifWrite4 SPROX_MifRead SPROX_MifStWriteBlock
NAME
SPROX_MifWrite4
DESCRIPTION
Write one 4-byte block of a Mifare card. No implicit authentication is performed ; this is typically the appropriate function to read from a Mifare UltraLight card.
WARNING
On a Mifare Standard card, authentication is mandatory and only 16-byte blocks can be written ; use SPROX_MifStWriteBlock.
INPUTS
const BYTE snr[4] : 4-byte UID of the Mifare card to read If NULL, the reader will work with currently selected card BYTE address : address to write const BYTE data[4] : data to be written
RETURNS
MI_OK : success, data have been written MI_NOTAGERR : the required card is not available in the RF field Other code if internal or communication error has occured.
SEE ALSO
SPROX_MifWrite SPROX_MifStWriteBlock