TABLE OF CONTENTS

 

[Modules] Mifare

NAME

   SpringProxAPI :: Mifare

DESCRIPTION

   Implementation of Philips Mifare functions
   (Mifare Standard and Mifare UltraLite)

[Definitions] ACC_AUTH_NORMAL

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.

[Definitions] ACC_AUTH_TRANSPORT

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.

[Definitions] ACC_BLOCK_COUNT

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.

[Definitions] ACC_BLOCK_VALUE

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.

[Functions] SPROX_MifLastAuthKey

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

[Functions] SPROX_MifLoadKey

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

[Functions] SPROX_MifRead

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

[Functions] SPROX_MifStDecrementCounter

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

[Functions] SPROX_MifStHalt

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

[Functions] SPROX_MifStReadBlock

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

[Functions] SPROX_MifStReadCounter

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

[Functions] SPROX_MifStReadSector

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

[Functions] SPROX_MifStReadTag768

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

[Functions] SPROX_MifStSelectAgain

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

[Functions] SPROX_MifStSelectAny

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

[Functions] 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

[Functions] SPROX_MifStUpdateAccessBlock

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

[Functions] SPROX_MifStWriteBlock

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

[Functions] SPROX_MifStWriteCounter

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

[Functions] SPROX_MifStWriteSector

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

[Functions] SPROX_MifStWriteTag768

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

[Functions] SPROX_MifWrite

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

[Functions] SPROX_MifWrite4

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

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