NFC T4T APDU reader and writer

Application protocol data units (APDUs) are special communication units that are used when exchanging data with a Type 4 Tag platform. Command APDUs (C-APDUs) are the commands sent from the NFC reader, while response APDUs (R-APDUs) are the responses to a specific command received by NFC reader 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 NFC Reader ST25R3911B 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

APDU reader and writer

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:

NFC_T4T_APDU_COMM_INS_SELECT = 0xA4

Code used for selecting EF or NDEF application.

NFC_T4T_APDU_COMM_INS_READ = 0xB0

Code used for selecting EF or NDEF application.

NFC_T4T_APDU_COMM_INS_UPDATE = 0xD6

Code used for selecting EF or NDEF application.

Functions

static 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: Pointer to C-APDU descriptor.

static 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: Pointer to R-APDU descriptor.

int nfc_t4t_apdu_comm_encode(const struct nfc_t4t_apdu_comm *cmd_apdu, u8_t *raw_data, u16_t *len)

Encode C-APDU.

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

Parameters
  • cmd_apdu: Pointer to the C-APDU descriptor.
  • raw_data: Pointer to the buffer with encoded C-APDU.
  • len: Size of the available memory for the C-APDU as input. Size of the generated C-APDU as output.
Return Value
  • 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 u8_t *raw_data, u16_t len)

Decode R-APDU.

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

Parameters
  • resp_apdu: Pointer to the R-APDU descriptor.
  • raw_data: Pointer to the buffer with encoded R-APDU.
  • len: Size of of the buffer with encoded R-APDU.
Return Value
  • 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: Pointer to the R-APDU descriptor.

struct nfc_t4t_apdu_data
#include <apdu.h>

APDU data field descriptor.

Public Members

u16_t len

Data field length.

u8_t *buff

Pointer to data field.

struct nfc_t4t_apdu_comm
#include <apdu.h>

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

Public Members

nfc_t4t_apdu_comm_ins instruction

The chosen code of instruction.

u16_t parameter

Parameters associated with the instruction code.

struct nfc_t4t_apdu_data data

Optional data fields (Lc + data bytes).

u16_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

u16_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.