javacard.framework.service
Class BasicService

java.lang.Object
  javacard.framework.service.BasicService

All Implemented Interfaces:

Service

Direct Known Subclasses:

RMIService

public class BasicService
extends Object
implements Service

This class should be used as the base class for implementing services. It provides a default implementation for the methods defined in the Service interface, and defines a set of helper methods that manage the APDU buffer to enable co-operation among different Services.

The BasicService class uses the state of APDU processing to enforce the validity of the various helper operations. It expects and maintains the following Common Service Format (CSF) of data in the APDU Buffer corresponding to the various APDU processing states (See APDU ):

 Init State format of APDU Buffer. This format corresponds to the
 APDU processing state - STATE_INITIAL :
  0     1    2    3    4    5  <- offset
 +------------------------------------------------------------+
 | CLA | INS | P1 | P2 | P3 | ... Implementation dependent ...|
 +------------------------------------------------------------+


 Input Ready format of APDU Buffer. This format corresponds
 to the APDU processing state - STATE_FULL_INCOMING.
  0     1    2    3    4    5  <- offset
 +------------------------------------------------------------+
 | CLA | INS | P1 | P2 | Lc | Incoming Data( Lc bytes )       |
 +------------------------------------------------------------+


 Output Ready format of APDU Buffer. This format corresponds
 to the APDU processing status - STATE_OUTGOING .. STATE_FULL_OUTGOING
  0     1    2     3     4    5  <- offset
 +------------------------------------------------------------+
 | CLA | INS | SW1 | SW2 | La | Outgoing Data( La bytes )     |
 +------------------------------------------------------------+


 

When the APDU buffer is in the Init and Input Ready formats, the helper methods allow input access methods but flag errors if output access is attempted. Conversely, when the APDU buffer is in the Output format, input access methods result in exceptions.

The Common Service Format (CSF) of the APDU Buffer is only defined for APDUs using the short length (normal semantics) of the ISO7816 protocol. When an implementation supports extended length APDU format (see ExtendedLength) and an APDU with more than 255 input or output data bytes is being processed, the behavior of BasicService class is undefined.

If the header areas maintained by the BasicService helper methods are modified directly in the APDU buffer and the format of the APDU buffer described above is not maintained, unexpected behavior might result.

In addition, both La=0 and La=256 are represented in the CSF format as La=0. The distinction is implementation dependent. The getOutputLength method must be used to avoid ambiguity.

Many of the helper methods also throw exceptions if the APDU object is in an error state ( processing status code < 0 ).

Version:

1.0

See Also:

APDU, javacardx.apdu.ExtendedLength

Constructor Summary

BasicService()
Creates new BasicService.

Method Summary

boolean	fail(APDU apdu, short sw) Sets the processing state for the command in the APDU object to processed, and indicates that the processing has failed.
byte	getCLA(APDU apdu) Returns the class byte for the command in the APDU object.
byte	getINS(APDU apdu) Returns the instruction byte for the command in the APDU object.
short	getOutputLength(APDU apdu) Returns the output length for the command in the APDU object.
byte	getP1(APDU apdu) Returns the first parameter byte for the command in the APDU object.
byte	getP2(APDU apdu) Returns the second parameter byte for the command in the APDU object.
short	getStatusWord(APDU apdu) Returns the response status word for the command in the APDU object.
boolean	isProcessed(APDU apdu) Checks if the command in the APDU object has already been processed.
boolean	processCommand(APDU apdu) This BasicService method is a default implementation and simply returns false without performing any processing.
boolean	processDataIn(APDU apdu) This BasicService method is a default implementation and simply returns false without performing any processing.
boolean	processDataOut(APDU apdu) This BasicService method is a default implementation and simply returns false without performing any processing.
short	receiveInData(APDU apdu) Receives the input data for the command in the APDU object if the input has not already been received.
boolean	selectingApplet() This method is used to determine if the command in the APDU object is the applet SELECT FILE command which selected the currently selected applet.
void	setOutputLength(APDU apdu, short length) Sets the output length of the outgoing response for the command in the APDU object.
void	setProcessed(APDU apdu) Sets the processing state of the command in the APDU object to processed.
void	setStatusWord(APDU apdu, short sw) Sets the response status word for the command in the APDU object.
boolean	succeed(APDU apdu) Sets the processing state for the command in the APDU object to processed, and indicates that the processing has succeeded.
boolean	succeedWithStatusWord(APDU apdu, short sw) Sets the processing state for the command in the APDU object to processed, and indicates that the processing has partially succeeded.

