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() 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 this format is found in ISO/IEC 7816-3 and ISO/IEC 7816-4.

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

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

See also: ResponseAPDU for the response equivalent, and SmartcardAPI for related functionality

Public Member Functions
	CommandAPDU ()
	Construct a null APDU - only compulsory fields are present, and everything is set to zero.

	CommandAPDU (int CLA, int INS, int P1, int P2)
	Construct an APDU as per ISO/IEC 7816-3 case 1 (i.e. no Lc, Le or command-data fields) More...

	CommandAPDU (int CLA, int INS, int P1, int P2, int Ne)
	Construct an APDU as per ISO/IEC 7816-3 case 2 (i.e. Le field present, but no Lc or command-data fields) More...

	CommandAPDU (int CLA, int INS, int P1, int P2, @NonNull byte[] data)
	Construct an APDU as per ISO/IEC 7816-3 case 3 (i.e. Lc and command-data fields present, but no Le field) More...

	CommandAPDU (int CLA, int INS, int P1, int P2, @NonNull byte[] data, int Ne)
	Construct an APDU as per ISO/IEC 7816-3 case 4 (i.e. Lc, command-data and Le fields all present) More...

	CommandAPDU (@NonNull byte[] stream)
	Extract APDU data from a byte stream. More...

short	CLA ()
	Query the instruction class (type of smartcard command) More...

byte []	commandData ()
	Copy the command data, if present. More...

boolean	commandDataPresent ()
	Are the Lc and command-data fields present in this APDU? More...

byte []	get ()
	Copy the entire APDU in byte-array format. More...

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

String	hexDump ()
	Obtain a hex dump of the entire APDU. More...

short	INS ()
	Query the instruction code (indication of specific command) More...

byte []	Lc ()
	Query the encoded length in bytes of the command data (Lc), if present. More...

byte []	Le ()
	Query the encoded maximum expected response length (Le) in bytes. More...

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

int	Nc ()
	Query the length of the command data (Nc), if there is any. More...

int	Ne ()
	Query the maximum expected response length (Ne) in bytes. More...

short	P1 ()
	Query the first parameter byte for the command. More...

short	P2 ()
	Query the second parameter byte for the command. More...

boolean	shortEncoding ()
	Are the Lc and Le fields using the "short" encoding? More...

Constructor & Destructor Documentation

◆ CommandAPDU() [1/5]

CommandAPDU	(	int	CLA,
		int	INS,
		int	P1,
		int	P2
	)

Construct 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

Exceptions

IllegalArgumentException if any of the parameters are out of range

◆ CommandAPDU() [2/5]

CommandAPDU	(	int	CLA,
		int	INS,
		int	P1,
		int	P2,
		int	Ne
	)

Construct 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

Exceptions

InvalidArgument if any of the parameters are out of range

◆ CommandAPDU() [3/5]

CommandAPDU	(	int	CLA,
		int	INS,
		int	P1,
		int	P2,
		@NonNull byte []	data
	)

Construct 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

Exceptions

InvalidArgument if any of the parameters are out of range

◆ CommandAPDU() [4/5]

CommandAPDU	(	int	CLA,
		int	INS,
		int	P1,
		int	P2,
		@NonNull byte []	data,
		int	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

Exceptions

InvalidArgument if any of the parameters are out of range

◆ CommandAPDU() [5/5]

CommandAPDU ( @NonNull byte [] 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)

Exceptions

InvalidArgument if the stream could not be parsed successfully

Member Function Documentation

◆ CLA()

short CLA ( )

Query the instruction class (type of smartcard command)

Returns: Contents of CLA field - e.g. inter-industry or proprietary. Valid range is 0-254.

◆ commandData()

byte [] commandData ( )

Copy the command data, if present.

Returns: Command data if present (length 1-65535), or a zero-length array otherwise

◆ commandDataPresent()

boolean commandDataPresent ( )

Are the Lc and command-data fields present in this APDU?

Returns: true for APDU cases 3 and 4, and false for cases 1 and 2.

◆ get()

byte [] 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

◆ header()

byte [] header ( )

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

Returns: First four bytes of the APDU

◆ hexDump()

String hexDump ( )

Obtain a hex dump of the entire APDU.

Returns: Hex dump with spaces separating the bytes

◆ INS()

short INS ( )

Query the instruction code (indication of specific command)

Returns: Contents of INS field - e.g. "write data". Valid range is 0-255.

◆ Lc()

byte [] Lc ( )

Query the encoded length in bytes of the command data (Lc), if present.

Returns: Contents of Lc field if command data is present, otherwise an empty byte array

◆ Le()

byte [] Le ( )

Query the encoded maximum expected response length (Le) in bytes.

Returns: Contents of Le field if it is present, otherwise an empty byte array */

◆ Le_Present()

boolean Le_Present ( )

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

This is equivalent to querying whether Ne > 0.

Returns: True for APDU cases 2 and 4; false for cases 1 and 3.

◆ Nc()

int Nc ( )

Query the length of the command data (Nc), if there is any.

Returns: Length of command data (valid range 1-65535) if present, otherwise zero

◆ Ne()

int Ne ( )

Query the maximum expected response length (Ne) in bytes.

Returns: Contents of Ne field if Le is present (range 1-65536), or zero if Le is not present

◆ P1()

short P1 ( )

Query the first parameter byte for the command.

Returns: Contents of P1 field - e.g. offset into file at which to write the data. Valid range is 0-254.

◆ P2()

short P2 ( )

Query the second parameter byte for the command.

Returns: Contents of P2 field - e.g. offset into file at which to write the data. Valid range is 0-254.

◆ shortEncoding()

boolean shortEncoding ( )

Are the Lc and Le fields using the "short" encoding?

Note: Absent fields are considered "short" for the purposes of this method.

Returns: True if Lc and Le are both absent or using the short encoding; false otherwise

Description

Public Member Functions

Constructor & Destructor Documentation

◆ CommandAPDU() [1/5]

◆ CommandAPDU() [2/5]

◆ CommandAPDU() [3/5]

◆ CommandAPDU() [4/5]

◆ CommandAPDU() [5/5]

Member Function Documentation

◆ CLA()

◆ commandData()

◆ commandDataPresent()

◆ get()

◆ header()

◆ hexDump()

◆ INS()

◆ Lc()

◆ Le()

◆ Le_Present()

◆ Nc()

◆ Ne()

◆ P1()

◆ P2()

◆ shortEncoding()