Description

Encapsulation of a smartcard command Application Protocol Data Unit (APDU)

The command APDU is the communication message sent from a card reader to a smartcard. This class encapsulates a command APDU, ensuring its validity at construction-time, and guaranteeing it remains valid for the lifetime of the object. The get (GrabbaCommandAPDU) method provides read-only access to the raw APDU data.

Additional information may be found at: https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit

The full specification of the format is found in ISO/IEC 7816-3 and ISO/IEC 7816-4.

Invariant: Stored fields are all within range for the APDU format.

Note: All property values are passed by copy; a new copy of the value will be generated each time a property is read.

Thread safety: This class is immutable, and thus fully thread-safe.

See also: GrabbaResponseAPDU for the response equivalent, and GrabbaSmartcardAPI for related functionality

Inheritance diagram for GrabbaCommandAPDU:

Instance Methods
(NSData *_Nonnull)	- get
	Copy the entire APDU in byte-array format. More...

(NSData *_Nonnull)	- header
	Copy the four header fields CLA, INS, P1 and P2 in byte-array format. More...

(NSString *_Nonnull)	- hexDump
	Obtain a hex dump of the entire APDU. More...

(instancetype _Nullable)	- init
	Initialise a null APDU - only compulsory fields are present, and all four header fields are set to zero. More...

(instancetype _Nullable)	- initFromStream:
	Extract APDU data from a byte stream. More...

(instancetype _Nullable)	- initWithCLA:INS:P1:P2:
	Initialise an APDU as per ISO/IEC 7816-3 case 1 (i.e. no Lc, Le or command-data fields) More...

(instancetype _Nullable)	- initWithCLA:INS:P1:P2:data:
	Initialise an APDU as per ISO/IEC 7816-3 case 3 (i.e. Lc and command-data fields present, but no Le field) More...

(instancetype _Nullable)	- initWithCLA:INS:P1:P2:data:Ne:
	Construct an APDU as per ISO/IEC 7816-3 case 4 (i.e. Lc, command-data and Le fields all present) More...

(instancetype _Nullable)	- initWithCLA:INS:P1:P2:Ne:
	Initialise an APDU as per ISO/IEC 7816-3 case 2 (i.e. Le field present, but no Lc or command-data fields) More...

Class Methods
(instancetype _Nullable)	+ commandAPDU
	Allocate and initialise a null APDU - only compulsory fields are present, and all four header fields are set to zero. More...

(instancetype _Nullable)	+ commandAPDU_FromStream:
	Allocate and initialise an APDU, extracting the data from a byte stream. More...

(instancetype _Nullable)	+ commandAPDU_WithCLA:INS:P1:P2:
	Allocate and initialise an APDU as per ISO/IEC 7816-3 case 1 (i.e. no Lc, Le or command-data fields) More...

(instancetype _Nullable)	+ commandAPDU_WithCLA:INS:P1:P2:data:
	Allocate and initialise an APDU as per ISO/IEC 7816-3 case 3 (i.e. Lc and command-data fields present, but no Le field) More...

(instancetype _Nullable)	+ commandAPDU_WithCLA:INS:P1:P2:data:Ne:
	Allocate and initialise an APDU as per ISO/IEC 7816-3 case 4 (i.e. Lc, command-data and Le fields all present) More...

(instancetype _Nullable)	+ commandAPDU_WithCLA:INS:P1:P2:Ne:
	Allocate and initialise an APDU as per ISO/IEC 7816-3 case 2 (i.e. Le field present, but no Lc or command-data fields) More...

(size_t)	+ maxCommandLength
	Maximum permitted command length in bytes (excluding header and length fields) More...

Properties
uint8_t	CLA
	Instruction class (CLA) - the type of smartcard command, e.g. interindustry or proprietary. More...

NSData *_Nonnull	commandData
	Command data for this APDU if any, otherwise an empty array. More...

BOOL	commandDataPresent
	Are the command data and encoded command data length (Lc) fields present in this APDU? More...

uint8_t	INS
	Instruction code (INS) - indication of the specific smartcard command, e.g. "write data". More...

NSData *_Nonnull	Lc
	Encoded length of command data (Lc), represented as a byte array; will be empty if Nc = 0. More...

