APDU reader and writer

Application protocol data units (APDUs) are special communication units that are defined in ISO/IEC 7816-4. The subset of these commands that is used to interact with a Type 4 Tag is implemented in this library.

Command APDUs (C-APDUs) are the commands sent from the polling device, while response APDUs (R-APDUs) are the responses to a specific command received by the polling device from the tag.

The APDU reader/writer module provides functions to encode a C-APDU according to its descriptor and to decode a raw R-APDU data into the appropriate descriptor.

This library can be used with the NFC Reader ST25R3911B library to exchange NFC Type 4 Tag data.

APDU types

There are three types of APDU that are relevant for a Type 4 Tag platform:

APDU type	Usage
Select	Selecting applications or files.
ReadBinary	Reading data from a file.
UpdateBinary	Writing data to a file.

C-APDU and R-APDU format

A C-APDU consists of the following fields:

Field	Length	Required	Description
CLA	1 byte	yes	Specifies the security level of the message.
INS	1 byte	yes	Specifies the command type to process.
P1	1 byte	yes	Specifies the first parameter for the chosen command type.
P2	1 byte	yes	Specifies the second parameter for the chosen command type.
Lc	1 or 3 byte	no	Specifies the data length.
Data	Lc bytes	no	Required if LC field is present. Contains payload of C-APDU.
Le	1 or 2 bytes	no	Specifies the expected response body length of R-APDU.

An R-APDU consists of the following fields:

Field	Length	Required	Description
Response body	variable	no	Carries the data of the R-APDU.
SW1	1 byte	yes	Specifies the first status word.
SW2	1 byte	yes	Specifies the second status word.

API documentation

Header file: include/nfc/t4t/apdu.h

Source file: subsys/nfc/t4t/apdu.c

group nfc_t4t_apdu

APDU reader and writer for Type 4 Tag communication.

Defines

NFC_T4T_APDU_CLASS_BYTE_NO_SECURE_MSG

Class byte indicating no secure messaging, used in C-APDU.

Enums

enum nfc_t4t_apdu_comm_ins

Possible instruction codes in C-APDU.

Values:

enumerator NFC_T4T_APDU_COMM_INS_SELECT

Code used for selecting EF or NDEF application.

enumerator NFC_T4T_APDU_COMM_INS_READ

Code used for selecting EF or NDEF application.

enumerator NFC_T4T_APDU_COMM_INS_UPDATE

Code used for selecting EF or NDEF application.

Functions

static inline void nfc_t4t_apdu_comm_clear(struct nfc_t4t_apdu_comm *cmd_apdu)

Clear a C-APDU descriptor and restore its default values.

Parameters

• cmd_apdu – [in] Pointer to C-APDU descriptor.

static inline void nfc_t4t_apdu_resp_clear(struct nfc_t4t_apdu_resp *resp_apdu)

Clearing an R-APDU descriptor and restore its default values.

Parameters

• resp_apdu – [in] Pointer to R-APDU descriptor.

int nfc_t4t_apdu_comm_encode(const struct nfc_t4t_apdu_comm *cmd_apdu, uint8_t *raw_data, uint16_t *len)

Encode C-APDU.

This function encodes C-APDU according to the provided descriptor.

Parameters

• cmd_apdu – [in] Pointer to the C-APDU descriptor.

• raw_data – [out] Pointer to the buffer with encoded C-APDU.

• len – [inout] Size of the available memory for the C-APDU as input. Size of the generated C-APDU as output.

Returns 0

If the operation was successful. Otherwise, a (negative) error code is returned.

int nfc_t4t_apdu_resp_decode(struct nfc_t4t_apdu_resp *resp_apdu, const uint8_t *raw_data, uint16_t len)

Decode R-APDU.

This function decodes buffer with encoded R-APDU and stores results in the R-APDU descriptor.

Parameters

• resp_apdu – [out] Pointer to the R-APDU descriptor.

• raw_data – [in] Pointer to the buffer with encoded R-APDU.

• len – [in] Size of of the buffer with encoded R-APDU.

Returns 0

If the operation was successful. Otherwise, a (negative) error code is returned.

void nfc_t4t_apdu_resp_printout(const struct nfc_t4t_apdu_resp *resp_apdu)

Print an R-APDU descriptor.

This function prints an R-APDU descriptor.

Parameters

• resp_apdu – [in] Pointer to the R-APDU descriptor.

struct nfc_t4t_apdu_data

#include <apdu.h>

APDU data field descriptor.

Public Members

uint16_t len

Data field length.

uint8_t *buff

Pointer to data field.

struct nfc_t4t_apdu_comm

#include <apdu.h>

Command Application Protocol Data Unit (C-APDU) descriptor.

Public Members

enum nfc_t4t_apdu_comm_ins instruction

The chosen code of instruction.

uint16_t parameter

Parameters associated with the instruction code.

struct nfc_t4t_apdu_data data

Optional data fields (Lc + data bytes).

uint16_t resp_len

Optional response length field (Le).

struct nfc_t4t_apdu_resp

#include <apdu.h>

Response Application Protocol Data Unit (R-APDU) descriptor.

Public Members

uint16_t status

Mandatory status field.

struct nfc_t4t_apdu_data data

Optional data field.

Parameters for selecting instruction code in C-APDU

group nfc_t4t_apdu_select

instruction code in C-APDU

Defines

NFC_T4T_APDU_SELECT_BY_FILE_ID

Select by file identifier, first or only occurrence.

NFC_T4T_APDU_SELECT_BY_NAME

Select by name, first or only occurrence.

Status codes contained in R-APDU

group nfc_t4t_apdu_status

Defines

NFC_T4T_APDU_RAPDU_STATUS_CMD_COMPLETED

Command completed successfully.

NFC_T4T_APDU_RAPDU_STATUS_SEL_ITEM_NOT_FOUND

Selected item has not been found.