CIE-PN532 API per Arduino¶

Di seguito è possibile trovare tutte le API presenti nel codice. Il risultato visualizzato è frutto dell’integrazione tra Doxygen e Sphinx.

Application Programming Interface¶

class cie_AtrReader¶

Public Functions

cie_AtrReader(cie_PN532 *cie)¶

bool detectLength(const cie_EFPath filePath, word *contentLength)¶

Detects the length of an Elementary File by reading its ATR encoded content.

Return

A value indicating whether the operation succeeded or not

Parameters

filePath: a structure indicating the parent Dedicated File (either ROOT_MF or CIE_DF), the selection mode (either SELECT_BY_EFID or SELECT_BY_SFI) and the file identifier (either a sfi or an efid)
contentLength: The pointer to the length value

Private Members

cie_PN532 *_cie¶

class cie_BerReader¶

Public Functions

cie_BerReader(cie_PN532 *cie)¶

bool readTriples(const cie_EFPath filePath, cieBerTripleCallbackFunc callback, word *length, const byte maxDepth)¶

Reads the triples hierarchy in the BER encoded file.

Return

A value indicating whether the operation succeeded or not

Parameters

filePath: a structure indicating the parent Dedicated File (either ROOT_MF or CIE_DF), the selection mode (either SELECT_BY_EFID or SELECT_BY_SFI) and the file identifier (either a sfi or an efid)
cieBerTripleCallbackFunc: A callback function that will be invoked each time a triple has been found
maxDepth: How deep down in the hierarchy we should look for triples

Private Functions

void resetCursor()¶: Resets the cursor to the binary content.

bool areEqual(byte *buffer1, byte length1, byte *buffer2, byte length2)¶

void readBinaryContent(const cie_EFPath filePath, const word offset, const word length)¶

bool readTriple(const cie_EFPath filePath, cie_BerTriple *triple, word *length)¶

Extracts informations from a single triple.

Return

A value indicating whether the operation succeeded or not

Parameters

filePath: a structure indicating the parent Dedicated File (either ROOT_MF or CIE_DF), the selection mode (either SELECT_BY_EFID or SELECT_BY_SFI) and the file identifier (either a sfi or an efid)
triple: The pointer to the triple object
length: The pointer to the outer length (tag octets + length octets + content length)

bool readTripleValue(const cie_BerTriple triple, byte *buffer)¶

Reads the binary content of a triple into the buffer.

Return

A value indicating whether the operation succeeded or not

Parameters

triple: The triple to be read
buffer: The pointer to the buffer where the binary content will be written to

bool detectLength(const cie_EFPath filePath, word *contentOffset, word *contentLength, byte *lengthOctets)¶

Detects the content length in a triple.

Return

A value indicating whether the operation succeeded or not

Parameters

filePath: a structure indicating the parent Dedicated File (either ROOT_MF or CIE_DF), the selection mode (either SELECT_BY_EFID or SELECT_BY_SFI) and the file identifier (either a sfi or an efid)
contentOffset: The pointer to binary content offset
contentLength: The pointer to binary content length
lengthOctets: The pointer to the number of length octets found in this triple)

bool detectTag(const cie_EFPath filePath, byte *classification, byte *encoding, word *type, byte *tagOctets)¶

Detects the tag type, class and content encoding.

Return

A value indicating whether the operation succeeded or not

Parameters

filePath: a structure indicating the parent Dedicated File (either ROOT_MF or CIE_DF), the selection mode (either SELECT_BY_EFID or SELECT_BY_SFI) and the file identifier (either a sfi or an efid)
classification: The pointer to the detected class value
encoding: The pointer to the detected binary content encoding (either primitive or constructed)
type: The pointer to the detected type value
tagOctets: The pointer to the number of tag octets found in this triple

bool readOctets(const cie_EFPath filePath, byte *buffer, const word offset, const word length)¶

Reads bytes from the file.

Return

A value indicating whether the operation succeeded or not

Parameters

filePath: a structure indicating the parent Dedicated File (either ROOT_MF or CIE_DF), the selection mode (either SELECT_BY_EFID or SELECT_BY_SFI) and the file identifier (either a sfi or an efid)
buffer: The pointer to the buffer which will contain the octets
offset: The offset from which we should read
length: The number of bytes to read

bool readOctets(const cie_EFPath filePath, byte *buffer, const word length)¶