NSData *_Nonnull	Le
	Encoded maximum expected response length (Le), represented as a byte array; will be empty if Ne = 0. More...

BOOL	LePresent
	Is the encoded maximum expected response length (Le) field present in this APDU? More...

uint16_t	Nc
	Length in bytes of the command data (Nc) if there is any, otherwise zero. More...

uint32_t	Ne
	Maximum number of response bytes expected (Ne), range 0 to maxResponseLength inclusive. More...

uint8_t	P1
	First parameter byte (P1) - e.g. offset into file at which to write the data. More...

uint8_t	P2
	Second parameter byte (P2) - e.g. offset into file at which to write the data. More...

BOOL	shortEncoding
	Is this APDU using the "short" encodings for the Lc and Le fields (if present) More...

Method Documentation

◆ commandAPDU()

+ (instancetype _Nullable) commandAPDU

Allocate and initialise a null APDU - only compulsory fields are present, and all four header fields are set to zero.

◆ commandAPDU_FromStream:()

+ (instancetype _Nullable) commandAPDU_FromStream: (NSData *_Nonnull) stream

Allocate and initialise an APDU, extracting the data from a byte stream.

The first four bytes of the stream are used to construct the CLA, INS, P1 and P2 fields respectively.

If no data is present beyond the first four bytes, then Nc = Ne = 0 and parsing is considered successful.

Otherwise, the remaining bytes are used to populate the optional Lc field, the optional command-data field, and the optional Le field. The following combinations are tested, in the following order:

Short Lc, Nc bytes of command data, no Le
Short Lc, Nc bytes of command data, short Le
Extended Lc, Nc bytes of command data, no Le
Extended Lc, Nc bytes of command data, extended Le
No Lc, no command data, short Le
No Lc, no command data, extended Le If none of the combinations match then parsing is considered to have failed.

Parameters

stream APDU data stream; must contain a valid command APDU (and only that APDU - no additional leading or trailing bytes are permitted)

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ commandAPDU_WithCLA:INS:P1:P2:()

+ (instancetype _Nullable) commandAPDU_WithCLA:	(unsigned)	CLA
INS:	(unsigned)	INS
P1:	(unsigned)	P1
P2:	(unsigned)	P2

Allocate and initialise an APDU as per ISO/IEC 7816-3 case 1 (i.e. no Lc, Le or command-data fields)

Parameters

CLA	Instruction class - indicates the type of command, e.g. interindustry or proprietary, valid range 0-254
INS	Instruction code - indicates the specific command, e.g. "write data", valid range 0-255
P1	First parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255
P2	Second parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ commandAPDU_WithCLA:INS:P1:P2:data:()

+ (instancetype _Nullable) commandAPDU_WithCLA:	(unsigned)	CLA
INS:	(unsigned)	INS
P1:	(unsigned)	P1
P2:	(unsigned)	P2
data:	(NSData *_Nonnull)	data

Allocate and initialise an APDU as per ISO/IEC 7816-3 case 3 (i.e. Lc and command-data fields present, but no Le field)

Parameters

CLA	Instruction class - indicates the type of command, e.g. interindustry or proprietary, valid range 0-254
INS	Instruction code - indicates the specific command, e.g. "write data", valid range 0-255
P1	First parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255
P2	Second parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255
data	Command data; must be of length 1-65535.

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ commandAPDU_WithCLA:INS:P1:P2:data:Ne:()

+ (instancetype _Nullable) commandAPDU_WithCLA:	(unsigned)	CLA
INS:	(unsigned)	INS
P1:	(unsigned)	P1
P2:	(unsigned)	P2
data:	(NSData *_Nonnull)	data
Ne:	(unsigned)	Ne

Allocate and initialise an APDU as per ISO/IEC 7816-3 case 4 (i.e. Lc, command-data and Le fields all present)

Parameters

CLA	Instruction class - indicates the type of command, e.g. interindustry or proprietary, valid range 0-254
INS	Instruction code - indicates the specific command, e.g. "write data", valid range 0-255
P1	First parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255
P2	Second parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255
data	Command data; must be of length 1-65535.
Ne	The maximum number of response bytes expected, valid range 1-65536

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ commandAPDU_WithCLA:INS:P1:P2:Ne:()

