Description

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

The response APDU is the communication message sent from a smartcard to a card reader. This class encapsulates a response APDU, ensuring its validity at construction-time, and guaranteeing it remains valid for the lifetime of the object. The get (GrabbaResponseAPDU) 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 defined 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: GrabbaCommandAPDU for the command equivalent, and GrabbaSmartcardAPI for related functionality

Inheritance diagram for GrabbaResponseAPDU:

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

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

(instancetype _Nullable)	- init
	Initialise an empty APDU - no response data, and status set to 0x6F00. More...

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

(instancetype _Nullable)	- initWithData:SW1:SW2:
	Initialise an APDU containing given data and status values. More...

Class Methods
(size_t)	+ maxResponseLength
	Maximum permitted response length in bytes (excluding header and length fields) More...

(instancetype _Nullable)	+ responseAPDU
	Allocate and initialise an empty APDU - no response data, and status set to 0x6F00. More...

(instancetype _Nullable)	+ responseAPDU_FromStream:
	Allocate and initialise an APDU with data extracted from a byte stream. More...

(instancetype _Nullable)	+ responseAPDU_WithData:SW1:SW2:
	Allocate and initialise an APDU containing given data and status values. More...

(NSString *_Nonnull)	+ statusStringForSW1:SW2:
	String description of a given response status. More...

Properties
NSData *_Nonnull	responseData
	Response data for this APDU. More...

size_t	responseDataSize
	Size of the response data for this APDU (i.e. length of responseData) More...

NSString *_Nonnull	statusString
	String description of the stored response status. More...

BOOL	successComplete
	Does the response indicate successful processing with no further response data remaining? More...

BOOL	successIncomplete
	Does the response indicate successful processing with additional response data remaining? More...

uint8_t	SW1
	First status byte (SW1) More...

uint8_t	SW2
	Second status byte (SW2) More...

Method Documentation

◆ get()

- (NSData* _Nonnull) get

Copy the entire APDU in byte-array format.

Returns: Entire APDU, including data, SW1 and SW2 fields

◆ 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 an empty APDU - no response data, and status set to 0x6F00.

This constructor should only be used when it is necessary to return a sentinel value, and that some other indication (e.g. an error code parameter) is supplied to a user to notify them that the value is invalid.

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 last two bytes in the array are used to construct the SW1 and SW2 fields; the remainder is treated as response data.

Parameters

stream APDU data stream; length must be at least 2 bytes, and at most maxResponseLength + 2

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

◆ initWithData:SW1:SW2:()

- (instancetype _Nullable) initWithData:	(NSData *_Nonnull)	data
SW1:	(unsigned)	SW1
SW2:	(unsigned)	SW2

Initialise an APDU containing given data and status values.

Parameters

data	Response data; length must not exceed maxResponseLength
SW1	First status byte - e.g. 0x90 for success. Valid ranges are 0x61-0x6F and 0x90-0x9F inclusive.
SW2	Second status byte - e.g. 0x00 for success. Valid range is 0-255.

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

◆ maxResponseLength()

+ (size_t) maxResponseLength

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

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

◆ responseAPDU()

+ (instancetype _Nullable) responseAPDU

Allocate and initialise an empty APDU - no response data, and status set to 0x6F00.

This constructor should only be used when it is necessary to return a sentinel value, and that some other indication (e.g. an error code parameter) is supplied to a user to notify them that the value is invalid.

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

◆ responseAPDU_FromStream:()

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

Allocate and initialise an APDU with data extracted from a byte stream.

The last two bytes in the array are used to construct the SW1 and SW2 fields; the remainder is treated as response data.

Parameters

stream APDU data stream; length must be at least 2 bytes, and at most maxResponseLength + 2

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

◆ responseAPDU_WithData:SW1:SW2:()

+ (instancetype _Nullable) responseAPDU_WithData:	(NSData *_Nonnull)	data
SW1:	(unsigned)	SW1
SW2:	(unsigned)	SW2

Allocate and initialise an APDU containing given data and status values.

Parameters

data	Response data; length must not exceed maxResponseLength
SW1	First status byte - e.g. 0x90 for success. Valid ranges are 0x61-0x6F and 0x90-0x9F inclusive.
SW2	Second status byte - e.g. 0x00 for success. Valid range is 0-255.

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

◆ statusStringForSW1:SW2:()

+ (NSString* _Nonnull) statusStringForSW1:	(uint8_t)	SW1
SW2:	(uint8_t)	SW2

String description of a given response status.

Parameters

SW1	First status byte
SW2	Second status byte

Returns: String containing a textual description of the status value stored in fields SW1 and SW2

Property Documentation

◆ responseData

- (NSData* _Nonnull) responseData

readnonatomiccopy

Response data for this APDU.

◆ responseDataSize

- (size_t) responseDataSize

readnonatomicassign

Size of the response data for this APDU (i.e. length of responseData)

◆ statusString

- (NSString* _Nonnull) statusString

readnonatomiccopy

String description of the stored response status.

◆ successComplete

- (BOOL) successComplete

readnonatomicassign

Does the response indicate successful processing with no further response data remaining?

This will be YES if the status bytes are 0x9000, or NO otherwise.

◆ successIncomplete

- (BOOL) successIncomplete

readnonatomicassign

Does the response indicate successful processing with additional response data remaining?

This will be YES if the status bytes are in the range 0x6100 to 0x61FF inclusive, or NO otherwise.

◆ SW1

- (uint8_t) SW1

readnonatomicassign

First status byte (SW1)

◆ SW2

- (uint8_t) SW2

readnonatomicassign

Second status byte (SW2)

Description

Instance Methods

Class Methods

Properties

Method Documentation

◆ get()

◆ hexDump()

◆ init()

◆ initFromStream:()

◆ initWithData:SW1:SW2:()

◆ maxResponseLength()

◆ responseAPDU()

◆ responseAPDU_FromStream:()

◆ responseAPDU_WithData:SW1:SW2:()

◆ statusStringForSW1:SW2:()

Property Documentation

◆ responseData

◆ responseDataSize

◆ statusString

◆ successComplete

◆ successIncomplete

◆ SW1

◆ SW2