Class APDU
- java.lang.Object
-
- javacard.framework.APDU
-
public final class APDU extends Object
Application Protocol Data Unit (APDU) is the communication format between the card and the off-card applications. The format of the APDU is defined in ISO specification 7816-4.This class only supports messages which conform to the structure of command and response defined in ISO 7816-4. The behavior of messages which use proprietary structure of messages is undefined. This class optionally supports extended length fields but only when the currently selected applet implements the
javacardx.apdu.ExtendedLength
interface.The
APDU
object is owned by the Java Card runtime environment. TheAPDU
class maintains a byte array buffer which is used to transfer incoming APDU header and data bytes as well as outgoing data. The buffer length must be at least 133 bytes ( 5 bytes of header and 128 bytes of data ). The Java Card runtime environment must zero out the APDU buffer before each new message received from the CAD.The Java Card runtime environment designates the
APDU
object as a temporary Java Card runtime environment Entry Point Object (See Runtime Environment Specification, Java Card Platform, Classic Edition, section 6.2.1 for details). A temporary Java Card runtime environment Entry Point Object can be accessed from any applet context. References to these temporary objects cannot be stored in class variables or instance variables or array components.The Java Card runtime environment similarly marks the APDU buffer as a global array (See Runtime Environment Specification, Java Card Platform, Classic Edition, section 6.2.2 for details). A global array can be accessed from any applet context. References to global arrays cannot be stored in class variables or instance variables or array components.
The applet receives the
APDU
instance to process from the Java Card runtime environment in theApplet.process(APDU)
method, and the first five header bytes [ CLA, INS, P1, P2, P3 ] are available in the APDU buffer. (The header format is the ISO7816-4 defined 7 byte extended APDU format with a 3 byte Lc field when the Lc field in the incoming APDU header is 3 bytes long).The
APDU
class API is designed to be transport protocol independent. In other words, applets can use the same APDU methods regardless of whether the underlying protocol in use is T=0 or T=1 (as defined in ISO 7816-3).The incoming APDU data size may be bigger than the APDU buffer size and may therefore need to be read in portions by the applet. Similarly, the outgoing response APDU data size may be bigger than the APDU buffer size and may need to be written in portions by the applet. The
APDU
class has methods to facilitate this.For sending large byte arrays as response data, the
APDU
class provides a special methodsendBytesLong()
which manages the APDU buffer.
// The purpose of this example is to show most of the methods // in use and not to depict any particular APDU processing class MyApplet extends javacard.framework.Applet { // ... public void process(APDU apdu){ // ... byte[] buffer = apdu.getBuffer(); byte cla = buffer[ISO7816.OFFSET_CLA]; byte ins = buffer[ISO7816.OFFSET_INS]; ... // assume this command has incoming data // Lc tells us the incoming apdu command length short bytesLeft = (short) (buffer[ISO7816.OFFSET_LC] & 0x00FF); if (bytesLeft < (short)55) ISOException.throwIt( ISO7816.SW_WRONG_LENGTH ); short readCount = apdu.setIncomingAndReceive(); while ( bytesLeft > 0){ // enter code here to process the data previously read in buffer[5] // to buffer[readCount+4]; bytesLeft -= readCount; readCount = apdu.receiveBytes ( ISO7816.OFFSET_CDATA ); // read more APDU data } // //... // // Note that for a short response as in the case illustrated here // the three APDU method calls shown : setOutgoing(),setOutgoingLength() & sendBytes() // could be replaced by one APDU method call : setOutgoingAndSend(). // construct the reply APDU short le = apdu.setOutgoing(); if (le < (short)2) ISOException.throwIt( ISO7816.SW_WRONG_LENGTH ); apdu.setOutgoingLength( (short)3 ); // build response data in apdu.buffer[ 0.. outCount-1 ]; buffer[0] = (byte)1; buffer[1] = (byte)2; buffer[3] = (byte)3; apdu.sendBytes ( (short)0 , (short)3 ); // return good complete status 90 00 } // ... }
TheAPDU
class also defines a set ofSTATE_..
constants which represent the various processing states of theAPDU
object based on the methods invoked and the state of the data transfers. ThegetCurrentState()
method returns the current state.Note that the state number assignments are ordered as follows: STATE_INITIAL < STATE_PARTIAL_INCOMING < STATE_FULL_INCOMING < STATE_OUTGOING < STATE_OUTGOING_LENGTH_KNOWN < STATE_PARTIAL_OUTGOING < STATE_FULL_OUTGOING.
The following are processing error states and have negative state number assignments : STATE_ERROR_NO_T0_GETRESPONSE, STATE_ERROR_T1_IFD_ABORT, STATE_ERROR_IO and STATE_ERROR_NO_T0_REISSUE.
Note:
- The method descriptions use the ISO7816-4 notation for the various APDU I/O cases of input and output directions. For example - T=0 (Case 2S) protocol - refers to short length outbound only case using the T=0 protocol. The perspective of the notation used in the method descriptions is that of the card(ICC) as seen at the transport layer(TPDU). External transformations of the APDU I/O case may have occurred at the CAD and therefore not visible to the card.
- The method descriptions mention T=0 and T=1 protocols. Unless specifically called out, the behavior described for T=1 protocol is applicable to contactless protocols also.
- See Also:
APDUException
,ISOException
-
-
Field Summary
Fields Modifier and Type Field Description static byte
PROTOCOL_MEDIA_CONTACTLESS_TYPE_A
Transport protocol Media - Contactless Type Astatic byte
PROTOCOL_MEDIA_CONTACTLESS_TYPE_B
Transport protocol Media - Contactless Type Bstatic byte
PROTOCOL_MEDIA_CONTACTLESS_TYPE_F
JIS X 6319-4:2010 transport protocol Type Fstatic byte
PROTOCOL_MEDIA_DEFAULT
Transport protocol Media - Contacted Asynchronous Half Duplexstatic byte
PROTOCOL_MEDIA_HCI_APDU_GATE
Deprecated.This constant was incorrectly defined and must not be usedstatic byte
PROTOCOL_MEDIA_MASK
Media nibble mask in protocol bytestatic byte
PROTOCOL_MEDIA_USB
Transport protocol Media - USBstatic byte
PROTOCOL_T0
ISO 7816 transport protocol type T=0.static byte
PROTOCOL_T1
ISO 7816 transport protocol type T=1.static byte
PROTOCOL_TYPE_MASK
Type nibble mask in protocol bytestatic byte
STATE_ERROR_IO
This error state of aAPDU
object occurs when anAPDUException
with reason codeAPDUException.IO_ERROR
has been thrown.static byte
STATE_ERROR_NO_T0_GETRESPONSE
This error state of aAPDU
object occurs when anAPDUException
with reason codeAPDUException.NO_T0_GETRESPONSE
has been thrown.static byte
STATE_ERROR_NO_T0_REISSUE
This error state of aAPDU
object occurs when anAPDUException
with reason codeAPDUException.NO_T0_REISSUE
has been thrown.static byte
STATE_ERROR_T1_IFD_ABORT
This error state of aAPDU
object occurs when anAPDUException
with reason codeAPDUException.T1_IFD_ABORT
has been thrown.static byte
STATE_FULL_INCOMING
This is the state of aAPDU
object when all the incoming data been received.static byte
STATE_FULL_OUTGOING
This is the state of aAPDU
object when all outbound data has been transferred.static byte
STATE_INITIAL
This is the state of a newAPDU
object when only the command header is valid.static byte
STATE_OUTGOING
This is the state of a newAPDU
object when data transfer mode is outbound but length is not yet known.static byte
STATE_OUTGOING_LENGTH_KNOWN
This is the state of aAPDU
object when data transfer mode is outbound and outbound length is known.static byte
STATE_PARTIAL_INCOMING
This is the state of aAPDU
object when incoming data has partially been received.static byte
STATE_PARTIAL_OUTGOING
This is the state of aAPDU
object when some outbound data has been transferred but not all.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description byte[]
getBuffer()
Returns the APDU buffer byte array.static byte
getCLAChannel()
Returns the logical channel number associated with the currentAPDU
command based on the CLA byte.static APDU
getCurrentAPDU()
This method is called during theApplet.process(APDU)
method to obtain a reference to the currentAPDU
object.static byte[]
getCurrentAPDUBuffer()
This method is called during theApplet.process(APDU)
method to obtain a reference to the current APDU buffer.byte
getCurrentState()
This method returns the current processing state of theAPDU
object.static short
getInBlockSize()
Returns the configured incoming block size.short
getIncomingLength()
Returns the incoming data length(Lc).byte
getNAD()
Returns the Node Address byte (NAD) in contacted T=1 protocol, and 0 in contacted T=0 and contactless protocols.short
getOffsetCdata()
Returns the offset within the APDU buffer for incoming command data.static short
getOutBlockSize()
Returns the configured outgoing block size.static byte
getProtocol()
Returns the ISO 7816 transport protocol type, T=1 or T=0, in the low nibble and the transport media in the upper nibble in use, based on protocol and media used for the last APDU received.boolean
isCommandChainingCLA()
Returns whether the currentAPDU
command is the first or part of a command chain.boolean
isISOInterindustryCLA()
Returns whether the currentAPDU
command CLA byte corresponds to an interindustry command as defined in ISO 7816-4:2013 specification.boolean
isSecureMessagingCLA()
Returnstrue
if the encoding of the currentAPDU
command based on the CLA byte indicates secure messaging.boolean
isValidCLA()
Returns whether the currentAPDU
command CLA byte is valid.short
receiveBytes(short bOff)
Gets as many data bytes as will fit without APDU buffer overflow, at the specified offsetbOff
.void
sendBytes(short bOff, short len)
Sendslen
more bytes from APDU buffer at specified offsetbOff
.void
sendBytesLong(byte[] outData, short bOff, short len)
Sendslen
more bytes fromoutData
byte array starting at specified offsetbOff
.short
setIncomingAndReceive()
This is the primary receive method.short
setOutgoing()
This method is used to set the data transfer direction to outbound and to obtain the expected length of response (Ne).void
setOutgoingAndSend(short bOff, short len)
This is the "convenience" send method.void
setOutgoingLength(short len)
Sets the actual length of response data.short
setOutgoingNoChaining()
This method is used to set the data transfer direction to outbound without using chaining mode and to obtain the expected length of response (Ne).static void
waitExtension()
Requests additional processing time from CAD.
-
-
-
Field Detail
-
STATE_INITIAL
public static final byte STATE_INITIAL
This is the state of a newAPDU
object when only the command header is valid.- See Also:
- Constant Field Values
-
STATE_PARTIAL_INCOMING
public static final byte STATE_PARTIAL_INCOMING
This is the state of aAPDU
object when incoming data has partially been received.- See Also:
- Constant Field Values
-
STATE_FULL_INCOMING
public static final byte STATE_FULL_INCOMING
This is the state of aAPDU
object when all the incoming data been received.- See Also:
- Constant Field Values
-
STATE_OUTGOING
public static final byte STATE_OUTGOING
This is the state of a newAPDU
object when data transfer mode is outbound but length is not yet known.- See Also:
- Constant Field Values
-
STATE_OUTGOING_LENGTH_KNOWN
public static final byte STATE_OUTGOING_LENGTH_KNOWN
This is the state of aAPDU
object when data transfer mode is outbound and outbound length is known.- See Also:
- Constant Field Values
-
STATE_PARTIAL_OUTGOING
public static final byte STATE_PARTIAL_OUTGOING
This is the state of aAPDU
object when some outbound data has been transferred but not all.- See Also:
- Constant Field Values
-
STATE_FULL_OUTGOING
public static final byte STATE_FULL_OUTGOING
This is the state of aAPDU
object when all outbound data has been transferred.- See Also:
- Constant Field Values
-
STATE_ERROR_NO_T0_GETRESPONSE
public static final byte STATE_ERROR_NO_T0_GETRESPONSE
This error state of aAPDU
object occurs when anAPDUException
with reason codeAPDUException.NO_T0_GETRESPONSE
has been thrown.- See Also:
- Constant Field Values
-
STATE_ERROR_T1_IFD_ABORT
public static final byte STATE_ERROR_T1_IFD_ABORT
This error state of aAPDU
object occurs when anAPDUException
with reason codeAPDUException.T1_IFD_ABORT
has been thrown.- See Also:
- Constant Field Values
-
STATE_ERROR_IO
public static final byte STATE_ERROR_IO
This error state of aAPDU
object occurs when anAPDUException
with reason codeAPDUException.IO_ERROR
has been thrown.- See Also:
- Constant Field Values
-
STATE_ERROR_NO_T0_REISSUE
public static final byte STATE_ERROR_NO_T0_REISSUE
This error state of aAPDU
object occurs when anAPDUException
with reason codeAPDUException.NO_T0_REISSUE
has been thrown.- See Also:
- Constant Field Values
-
PROTOCOL_MEDIA_MASK
public static final byte PROTOCOL_MEDIA_MASK
Media nibble mask in protocol byte- See Also:
getProtocol()
, Constant Field Values
-
PROTOCOL_TYPE_MASK
public static final byte PROTOCOL_TYPE_MASK
Type nibble mask in protocol byte- See Also:
getProtocol()
, Constant Field Values
-
PROTOCOL_T0
public static final byte PROTOCOL_T0
ISO 7816 transport protocol type T=0.- See Also:
getProtocol()
, Constant Field Values
-
PROTOCOL_T1
public static final byte PROTOCOL_T1
ISO 7816 transport protocol type T=1. This constant is also used to denote the T=CL variant for contactless cards defined in ISO14443-4.- See Also:
getProtocol()
, Constant Field Values
-
PROTOCOL_MEDIA_DEFAULT
public static final byte PROTOCOL_MEDIA_DEFAULT
Transport protocol Media - Contacted Asynchronous Half Duplex- See Also:
getProtocol()
, Constant Field Values
-
PROTOCOL_MEDIA_CONTACTLESS_TYPE_A
public static final byte PROTOCOL_MEDIA_CONTACTLESS_TYPE_A
Transport protocol Media - Contactless Type A- See Also:
getProtocol()
, Constant Field Values
-
PROTOCOL_MEDIA_CONTACTLESS_TYPE_B
public static final byte PROTOCOL_MEDIA_CONTACTLESS_TYPE_B
Transport protocol Media - Contactless Type B- See Also:
getProtocol()
, Constant Field Values
-
PROTOCOL_MEDIA_USB
public static final byte PROTOCOL_MEDIA_USB
Transport protocol Media - USB- See Also:
getProtocol()
, Constant Field Values
-
PROTOCOL_MEDIA_HCI_APDU_GATE
@Deprecated public static final byte PROTOCOL_MEDIA_HCI_APDU_GATE
Deprecated.This constant was incorrectly defined and must not be usedTransport protocol Media - APDU over HCI defined for the APDU gate in ETSI TS 102 622- See Also:
- Constant Field Values
-
PROTOCOL_MEDIA_CONTACTLESS_TYPE_F
public static final byte PROTOCOL_MEDIA_CONTACTLESS_TYPE_F
JIS X 6319-4:2010 transport protocol Type F- See Also:
getProtocol()
, Constant Field Values
-
-
Method Detail
-
getBuffer
public byte[] getBuffer()
Returns the APDU buffer byte array.Note:
- References to the APDU buffer byte array may be stored in local variables or method parameters.
- References to the APDU buffer byte array cannot be stored in class variables or instance variables or array components. See Runtime Environment Specification, Java Card Platform, Classic Edition, section 6.2.2 for details.
- Returns:
- byte array containing the APDU buffer
-
getInBlockSize
public static short getInBlockSize()
Returns the configured incoming block size. In T=1 protocol, this corresponds to IFSC (information field size for ICC), the maximum size of incoming data blocks into the card. In T=0 protocol, this method returns 1. IFSC is defined in ISO 7816-3. In contactless protocols, the maximum size of the incoming frame without the protocol overhead is returned.This information may be used to ensure that there is enough space remaining in the APDU buffer when
receiveBytes()
is invoked.Note:
- On
receiveBytes()
thebOff
param should account for this potential blocksize.
- Returns:
- incoming block size setting
- See Also:
receiveBytes(short)
- On
-
getOutBlockSize
public static short getOutBlockSize()
Returns the configured outgoing block size. In T=1 protocol, this corresponds to IFSD (information field size for interface device), the maximum size of outgoing data blocks to the CAD. In T=0 protocol, this method returns 258 (accounts for 2 status bytes). IFSD is defined in ISO 7816-3. In contactless protocols, the maximum frame size that can be received by the PCD(proximity coupling device) without the protocol overhead is returned.This information may be used prior to invoking the
setOutgoingLength()
method, to limit the length of outgoing messages when chaining mode is not allowed. See Runtime Environment Specification, Java Card Platform, Classic Edition, section 9.4 for details.Note:
- On
setOutgoingLength()
thelen
param should account for this potential blocksize.
- Returns:
- outgoing block size setting
- See Also:
setOutgoingLength(short)
- On
-
getProtocol
public static byte getProtocol()
Returns the ISO 7816 transport protocol type, T=1 or T=0, in the low nibble and the transport media in the upper nibble in use, based on protocol and media used for the last APDU received.Note:
- This method returns T=1 in the low nibble for contactless protocols.
- Returns:
- the protocol media and type in progress Valid nibble codes are
listed in
PROTOCOL_*
constants above, for examplePROTOCOL_T0
.
-
getNAD
public byte getNAD()
Returns the Node Address byte (NAD) in contacted T=1 protocol, and 0 in contacted T=0 and contactless protocols. This may be used as additional information to maintain multiple contexts.- Returns:
- NAD transport byte as defined in ISO 7816-3
-
setOutgoing
public short setOutgoing() throws APDUException
This method is used to set the data transfer direction to outbound and to obtain the expected length of response (Ne). This method should only be called on a case 2 or case 4 command, otherwise erroneous behavior may result.Notes.
- On a case 4 command, the
setIncomingAndReceive()
must be invoked prior to calling this method. Otherwise, erroneous behavior may result in T=0 protocol. - Any remaining incoming data will be discarded.
- In T=0 (Case 4S) protocol, this method will return 256 with normal semantics.
- In T=0 (Case 2E, 4S, 4E) protocol, this method will return 32767 when
the currently selected applet implements the
javacardx.apdu.ExtendedLength
interface. - In T=1 (Case 2E, 4E) protocol, this method will return 32767 when the
Le field in the APDU command is protocol is 0x0000 or greater than 32767
and the currently selected applet implements the
javacardx.apdu.ExtendedLength
interface. - This method sets the state of the
APDU
object toSTATE_OUTGOING
.
- Returns:
- Ne, the expected length of response
- Throws:
APDUException
- with the following reason codes:APDUException.ILLEGAL_USE
if this method, orsetOutgoingNoChaining()
method already invoked.APDUException.IO_ERROR
if the APDU is an error state.
- On a case 4 command, the
-
setOutgoingNoChaining
public short setOutgoingNoChaining() throws APDUException
This method is used to set the data transfer direction to outbound without using chaining mode and to obtain the expected length of response (Ne). This method should be used in place of thesetOutgoing()
method by applets which need to be compatible with legacy CAD/terminals which do not support chaining mode. See Runtime Environment Specification, Java Card Platform, Classic Edition, section 9.4 for details.Notes.
- On a case 4 command, the
setIncomingAndReceive()
must be invoked prior to calling this method. Otherwise, erroneous behavior may result in T=0 protocol. - Any remaining incoming data will be discarded.
- In T=0 (Case 4S) protocol, this method will return 256 with normal semantics.
- In T=0 (Case 2E, 4S, 4E) protocol, this method will return 256 when
the currently selected applet implements the
javacardx.apdu.ExtendedLength
interface. - When this method is used, the
waitExtension()
method cannot be used. - In T=1 protocol, retransmission on error may be restricted.
- In some cases of the T=0 protocol, the outbound transfer must be performed
without using
(ISO7816.SW_BYTES_REMAINING_00+count)
response status chaining. See the Runtime Environment Specification, Java Card Platform, Classic Edition, section 9.4 for details. - In T=1 protocol, the outbound transfer must not set the More(M) Bit in the PCB of the I block. See ISO 7816-3.
- This method sets the state of the
APDU
object toSTATE_OUTGOING
.
- Returns:
- Ne, the expected length of response data
- Throws:
APDUException
- with the following reason codes:APDUException.ILLEGAL_USE
if this method, orsetOutgoing()
method already invoked.APDUException.IO_ERROR
if the APDU is in an error state
- On a case 4 command, the
-
setOutgoingLength
public void setOutgoingLength(short len) throws APDUException
Sets the actual length of response data. If a length of0
is specified, no data will be output.Note:
- In T=0 (Case 2&4) protocol, the length is used by the Java Card runtime environment to prompt the CAD for GET RESPONSE commands.
- This method sets the state of the
APDU
object toSTATE_OUTGOING_LENGTH_KNOWN
.
- Parameters:
len
- the length of response data- Throws:
APDUException
- with the following reason codes:APDUException.ILLEGAL_USE
ifsetOutgoing()
orsetOutgoingNoChaining()
not called or ifsetOutgoingAndSend()
already invoked, or this method already invoked.APDUException.BAD_LENGTH
if any one of the following is true:len
is negative.len
is greater than 256 and the currently selected applet does not implement thejavacardx.apdu.ExtendedLength
interface.- T=0 protocol is in use, non BLOCK CHAINED data
transfer is requested and
len
is greater than 256. - T=1 protocol is in use, non BLOCK CHAINED data
transfer is requested and
len
is greater than (IFSD-2), where IFSD is the Outgoing Block Size. The -2 accounts for the status bytes in T=1.
APDUException.NO_T0_GETRESPONSE
if T=0 protocol is in use and the CAD does not respond to(ISO7816.SW_BYTES_REMAINING_00+count)
response status with GET RESPONSE command on the same origin logical channel number as that of the current APDU command.APDUException.NO_T0_REISSUE
if T=0 protocol is in use and the CAD does not respond to(ISO7816.SW_CORRECT_LENGTH_00+count)
response status by re-issuing same APDU command on the same origin logical channel number as that of the current APDU command with the corrected length.APDUException.IO_ERROR
if the APDU is in an error state
- See Also:
getOutBlockSize()
-
receiveBytes
public short receiveBytes(short bOff) throws APDUException
Gets as many data bytes as will fit without APDU buffer overflow, at the specified offsetbOff
. Gets all the remaining bytes if they fit.Notes:
- The space in the buffer must allow for incoming block size.
- In T=1 protocol, if all the remaining bytes do not fit in the buffer, this method may return less bytes than the maximum incoming block size (IFSC).
- In T=0 protocol, if all the remaining bytes do not fit in the buffer, this method may return less than a full buffer of bytes to optimize and reduce protocol overhead.
- In T=1 protocol, if this method throws an
APDUException
withT1_IFD_ABORT
reason code, the Java Card runtime environment will restart APDU command processing using the newly received command. No more input data can be received. No output data can be transmitted. No error status response can be returned. - This method sets the state of the
APDU
object toSTATE_PARTIAL_INCOMING
if all incoming bytes are not received. - This method sets the state of the
APDU
object toSTATE_FULL_INCOMING
if all incoming bytes are received.
- Parameters:
bOff
- the offset into APDU buffer- Returns:
- number of bytes read. Returns 0 if no bytes are available
- Throws:
APDUException
- with the following reason codes:APDUException.ILLEGAL_USE
ifsetIncomingAndReceive()
not called or ifsetOutgoing()
orsetOutgoingNoChaining()
previously invoked.APDUException.BUFFER_BOUNDS
if not enough buffer space for incoming block size or ifbOff
is negative.APDUException.IO_ERROR
if the APDU is in an error stateAPDUException.T1_IFD_ABORT
if T=1 protocol is in use and the CAD sends in an ABORT S-Block command to abort the data transfer.
- See Also:
getInBlockSize()
-
setIncomingAndReceive
public short setIncomingAndReceive() throws APDUException
This is the primary receive method. Calling this method indicates that this APDU has incoming data. This method gets as many bytes as will fit without buffer overflow in the APDU buffer following the header. It gets all the incoming bytes if they fit.This method should only be called on a case 3 or case 4 command, otherwise erroneous behavior may result.
Notes:
- In T=0 ( Case 3&4 ) protocol, the P3 param is assumed to be Lc.
- Data is read into the buffer at offset 5 for normal APDU semantics.
- Data is read into the buffer at offset 7 for an extended length APDU (Case 3E/4E).
- In T=1 protocol, if all the incoming bytes do not fit in the buffer, this method may return less bytes than the maximum incoming block size (IFSC).
- In T=0 protocol, if all the incoming bytes do not fit in the buffer, this method may return less than a full buffer of bytes to optimize and reduce protocol overhead.
- This method sets the transfer direction to be inbound
and calls
receiveBytes(5)
for normal semantics orreceiveBytes(7)
for extended semantics. - This method may only be called once in a
Applet.process()
method. - This method sets the state of the
APDU
object toSTATE_PARTIAL_INCOMING
if all incoming bytes are not received. - This method sets the state of the
APDU
object toSTATE_FULL_INCOMING
if all incoming bytes are received.
- Returns:
- number of data bytes read. The Le byte, if any, is not included in the count. Returns 0 if no bytes are available.
- Throws:
APDUException
- with the following reason codes:APDUException.ILLEGAL_USE
ifsetIncomingAndReceive()
already invoked or ifsetOutgoing()
orsetOutgoingNoChaining()
previously invoked.APDUException.IO_ERROR
if the APDU is in an error stateAPDUException.T1_IFD_ABORT
if T=1 protocol is in use and the CAD sends in an ABORT S-Block command to abort the data transfer.
- See Also:
getIncomingLength()
,getOffsetCdata()
-
sendBytes
public void sendBytes(short bOff, short len) throws APDUException
Sendslen
more bytes from APDU buffer at specified offsetbOff
.If the last part of the response is being sent by the invocation of this method, the APDU buffer must not be altered. If the data is altered, incorrect output may be sent to the CAD. Requiring that the buffer not be altered allows the implementation to reduce protocol overhead by transmitting the last part of the response along with the status bytes.
Notes:
- If
setOutgoingNoChaining()
was invoked, output chaining mode must not be used. See Runtime Environment Specification, Java Card Platform, Classic Edition section 9.4 for details. - In T=0 protocol, if
setOutgoingNoChaining()
was invoked, Le bytes must be transmitted before(ISO7816.SW_BYTES_REMAINING_00+remaining bytes)
response status is returned. - In T=0 protocol, if this method throws an
APDUException
withNO_T0_GETRESPONSE
orNO_T0_REISSUE
reason code, the Java Card runtime environment will restart APDU command processing using the newly received command. No more output data can be transmitted. No error status response can be returned. - In T=1 protocol, if this method throws an
APDUException
withT1_IFD_ABORT
reason code, the Java Card runtime environment will restart APDU command processing using the newly received command. No more output data can be transmitted. No error status response can be returned. - This method sets the state of the
APDU
object toSTATE_PARTIAL_OUTGOING
if all outgoing bytes have not been sent. - This method sets the state of the
APDU
object toSTATE_FULL_OUTGOING
if all outgoing bytes have been sent.
- Parameters:
bOff
- the offset into APDU bufferlen
- the length of the data in bytes to send- Throws:
APDUException
- with the following reason codes:APDUException.ILLEGAL_USE
ifsetOutgoingLength()
not called orsetOutgoingAndSend()
previously invoked or response byte count exceeded or ifAPDUException.NO_T0_GETRESPONSE
orAPDUException.NO_T0_REISSUE
orAPDUException.T1_IFD_ABORT
previously thrown.APDUException.BUFFER_BOUNDS
ifbOff
is negative orlen
is negative orbOff+len
exceeds the buffer size.APDUException.IO_ERROR
if the APDU is in an error state.APDUException.NO_T0_GETRESPONSE
if T=0 protocol is in use and the CAD does not respond to(ISO7816.SW_BYTES_REMAINING_00+count)
response status with GET RESPONSE command on the same origin logical channel number as that of the current APDU command.APDUException.NO_T0_REISSUE
if T=0 protocol is in use and the CAD does not respond to(ISO7816.SW_CORRECT_LENGTH_00+count)
response status by re-issuing same APDU command on the same origin logical channel number as that of the current APDU command with the corrected length.APDUException.T1_IFD_ABORT
if T=1 protocol is in use and the CAD sends in an ABORT S-Block command to abort the data transfer.
- See Also:
setOutgoing()
,setOutgoingNoChaining()
- If
-
sendBytesLong
public void sendBytesLong(byte[] outData, short bOff, short len) throws APDUException, SecurityException
Sendslen
more bytes fromoutData
byte array starting at specified offsetbOff
.If the last of the response is being sent by the invocation of this method, the APDU buffer must not be altered. If the data is altered, incorrect output may be sent to the CAD. Requiring that the buffer not be altered allows the implementation to reduce protocol overhead by transmitting the last part of the response along with the status bytes.
The Java Card runtime environment may use the APDU buffer to send data to the CAD.
Notes:
- If
setOutgoingNoChaining()
was invoked, output chaining mode must not be used. See Runtime Environment Specification, Java Card Platform, Classic Edition section 9.4 for details. - In T=0 protocol, if
setOutgoingNoChaining()
was invoked, Le bytes must be transmitted before(ISO7816.SW_BYTES_REMAINING_00+remaining bytes)
response status is returned. - In T=0 protocol, if this method throws an
APDUException
withNO_T0_GETRESPONSE
orNO_T0_REISSUE
reason code, the Java Card runtime environment will restart APDU command processing using the newly received command. No more output data can be transmitted. No error status response can be returned. - In T=1 protocol, if this method throws an
APDUException
withT1_IFD_ABORT
reason code, the Java Card runtime environment will restart APDU command processing using the newly received command. No more output data can be transmitted. No error status response can be returned. - This method sets the state of the
APDU
object toSTATE_PARTIAL_OUTGOING
if all outgoing bytes have not been sent. - This method sets the state of the
APDU
object toSTATE_FULL_OUTGOING
if all outgoing bytes have been sent.
- Parameters:
outData
- the source data byte arraybOff
- the offset into OutData arraylen
- the byte length of the data to send- Throws:
SecurityException
- if theoutData
array is not accessible in the caller's contextAPDUException
- with the following reason codes:APDUException.ILLEGAL_USE
ifsetOutgoingLength()
not called orsetOutgoingAndSend()
previously invoked or response byte count exceeded or ifAPDUException.NO_T0_GETRESPONSE
orAPDUException.NO_T0_REISSUE
orAPDUException.NO_T0_REISSUE
previously thrown.APDUException.IO_ERROR
if the APDU is in an error state.APDUException.NO_T0_GETRESPONSE
if T=0 protocol is in use and CAD does not respond to(ISO7816.SW_BYTES_REMAINING_00+count)
response status with GET RESPONSE command on the same origin logical channel number as that of the current APDU command.APDUException.T1_IFD_ABORT
if T=1 protocol is in use and the CAD sends in an ABORT S-Block command to abort the data transfer.
- See Also:
setOutgoing()
,setOutgoingNoChaining()
- If
-
setOutgoingAndSend
public void setOutgoingAndSend(short bOff, short len) throws APDUException
This is the "convenience" send method. It provides for the most efficient way to send a short response which fits in the buffer and needs the least protocol overhead. This method is a combination ofsetOutgoing(), setOutgoingLength( len )
followed bysendBytes ( bOff, len )
. In addition, once this method is invoked,sendBytes()
andsendBytesLong()
methods cannot be invoked and the APDU buffer must not be altered.Sends
len
byte response from the APDU buffer starting at the specified offsetbOff
.Notes:
- No other
APDU
send methods can be invoked. - The APDU buffer must not be altered. If the data is altered, incorrect output may be sent to the CAD.
- The actual data transmission may only take place on return from
Applet.process()
- This method sets the state of the
APDU
object toSTATE_FULL_OUTGOING
.
- Parameters:
bOff
- the offset into APDU bufferlen
- the bytelength of the data to send- Throws:
APDUException
- with the following reason codes:APDUException.ILLEGAL_USE
ifsetOutgoing()
orsetOutgoingAndSend()
previously invoked.APDUException.IO_ERROR
if the APDU is in an error state.APDUException.BAD_LENGTH
iflen
is negative or greater than 256 and the currently selected applet does not implement thejavacardx.apdu.ExtendedLength
interface.
- No other
-
getCurrentState
public byte getCurrentState()
This method returns the current processing state of theAPDU
object. It is used by theBasicService
class to help services collaborate in the processing of an incoming APDU command. Valid codes are listed inSTATE_*
constants above, for exampleSTATE_INITIAL
.- Returns:
- the current processing state of the APDU
- See Also:
javacard.framework.service.BasicService
-
getCurrentAPDU
public static APDU getCurrentAPDU() throws SecurityException
This method is called during theApplet.process(APDU)
method to obtain a reference to the currentAPDU
object. This method can only be called in the context of the currently selected applet.Note:
- Do not call this method directly or indirectly from within a method invoked remotely via Java Card RMI method invocation from the client. The APDU object and APDU buffer are reserved for use by RMIService. Remote method parameter data may become corrupted.
- Returns:
- the current
APDU
object being processed - Throws:
SecurityException
- if- the current context is not the context of the currently selected applet instance or
- this method was not called, directly or indirectly, from the applet's process method (called directly by the Java Card runtime environment), or
- the method is called during applet installation or deletion.
-
getCurrentAPDUBuffer
public static byte[] getCurrentAPDUBuffer() throws SecurityException
This method is called during theApplet.process(APDU)
method to obtain a reference to the current APDU buffer. This method can only be called in the context of the currently selected applet.Note:
- Do not call this method directly or indirectly from within a method
invoked remotely via Java Card RMI method invocation from the client. The
APDU
object and APDU buffer are reserved for use byRMIService
. Remote method parameter data may become corrupted.
- Returns:
- the APDU buffer of the
APDU
object being processed - Throws:
SecurityException
- if- the current context is not the context of the currently selected applet or
- this method was not called, directly or indirectly, from the applet's process method (called directly by the Java Card runtime environment), or
- the method is called during applet installation or deletion.
- Do not call this method directly or indirectly from within a method
invoked remotely via Java Card RMI method invocation from the client. The
-
getCLAChannel
public static byte getCLAChannel()
Returns the logical channel number associated with the currentAPDU
command based on the CLA byte. A number in the range 0-19 based on the CLA byte encoding is returned if the command contains logical channel encoding. If the command does not contain logical channel information, 0 is returned.Note:
- This method returns 0 if the CLA bits (b8,b7,b6) is %b001 which is a CLA encoding reserved for future use(RFU), or if CLA is 0xFF which is an invalid value as defined in the ISO 7816-4:2013 specification.
See Runtime Environment Specification, Java Card Platform, Classic Edition, section 4.3 for encoding details.
- Returns:
- logical channel number, if present, within the CLA byte, 0 otherwise
-
waitExtension
public static void waitExtension() throws APDUException
Requests additional processing time from CAD. The implementation should ensure that this method needs to be invoked only under unusual conditions requiring excessive processing times.Notes:
- In T=0 protocol, a NULL procedure byte is sent to reset the work waiting time (see ISO 7816-3).
- In T=1 protocol, the implementation needs to request the same T=0 protocol work waiting time quantum by sending a T=1 protocol request for wait time extension(see ISO 7816-3).
- If the implementation uses an automatic timer mechanism instead, this method may do nothing.
- Throws:
APDUException
- with the following reason codes:APDUException.ILLEGAL_USE
ifsetOutgoingNoChaining()
previously invoked.APDUException.IO_ERROR
if the APDU is in an error state.
-
isCommandChainingCLA
public boolean isCommandChainingCLA()
Returns whether the currentAPDU
command is the first or part of a command chain. Bit b5 of the CLA byte if set, indicates that theAPDU
is the first or part of a chain of commands.Note:
- This method returns
false
if the CLA bits (b8,b7,b6) is %b001 which is a CLA encoding reserved for future use(RFU), or if CLA is 0xFF which is an invalid value as defined in the ISO 7816-4:2013 specification.
See Runtime Environment Specification, Java Card Platform, Classic Edition, section 4.3 for encoding details.
- Returns:
true
if this APDU is not the last APDU of a command chain,false
otherwise.- Since:
- 2.2.2
- This method returns
-
isSecureMessagingCLA
public boolean isSecureMessagingCLA()
Returnstrue
if the encoding of the currentAPDU
command based on the CLA byte indicates secure messaging. The secure messaging information is in bits (b4,b3) for commands with origin channel numbers 0-3, and in bit b6 for origin channel numbers 4-19.Note:
- This method returns
false
if the CLA bits (b8,b7,b6) is %b001 which is a CLA encoding reserved for future use(RFU), or if CLA is 0xFF which is an invalid value as defined in the ISO 7816-4:2013 specification.
See Runtime Environment Specification, Java Card Platform, Classic Edition, section 4.3 for encoding details.
- Returns:
true
if the secure messaging bit(s) is(are) nonzero,false
otherwise- Since:
- 2.2.2
- This method returns
-
isISOInterindustryCLA
public boolean isISOInterindustryCLA()
Returns whether the currentAPDU
command CLA byte corresponds to an interindustry command as defined in ISO 7816-4:2013 specification. Bit b8 of the CLA byte if0
, indicates that theAPDU
is an interindustry command.- Returns:
true
if this APDU CLA byte corresponds to an ISO interindustry command,false
otherwise.- Since:
- 2.2.2
-
isValidCLA
public boolean isValidCLA()
Returns whether the currentAPDU
command CLA byte is valid. The CLA byte is invalid if the CLA bits (b8,b7,b6) is %b001, which is a CLA encoding reserved for future use(RFU), or if CLA is 0xFF which is an invalid value as defined in the ISO 7816-4:2013 specification.See Runtime Environment Specification, Java Card Platform, Classic Edition, section 4.3 for encoding details.
- Returns:
true
if this APDU CLA byte is valid,false
otherwise.- Since:
- 3.0
-
getIncomingLength
public short getIncomingLength()
Returns the incoming data length(Lc). This method can be invoked whenever inbound data processing methods can be invoked during case 1, 3 or 4 processing. It is most useful for an extended length enabled applet to avoid parsing the variable length Lc format in the APDU header.- Returns:
- the incoming byte length indicated by the Lc field in the APDU
header. Return
0
if no incoming data (Case 1) - Throws:
APDUException
- with the following reason codes:APDUException.ILLEGAL_USE
ifsetIncomingAndReceive()
not called or ifsetOutgoing()
orsetOutgoingNoChaining()
previously invoked.
- Since:
- 2.2.2
- See Also:
getOffsetCdata()
-
getOffsetCdata
public short getOffsetCdata()
Returns the offset within the APDU buffer for incoming command data. This method can be invoked whenever inbound data processing methods can be invoked during case 1, 3 or 4 processing. It is most useful for an extended length enabled applet to avoid parsing the variable length Lc format in the APDU header.- Returns:
- the offset within the APDU buffer for incoming command data from
the previous call to
setIncomingAndReceive()
method. The value returned is either 5 (Lc is 1 byte), or 7 (when Lc is 3 bytes) - Throws:
APDUException
- with the following reason codes:APDUException.ILLEGAL_USE
ifsetIncomingAndReceive()
not called or ifsetOutgoing()
orsetOutgoingNoChaining()
previously invoked.
- Since:
- 2.2.2
- See Also:
getIncomingLength()
-
-