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

  • [in] cmd_apdu: 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

  • [in] resp_apdu: 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

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

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

  • [inout] 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 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

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

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

  • [in] 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

  • [in] resp_apdu: 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.