Reads bytes from the file.

Return

A value indicating whether the operation succeeded or not

Parameters

filePath: a structure indicating the parent Dedicated File (either ROOT_MF or CIE_DF), the selection mode (either SELECT_BY_EFID or SELECT_BY_SFI) and the file identifier (either a sfi or an efid)
buffer: The pointer to the buffer which will contain the octets
length: The number of bytes to read

bool readOctet(const cie_EFPath filePath, byte *octet)¶

Reads bytes from the file.

Return

A value indicating whether the operation succeeded or not

Parameters

filePath: a structure indicating the parent Dedicated File (either ROOT_MF or CIE_DF), the selection mode (either SELECT_BY_EFID or SELECT_BY_SFI) and the file identifier (either a sfi or an efid)
octet: The pointer to the byte read

Private Members

cie_PN532 *_cie¶

word _currentOffset¶

class cie_BerTriple¶

Public Members

byte classification¶

byte encoding¶

unsigned int type¶

word offset¶

word contentOffset¶

word contentLength¶

byte depth¶

struct cie_EFPath¶

Public Members

byte df¶

byte selectionMode¶

word id¶

class cie_Key¶

Public Functions

~cie_Key()¶

Public Members

byte *exponent¶

byte exponentLength¶

byte *modulus¶

word modulusLength¶

class cie_Nfc¶

Subclassed by cie_Nfc_Adafruit

Public Functions

virtual void begin() = 0¶

virtual bool detectCard() = 0¶

virtual bool sendCommand(byte *command, byte commandLength, byte *response, word *responseLength) = 0¶

virtual void generateRandomBytes(byte *buffer, const word offset, const byte length) = 0¶

class cie_Nfc_Adafruit¶

Inherits from cie_Nfc

Public Functions

cie_Nfc_Adafruit()¶: Create with the typical breakout wiring, as described by Adafruit: https://learn.adafruit.com/adafruit-pn532-rfid-nfc/breakout-wiring.

cie_Nfc_Adafruit(byte clk, byte miso, byte mosi, byte ss)¶

Create with a customized wiring.

Parameters

clk: The CLK pin number
miso: The MISO pin number
mosi: The MOSI pin number
ss: The SS pin number

~cie_Nfc_Adafruit()¶: Frees resources.

void begin()¶: Initializes the PN532 board.

bool detectCard()¶

Attempts at detecting a card (will succeed if a card is present)

Return: A boolean value indicating whether a card was detected or not

bool sendCommand(byte *command, byte commandLength, byte *response, word *responseLength)¶

Sends an APDU command to the CIE via the PN532 terminal and checks whether the response has a valid status word.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

command: A pointer to the APDU command bytes
commandLength: Length of the command
response: A pointer to the buffer which will contain the response bytes
responseLength: The length of the desired response

void generateRandomBytes(byte *buffer, const word offset, const byte length)¶

Populates a buffer with random generated bytes.

Parameters

buffer: The pointer to a byte array
offset: The starting offset in the buffer
length: The number of random bytes to generate

Private Members

Adafruit_PN532 *_nfc¶

class cie_PN532¶

Public Functions

cie_PN532()¶: Create with the typical breakout wiring, as described by Adafruit: https://learn.adafruit.com/adafruit-pn532-rfid-nfc/breakout-wiring.

cie_PN532(byte clk, byte miso, byte mosi, byte ss)¶

Create with a customized wiring.

Parameters

clk: The CLK pin number
miso: The MISO pin number
mosi: The MOSI pin number
ss: The SS pin number

cie_PN532(cie_Nfc *nfc)¶: Create with a custom instance of the Adafruit_PN532 class.

~cie_PN532()¶: Frees resources.

void begin(void)¶: Initializes the PN532 board.

bool detectCard()¶: Dumps all values present in the CIE. Call this in your loop.

bool read_EF_DH(byte *contentBuffer, word *contentLength)¶

Reads the binary content the EF_DH elementary file.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

contentBuffer: The pointer to data containing the contents of the file
contentLength: The length of the file

bool read_EF_ATR(byte *contentBuffer, word *contentLength)¶

Reads the binary content of the EF_ATR elementary file.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

contentBuffer: The pointer to data containing the contents of the file
contentLength: The length of the file

bool read_EF_SN_ICC(byte *contentBuffer, word *contentLength)¶

Reads the binary content of the SN_ICC elementary file.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