+ (instancetype _Nullable) commandAPDU_WithCLA:	(unsigned)	CLA
INS:	(unsigned)	INS
P1:	(unsigned)	P1
P2:	(unsigned)	P2
Ne:	(unsigned)	Ne

Allocate and initialise an APDU as per ISO/IEC 7816-3 case 2 (i.e. Le field present, but no Lc or command-data fields)

Parameters

CLA	Instruction class - indicates the type of command, e.g. interindustry or proprietary, valid range 0-254
INS	Instruction code - indicates the specific command, e.g. "write data", valid range 0-255
P1	First parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255
P2	Second parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255
Ne	The maximum number of response bytes expected, valid range 1-65536

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ get()

- (NSData* _Nonnull) get

Copy the entire APDU in byte-array format.

Returns: Entire APDU, including CLA, INS, P1 and P2 fields, and possibly also including Lc, command-data and/or Le fields

See also: For information about the internal structure of this APDU, refer to commandDataPresent, LePresent and shortEncoding.

◆ header()

- (NSData* _Nonnull) header

Copy the four header fields CLA, INS, P1 and P2 in byte-array format.

Returns: First four bytes of the APDU

◆ hexDump()

- (NSString* _Nonnull) hexDump

Obtain a hex dump of the entire APDU.

Returns: Hex dump of the APDU (i.e. output of get), with a space after each byte

◆ init()

- (instancetype _Nullable) init

Initialise a null APDU - only compulsory fields are present, and all four header fields are set to zero.

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ initFromStream:()

- (instancetype _Nullable) initFromStream: (NSData *_Nonnull) stream

Extract APDU data from a byte stream.

The first four bytes of the stream are used to construct the CLA, INS, P1 and P2 fields respectively.

If no data is present beyond the first four bytes, then Nc = Ne = 0 and parsing is considered successful.

Otherwise, the remaining bytes are used to populate the optional Lc field, the optional command-data field, and the optional Le field. The following combinations are tested, in the following order:

Short Lc, Nc bytes of command data, no Le
Short Lc, Nc bytes of command data, short Le
Extended Lc, Nc bytes of command data, no Le
Extended Lc, Nc bytes of command data, extended Le
No Lc, no command data, short Le
No Lc, no command data, extended Le If none of the combinations match then parsing is considered to have failed.

Parameters

stream APDU data stream; must contain a valid command APDU (and only that APDU - no additional leading or trailing bytes are permitted)

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ initWithCLA:INS:P1:P2:()

- (instancetype _Nullable) initWithCLA:	(unsigned)	CLA
INS:	(unsigned)	INS
P1:	(unsigned)	P1
P2:	(unsigned)	P2

Initialise an APDU as per ISO/IEC 7816-3 case 1 (i.e. no Lc, Le or command-data fields)

Parameters

CLA	Instruction class - indicates the type of command, e.g. interindustry or proprietary, valid range 0-254
INS	Instruction code - indicates the specific command, e.g. "write data", valid range 0-255
P1	First parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255
P2	Second parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ initWithCLA:INS:P1:P2:data:()

- (instancetype _Nullable) initWithCLA:	(unsigned)	CLA
INS:	(unsigned)	INS
P1:	(unsigned)	P1
P2:	(unsigned)	P2
data:	(NSData *_Nonnull)	data

Initialise an APDU as per ISO/IEC 7816-3 case 3 (i.e. Lc and command-data fields present, but no Le field)

Parameters

CLA	Instruction class - indicates the type of command, e.g. interindustry or proprietary, valid range 0-254
INS	Instruction code - indicates the specific command, e.g. "write data", valid range 0-255
P1	First parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255
P2	Second parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255
data	Command data; must be of length 1-65535.

◆ initWithCLA:INS:P1:P2:data:Ne:()

- (instancetype _Nullable) initWithCLA:	(unsigned)	CLA
INS:	(unsigned)	INS
P1:	(unsigned)	P1
P2:	(unsigned)	P2
data:	(NSData *_Nonnull)	data
Ne:	(unsigned)	Ne

Construct an APDU as per ISO/IEC 7816-3 case 4 (i.e. Lc, command-data and Le fields all present)

Parameters