Methods inherited from class java.lang.Object

equals

Constructor Detail

BasicService

public BasicService()

Creates new BasicService.

Method Detail

processDataIn

public boolean processDataIn(APDU apdu)

This BasicService method is a default implementation and simply returns false without performing any processing.

Specified by:

processDataIn in interface Service

Parameters:

apdu - the APDU object containing the command being processed

Returns:

false

processCommand

public boolean processCommand(APDU apdu)

This BasicService method is a default implementation and simply returns false without performing any processing.

Specified by:

processCommand in interface Service

Parameters:

apdu - the APDU object containing the command being processed

Returns:

false

processDataOut

public boolean processDataOut(APDU apdu)

This BasicService method is a default implementation and simply returns false without performing any processing.

Specified by:

processDataOut in interface Service

Parameters:

apdu - the APDU object containing the command being processed

Returns:

false

receiveInData

public short receiveInData(APDU apdu)
                    throws ServiceException

Receives the input data for the command in the APDU object if the input has not already been received. The entire input data must fit in the APDU buffer starting at offset 5. When invoked, the APDU object must either be in STATE_INITIAL with the APDU buffer in the Init format or in STATE_FULL_INCOMING with the APDU buffer in the Input Ready format

Parameters:

apdu - the APDU object containing the apdu being processed

Returns:

the length of input data received and present in the APDU Buffer

Throws:

ServiceException - with the following reason code:

• ServiceException.CANNOT_ACCESS_IN_COMMAND if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING or,
• ServiceException.COMMAND_DATA_TOO_LONG if the input data does not fit in the APDU buffer starting at offset 5.

setProcessed

public void setProcessed(APDU apdu)
                  throws ServiceException

Sets the processing state of the command in the APDU object to processed. This is done by setting the APDU object in outgoing mode by invoking the APDU.setOutgoing method. If the APDU is already in outgoing mode, this method does nothing (allowing the method to be called several times).

Parameters:

apdu - the APDU object containing the command being processed

Throws:

ServiceException - with the following reason code:

• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the APDU object is not accessible (APDU object in STATE_ERROR_.. )

See Also:

javacard.framework.APDU.getCurrentState()

isProcessed

public boolean isProcessed(APDU apdu)

Checks if the command in the APDU object has already been processed. This is done by checking whether or not the APDU object has been set in outgoing mode via a previous invocation of the APDU.setOutgoing method.

Note:

• This method returns true if the APDU object is not accessible (APDU object in STATE_ERROR_.. ).

Parameters:

apdu - the APDU object containing the command being processed

Returns:

true if the command has been processed, false otherwise

setOutputLength

public void setOutputLength(APDU apdu,
                            short length)
                     throws ServiceException

Sets the output length of the outgoing response for the command in the APDU object. This method can be called regardless of the current state of the APDU processing.

Parameters:

apdu - the APDU object containing the command being processed

length - the number of bytes in the response to the command

Throws:

ServiceException - with the following reason code:

• ServiceException.ILLEGAL_PARAM if the length parameter is greater than 256 or if the outgoing response will not fit within the APDU Buffer.

getOutputLength

public short getOutputLength(APDU apdu)
                      throws ServiceException

Returns the output length for the command in the APDU object. This method can only be called if the APDU processing state indicates that the command has been processed.

Parameters:

apdu - the APDU object containing the command being processed

Returns:

a value in the range: 0 to 256(inclusive), that represents the number of bytes to be returned for this command

Throws:

ServiceException - with the following reason code:

• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the command is not processed or if the APDU object is not accessible (APDU object in STATE_ERROR_.. )