contentBuffer: The pointer to data containing the contents of the file
contentLength: The length of the file

bool read_EF_ID_Servizi(byte *contentBuffer, word *contentLength)¶

Reads the binary content of the EF_ID_Servizi elementary file.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

contentBuffer: The pointer to data containing the contents of the file
contentLength: The length of the file

bool read_EF_Int_Kpub(cie_Key *key)¶

Reads the binary content of the EF.Int.Kpub elementary file.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

key: The pointer to a cie_Key object which will be populated with the modulus and exponent values

bool read_EF_Servizi_Int_Kpub(cie_Key *key)¶

Reads the binary content of the EF.Servizi_Int.Kpub elementary file.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

key: The pointer to a cie_Key object which will be populated with the modulus and exponent values

bool isCardValid()¶

Performs the challenge/response algorithm with the SDO.Int_Servizi.Kpub to check where this is a valid or cloned card.

Return: A boolean value indicating whether the card is valid or not

bool readElementaryFile(const cie_EFPath filePath, byte *contentBuffer, word *contentLength, const byte lengthStrategy)¶

Reads the binary content of an Elementary File given its Dedicated File and EFID or SFI identifier.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

df: The containing Dedicated File (either ROOT_MF or CIE_DF)
filePath: a structure indicating the parent Dedicated File (either ROOT_MF or CIE_DF), the selection mode (either SELECT_BY_EFID or SELECT_BY_SFI) and the file identifier (either a sfi or an efid)
contentBuffer: Pointer to the response data
response: The maximum desired length of the response
lengthStrategy: How to determine the length of the file (either FIXED_LENGTH or AUTODETECT_BER_LENGTH or AUTODETECT_ATR_LENGTH)

bool readBinaryContent(const cie_EFPath filePath, byte *contentBuffer, word offset, const word contentLength)¶

Reads the binary content of the currently selected Elementary File.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

filePath: a structure indicating the parent Dedicated File (either ROOT_MF or CIE_DF), the selection mode (either SELECT_BY_EFID or SELECT_BY_SFI) and the file identifier (either a sfi or an efid)
contentBuffer: The pointer to the data buffer
contentLength: The number of bytes to read

bool readKey(const cie_EFPath filePath, cie_Key *key)¶

Reads the key content (BER encoded modulus and exponent) from the indicated Elementary File.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

filePath: a structure indicating the parent Dedicated File (either ROOT_MF or CIE_DF), the selection mode (either SELECT_BY_EFID or SELECT_BY_SFI) and the file identifier (either a sfi or an efid)
key: A pointer to a which object which will be populated with the modulus and exponent

void printHex(byte *buffer, const word length)¶

Prints an hex representation of a buffer.

Parameters

buffer: The pointer to the byte buffer
length: The length of the buffer

bool print_EF_SOD(word *contentLength)¶

Print the binary content of the EF_SOD elementary file.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

contentLength: The reported length of the file

bool parse_EF_SOD(cieBerTripleCallbackFunc callback)¶

Parses the BER content of the EF_SOD file.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

callback: A function which will be invoked when a new triple has been read

Public Members

bool verbose¶

Private Functions

bool sendCommand(byte *command, const byte commandLength, byte *response, word *responseLength)¶

Sends an APDU command to the CIE via the PN532 terminal and checks whether the response has a valid status word.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

command: A pointer to the APDU command bytes
commandLength: Length of the command
response: A pointer to the buffer which will contain the response bytes
responseLength: The length of the desired response

void initFields()¶: Set default values to some private fields.

bool sendCommand(byte *command, const word commandLength)¶

Sends an APDU command which won’t return any data to the CIE via the PN532 terminal and checks whether the response has a valid status word.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

command: A pointer to the APDU command bytes
commandLength: Length of the command

bool select_SDO_Servizi_Int_Kpriv()¶

Selects the SDO.Servizi_Int.Kpriv private key for internal authentication.

Return: A boolean value indicating whether the operation succeeded or not

bool ensureSelected(const cie_EFPath filePath)¶

bool ensureDedicatedFileIsSelected(const byte df)¶

Selects a dedicated file in the IAS application.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

df: The Dedicated File (either ROOT_MF or CIE_DF)

bool ensureElementaryFileIsSelected(const cie_EFPath filePath)¶

Ensures an Elementary file is selected (does nothing if it was already selected)