CLA	Instruction class - indicates the type of command, e.g. interindustry or proprietary, valid range 0-254
INS	Instruction code - indicates the specific command, e.g. "write data", valid range 0-255
P1	First parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255
P2	Second parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255
data	Command data; must be of length 1-65535.
Ne	The maximum number of response bytes expected, valid range 1-65536

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ initWithCLA:INS:P1:P2:Ne:()

- (instancetype _Nullable) initWithCLA:	(unsigned)	CLA
INS:	(unsigned)	INS
P1:	(unsigned)	P1
P2:	(unsigned)	P2
Ne:	(unsigned)	Ne

Initialise an APDU as per ISO/IEC 7816-3 case 2 (i.e. Le field present, but no Lc or command-data fields)

Parameters

CLA	Instruction class - indicates the type of command, e.g. interindustry or proprietary, valid range 0-254
INS	Instruction code - indicates the specific command, e.g. "write data", valid range 0-255
P1	First parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255
P2	Second parameter byte for the command, e.g. offset into file at which to write the data, valid range 0-255
Ne	The maximum number of response bytes expected, valid range 1-65536

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ maxCommandLength()

+ (size_t) maxCommandLength

Maximum permitted command length in bytes (excluding header and length fields)

Returns: The maximum length, which is a fixed value (65535)

Property Documentation

◆ CLA

- (uint8_t) CLA

readnonatomicassign

Instruction class (CLA) - the type of smartcard command, e.g. interindustry or proprietary.

◆ commandData

- (NSData* _Nonnull) commandData

readnonatomiccopy

Command data for this APDU if any, otherwise an empty array.

◆ commandDataPresent

- (BOOL) commandDataPresent

readnonatomicassign

Are the command data and encoded command data length (Lc) fields present in this APDU?

◆ INS

- (uint8_t) INS

readnonatomicassign

Instruction code (INS) - indication of the specific smartcard command, e.g. "write data".

◆ Lc

- (NSData* _Nonnull) Lc

readnonatomiccopy

Encoded length of command data (Lc), represented as a byte array; will be empty if Nc = 0.

◆ Le

- (NSData* _Nonnull) Le

readnonatomiccopy

Encoded maximum expected response length (Le), represented as a byte array; will be empty if Ne = 0.

◆ LePresent

- (BOOL) LePresent

readnonatomicassign

Is the encoded maximum expected response length (Le) field present in this APDU?

◆ Nc

- (uint16_t) Nc

readnonatomicassign

Length in bytes of the command data (Nc) if there is any, otherwise zero.

◆ Ne

- (uint32_t) Ne

readnonatomicassign

Maximum number of response bytes expected (Ne), range 0 to maxResponseLength inclusive.

◆ P1

- (uint8_t) P1

readnonatomicassign

First parameter byte (P1) - e.g. offset into file at which to write the data.

◆ P2

- (uint8_t) P2

readnonatomicassign

Second parameter byte (P2) - e.g. offset into file at which to write the data.

◆ shortEncoding

- (BOOL) shortEncoding

readnonatomicassign

Is this APDU using the "short" encodings for the Lc and Le fields (if present)

This property will be set YES if both fields are either absent or encodable using the "short" (single-byte) formats, or NO if either field requires the extended (multi-byte) format.

Description

Instance Methods

Class Methods

Properties

Method Documentation

◆ commandAPDU()

◆ commandAPDU_FromStream:()

◆ commandAPDU_WithCLA:INS:P1:P2:()

◆ commandAPDU_WithCLA:INS:P1:P2:data:()

◆ commandAPDU_WithCLA:INS:P1:P2:data:Ne:()

◆ commandAPDU_WithCLA:INS:P1:P2:Ne:()

◆ get()

◆ header()

◆ hexDump()

◆ init()

◆ initFromStream:()

◆ initWithCLA:INS:P1:P2:()

◆ initWithCLA:INS:P1:P2:data:()

◆ initWithCLA:INS:P1:P2:data:Ne:()

◆ initWithCLA:INS:P1:P2:Ne:()

◆ maxCommandLength()

Property Documentation

◆ CLA

◆ commandData

◆ commandDataPresent

◆ INS

◆ Lc

◆ Le

◆ LePresent

◆ Nc

◆ Ne

◆ P1

◆ P2

◆ shortEncoding