See Also:

javacard.framework.APDU.getCurrentState()

setStatusWord

public void setStatusWord(APDU apdu,
                          short sw)

Sets the response status word for the command in the APDU object. This method can be called regardless of the APDU processing state of the current command.

Parameters:

apdu - the APDU object containing the command being processed

sw - the status word response for this command

getStatusWord

public short getStatusWord(APDU apdu)
                    throws ServiceException

Returns the response status word for the command in the APDU object. This method can only be called if the APDU processing state indicates that the command has been processed.

Parameters:

apdu - the APDU object containing the command being processed

Returns:

the status word response for this command

Throws:

ServiceException - with the following reason code:

• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the command is not processed or if the APDU object is not accessible (APDU object in STATE_ERROR_.. )

See Also:

javacard.framework.APDU.getCurrentState()

fail

public boolean fail(APDU apdu,
                    short sw)
             throws ServiceException

Sets the processing state for the command in the APDU object to processed, and indicates that the processing has failed. Sets the output length to 0 and the status word of the response to the specified value.

Parameters:

apdu - the APDU object containing the command being processed

sw - the status word response for this command

Returns:

true

Throws:

ServiceException - with the following reason code:

• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the APDU object is not accessible (APDU object in STATE_ERROR_.. )

See Also:

javacard.framework.APDU.getCurrentState()

succeed

public boolean succeed(APDU apdu)
                throws ServiceException

Sets the processing state for the command in the APDU object to processed, and indicates that the processing has succeeded. Sets the status word of the response to 0x9000. The output length of the response must be set separately.

Parameters:

apdu - the APDU object containing the command being processed.

Returns:

true

Throws:

ServiceException - with the following reason code:

• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the APDU object is not accessible (APDU object in STATE_ERROR_.. )

See Also:

javacard.framework.APDU.getCurrentState()

succeedWithStatusWord

public boolean succeedWithStatusWord(APDU apdu,
                                     short sw)
                              throws ServiceException

Sets the processing state for the command in the APDU object to processed, and indicates that the processing has partially succeeded. Sets the the status word of the response to the specified value. The output length of the response must be set separately.

Parameters:

apdu - the APDU object containing the command being processed

sw - the status word to be returned for this command

Returns:

true

Throws:

ServiceException - with the following reason code:

• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the APDU object is not accessible (APDU object in STATE_ERROR_.. )

See Also:

javacard.framework.APDU.getCurrentState()

getCLA

public byte getCLA(APDU apdu)

Returns the class byte for the command in the APDU object. This method can be called regardless of the APDU processing state of the current command.

Parameters:

apdu - the APDU object containing the command being processed

Returns:

the value of the CLA byte

getINS

public byte getINS(APDU apdu)

Returns the instruction byte for the command in the APDU object. This method can be called regardless of the APDU processing state of the current command.

Parameters:

apdu - the APDU object containing the command being processed

Returns:

the value of the INS byte

getP1

public byte getP1(APDU apdu)
           throws ServiceException

Returns the first parameter byte for the command in the APDU object. When invoked, the APDU object must be in STATE_INITIAL or STATE_FULL_INCOMING.

Parameters:

apdu - the APDU object containing the command being processed

Returns:

the value of the P1 byte

Throws:

ServiceException - with the following reason code:

• ServiceException.CANNOT_ACCESS_IN_COMMAND if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING.

getP2

public byte getP2(APDU apdu)
           throws ServiceException

Returns the second parameter byte for the command in the APDU object. When invoked, the APDU object must be in STATE_INITIAL or STATE_FULL_INCOMING.

Parameters:

apdu - the APDU object containing the command being processed

Returns:

the value of the P2 byte

Throws:

ServiceException - with the following reason code:

• ServiceException.CANNOT_ACCESS_IN_COMMAND if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING.

selectingApplet

public boolean selectingApplet()

This method is used to determine if the command in the APDU object is the applet SELECT FILE command which selected the currently selected applet.

Returns:

true if applet SELECT FILE command is being processed