Return

A boolean value indicating whether the operation succeeded or not

Parameters

filePath: a structure indicating the parent Dedicated File (either ROOT_MF or CIE_DF), the selection mode (either SELECT_BY_EFID or SELECT_BY_SFI) and the file identifier (either a sfi or an efid)

bool ensureSdoIsSelected(const cie_EFPath filePath)¶

Ensures an elementary file is selected by its SDO ID, that is by sending an MSE mode SET (with AT template) command.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

filePath: a structure indicating the parent Dedicated File (either ROOT_MF or CIE_DF), the selection mode (either SELECT_BY_EFID or SELECT_BY_SFI) and the file identifier (either a sfi or an efid)

bool selectIasApplication(void)¶

Selects the IAS Application.

Return: A value indicating whether the operation succeeded or not

bool selectRootMasterFile(void)¶

Selects the ROOT Master File.

Return: A boolean value indicating whether the operation succeeded or not

bool selectCieDedicatedFile(void)¶

Selects the CIE DF.

Return: A value indicating whether the operation succeeded or not

bool determineLength(const cie_EFPath filePath, word *contentLength, const byte lengthStrategy)¶

Sets the length value of a currently selected Elementary File.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

filePath: a structure indicating the parent Dedicated File (either ROOT_MF or CIE_DF), the selection mode (either SELECT_BY_EFID or SELECT_BY_SFI) and the file identifier (either a sfi or an efid)
contentLength: The pointer to the length value
lengthStrategy: The chosen strategy by user (either AUTODETECT_BER_LENGTH or FIXED_LENGTH)

bool hasSuccessStatusWord(byte *response, const word responseLength)¶

Reads the EF contents by its SFI under the current DF.

Return

A value indicating whether the operation succeeded or not

Parameters

response: Pointer to the response data
responseLength: The length of the response

word clamp(const word value, const byte maxValue)¶

Ensures a value is less or equal than a max value.

Return

The clamped value

Parameters

value: The value that should be checked
maxValue: The maximum value

bool establishSecureMessaging()¶

Establishes a secure messaging context by performing mutual authentication.

Return: A boolean value indicating whether the operation succeeded or not

bool getChallenge(byte *contentBuffer, word *contentLength)¶

Reads the binary content of an Elementary File given its Dedicated File and EFID or SFI identifier.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

contentBuffer: Pointer to the response data
contentLength: The length of the response

bool mutualAuthenticate(byte *snIccBuffer, const byte snIccBufferLength, byte *rndIccBuffer, const byte rndIccBufferLength)¶

Performs mutual authentication.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

snIccBuffer: A pointer to the buffer containing the SN.ICC (card serial number)
snIccBufferLength: The length of the SN.ICC buffer
rndIccBuffer: A pointer to the buffer containing the RND.ICC (a random number generated by the card chip)
rndIccBufferLength: The length of the RND.ICC buffer

bool internalAuthenticate(byte *responseBuffer, word *responseLength, byte *challenge, const byte challengeLength)¶

Performs internal authentication.

Return

A boolean value indicating whether the operation succeeded or not

Parameters

responseBuffer: A pointer to the buffer which will contain the response for the internal authentication command
responseLength: The length of the response
challenge: A pointer to the challenge
challengeLength: The length of the provided challenge

bool verifyInternalAuthenticateResponse(cie_Key *pubKey, byte *cypher, const word cypherLength, const byte *message, const word messageLength)¶

Verify if the response returned for an INTERNAL AUTHENTICATE command is valid.

Return

A boolean value indicating whether the response was valid or not

Parameters

pubKey: A pointer to public key that is going to be used for decryption
cypher: The encrypted response returned for the INTERNAL AUTHENTICATE command
cypherLength: The length of the cypher, should be the same size of the public key modulus
message: A pointer to the original message to be verified
messageLength: The length of the message

void calculateSk(const byte valueType, byte *kIfd, byte *kIcc, byte *sk, byte *skLength)¶

Private Members

cie_Nfc *_nfc¶

cie_BerReader *_berReader¶

cie_AtrReader *_atrReader¶

byte _currentDedicatedFile¶

unsigned long _currentElementaryFile¶

file cie_AtrReader.cpp

#include «cie_AtrReader.h»

Reads and parses an Atr encoded binary content

Author: Developers Italia BSD (see License)

Defines

PN532DEBUGPRINT¶

file cie_AtrReader.h

#include «cie_PN532.h»#include «cie_EFPath.h»

Reads and parses an ATR encoded binary content

Author: Developers Italia BSD (see License)

file cie_BerReader.cpp

#include «cie_BerReader.h»

Reads and parses a BER encoded binary content

Author: Developers Italia BSD (see License)

Defines

PN532DEBUGPRINT

file cie_BerReader.h

#include «cie_EFPath.h»#include «cie_BerTriple.h»#include «cie_PN532.h»

Reads and parses a BER encoded binary content

Author: Developers Italia BSD (see License)

Defines

BER_READER_MAX_OFFSET¶

BER_READER_MAX_LENGTH¶

BER_READER_MAX_COUNT¶

file cie_BerTriple.h

#include <Arduino.h>

Definition of the cie_BerTriple structure used to describe an individual piece of information in BER encoded binary content

Author: Developers Italia BSD (see License)

Typedefs

typedef bool (*cieBerTripleCallbackFunc)(cie_BerTriple *)¶

file cie_EFPath.h

#include <Arduino.h>

Definition of the cie_EFPath structure used to describe paths in the CIE filesystem

Author: Developers Italia BSD (see License)

file cie_Key.cpp

#include «cie_Key.h»

Implementation of the cie_Key class describing an encryption key

Author: Developers Italia BSD (see License)

file cie_Key.h

#include <Arduino.h>

Definition of the cie_Key class describing an encryption key

Author: Developers Italia BSD (see License)

file cie_Nfc.h

#include <Arduino.h>

An interface needed by cie_PN532 as a decoupling abstraction to the underlying PN532 communication library

Author: Developers Italia BSD (see License)

file cie_Nfc_Adafruit.cpp

#include «cie_Nfc_Adafruit.h»

Implementation of the cie_Nfc abstract class using the Adafruit_PN532 library

Author: Developers Italia BSD (see License)

Defines

PN532DEBUGPRINT

file cie_Nfc_Adafruit.h: #include <Adafruit_PN532.h>#include «cie_Nfc.h»

file cie_PN532.cpp

#include «cie_PN532.h»

This is a library for the PN532 NFC/RFID breakout boards This library works with the Adafruit NFC breakout -> https://www.adafruit.com/products/364

Author: Developers Italia BSD (see License)

Check out the links above for our tutorials and wiring diagrams These chips use SPI or I2C to communicate. This library uses SPI to communicate.

Defines

PN532DEBUGPRINT

Functions

void calculateSk(const byte valueType, byte *kIfd, byte *kIcc, byte *sk, byte *skLength)¶

Calculates the SKENC or the SKMAC session key from the K.IFD and K.ICC random values.

Parameters

valueType: The type of the value (either SK_ENC or SK_MAC)
kIfd: The pointer to the K.IFD generated by the terminal (must be of K_LENGTH bytes)
kIcc: The pointer to the K.ICC generated by the card (must be of K_LENGTH bytes)
sk: A pointer to a buffer which will contain the computed SKENC or SKMAC
skLength: The reported length of the session key

file cie_PN532.h

#include <BigNumber.h>#include «cie_EFPath.h»#include «cie_AtrReader.h»#include «cie_BerReader.h»#include «cie_Key.h»#include «cie_Nfc_Adafruit.h»

This is a library for the PN532 NFC/RFID breakout boards This library works with the Adafruit NFC breakout -> https://www.adafruit.com/products/364

Author: Developers Italia BSD (see License)

Check out the links above for our tutorials and wiring diagrams These chips use SPI or I2C to communicate. This library uses SPI to communicate.

Defines

PN532_IRQ¶

PN532_RESET¶

EF_ID_SERVIZI_LENGTH¶

EF_SN_ICC_LENGTH¶

PAGE_LENGTH¶

READ_FROM_START¶

STATUS_WORD_LENGTH¶

CHALLENGE_LENGTH¶

K_LENGTH¶

SK_LENGTH¶

FIXED_LENGTH¶

AUTODETECT_BER_LENGTH¶

AUTODETECT_ATR_LENGTH¶

SELECT_BY_EFID¶

SELECT_BY_SFI¶

SELECT_BY_SDOID¶

NULL_DF¶

NULL_EF¶

ROOT_MF¶

CIE_DF¶

SK_ENC¶

SK_MAC¶