OpenCard  
 
OCF, the OpenCard Framework is a standard Java framework for working with Smart Cards.  
 

com.ibm.opencard.service
Interface MFCCodes

All Known Subinterfaces:
MFCSigCodes
All Known Implementing Classes:
MFC35Codes, MFC41Codes
public abstract interface MFCCodes

Provides parameterization of APDUs for MFC smartcards. The majority of the methods is used to get the CLAss and INStruction bytes fopr specific commands. Some other methods specify minor details that are important in special cases, for example of a command does neither include command data nor expect response data. Additionally, there are methods that check the status word of response APDUs.

Version:
$Id: MFCCodes.java,v 1.1 1999/12/02 16:06:07 damke Exp $

Field Summary
static short MASTER_FILE
          The master file ID.
static int NOOP_BASIC_END
           
static int NOOP_FILE_END
           
static int OP_APPEND_RECORD
           
static int OP_CREATE_FILE
           
static int OP_DECREASE
           
static int OP_DELETE_FILE
           
static int OP_EXTERNAL_AUTH
           
static int OP_GET_RANDOM
           
static int OP_INCREASE
           
static int OP_INTERNAL_AUTH
           
static int OP_INVALIDATE
           
static int OP_PUT_RANDOM
           
static int OP_READ_BINARY
           
static int OP_READ_RECORD
           
static int OP_REHABILITATE
           
static int OP_SELECT
           
static int OP_UPDATE_BINARY
           
static int OP_UPDATE_RECORD
           
static int OP_VERIFY_CHV
           
 
Method Summary
 void analyseStatus(int status, byte command, java.lang.Object context)
          Analyses the status of a smartcard's response.
 int getAG(int operation)
          Returns the access group for a given operation.
 byte getAskRandomByte()
           
 int getBlockSize()
          The maximum block size for data transfers.
 byte getClassByte()
          The CLAss byte for non-ISO commands.
 byte getINS(int operation)
          Returns the instruction byte for a given operation.
 byte getISOClassByte()
          The CLAss byte for ISO commands.
 byte getReadRecordByte()
           
 boolean indicatesError(int status)
          Checks whether a status word indicates an error.
 boolean needsZeroLc()
          Whether a command data length of zero is explicit.
 boolean needsZeroLe()
          Whether an expected response data length of zero is explicit.
 boolean needsZeroLe(boolean info)
          Whether an expected explicit zero Le is specified for select.
 

Field Detail

MASTER_FILE

public static final short MASTER_FILE
The master file ID. It is identical for all MFC cards, and it conforms to the ISO standard. There is no reason to expect it to change, so it is an attribute rather than a method.

OP_SELECT

public static final int OP_SELECT

OP_GET_RANDOM

public static final int OP_GET_RANDOM

OP_PUT_RANDOM

public static final int OP_PUT_RANDOM

OP_VERIFY_CHV

public static final int OP_VERIFY_CHV

OP_EXTERNAL_AUTH

public static final int OP_EXTERNAL_AUTH

OP_INTERNAL_AUTH

public static final int OP_INTERNAL_AUTH

NOOP_BASIC_END

public static final int NOOP_BASIC_END

OP_READ_BINARY

public static final int OP_READ_BINARY

OP_READ_RECORD

public static final int OP_READ_RECORD

OP_UPDATE_BINARY

public static final int OP_UPDATE_BINARY

OP_UPDATE_RECORD

public static final int OP_UPDATE_RECORD

OP_APPEND_RECORD

public static final int OP_APPEND_RECORD

OP_CREATE_FILE

public static final int OP_CREATE_FILE

OP_DELETE_FILE

public static final int OP_DELETE_FILE

OP_INVALIDATE

public static final int OP_INVALIDATE

OP_REHABILITATE

public static final int OP_REHABILITATE

OP_INCREASE

public static final int OP_INCREASE

OP_DECREASE

public static final int OP_DECREASE

NOOP_FILE_END

public static final int NOOP_FILE_END
Method Detail

getBlockSize

public int getBlockSize()
The maximum block size for data transfers.
Returns:
the block size for splitting read and write commands

needsZeroLc

public boolean needsZeroLc()
Whether a command data length of zero is explicit. The commands to invalidate or rehabilitate a file on the smartcard neither provide nor request data. With the MFC 4.1, the command APDU will consist of only 4 bytes, while previous MFC cards require an explicit Lc byte with value 0.
Returns:
true iff a zero Lc byte has to be part of the APDU

needsZeroLe

public boolean needsZeroLe()
Whether an expected response data length of zero is explicit. The commands to increase or decrease the value of a record in a structured file return the contents of the record and the amount that was sent with the command. For MFC 3.5 and 4.0, no expected length byte (Le) has to be provided. With the MFC 4.1, this byte is required but can be set to 0, so the card will send as many bytes as there are to send.
This method is also used to build the command APDU for reading a record. In the case of the MFC 4.1, the expected length must be set to zero to avoid trouble with secure messaging.
Finally, there is the select command. The MFC 3.5 and 4.0 do not allow an Le byte for select, the MFC 4.1 does. The german GeldKarte even requires the Le byte, at least in some cases. See also needsZeroLe(boolean).
This method could have been named isZeroLeSufficient or something like that, but since it corresponds to needsZeroLc, a corresponding name has been chosen, too.
Returns:
true iff Le has to be specified for increase or decrease
See Also:
needsZeroLc(), needsZeroLe(boolean)

needsZeroLe

public boolean needsZeroLe(boolean info)
Whether an expected explicit zero Le is specified for select. With the german GeldKarte, a zero Le must be given only if some bytes are expected at all. This method deals with this special case.
Parameters:
info - whether a response is expected at all
Returns:
true if a zero Le has to be appended, false otherwise
See Also:
needsZeroLe()

getINS

public byte getINS(int operation)
Returns the instruction byte for a given operation.
Parameters:
operation - a number indicating the operation
Returns:
the instruction byte for the operation

getAG

public int getAG(int operation)
Returns the access group for a given operation. Commands are grouped according to the access type, for example READ or UPDATE. For different cards, different numbers of these groups, and different groups for the same commands may be defined. This method returns the group number for a given command, which can be used to obtain the access conditions from the appropriate access information.
Parameters:
operation - a number indicating the operation
Returns:
the access group for that operation, or -1 if no access conditions have to be satisfied or if the operation is unknown

getISOClassByte

public byte getISOClassByte()
The CLAss byte for ISO commands. Up to and including MFC 4.0, all standard commands share the same command class. MFC 4.1 distinguishes between ISO and non-ISO commands, for example UPDATE BINARY and CREATE. This method returns the class for the standard commands defined by ISO 7816-4.
Returns:
the CLAss of ISO standard INStructions

getClassByte

public byte getClassByte()
The CLAss byte for non-ISO commands.
Returns:
the CLAss of non-ISO standard INStructions

getAskRandomByte

public byte getAskRandomByte()

getReadRecordByte

public byte getReadRecordByte()

analyseStatus

public void analyseStatus(int status,
                          byte command,
                          java.lang.Object context)
                   throws CardServiceException
Analyses the status of a smartcard's response. If the status indicates successful completion of a command, the method returns without further action. If the status indicates an error, an exception is thrown. The instruction byte of the command that was responded is given as second parameter, to allow context-sensitive error checking.
This method should be consistent with indicatesError. The easiest way to achieve this is to check the status using indicatesError and to return immeadiately if false is returned. If an error is indicated, an exception should be thrown, even if no specific error message can be generated.
Parameters:
status - the status word returned by the smartcard. It is passed as an int to conform to the method sw in class ResponseAPDU.
command - the INStruction byte that was sent to the smartcard. It can be used to determine a context-sensitive exception message.
context - an object specifying the context in which the response was received. This parameter is optional and may get evaluated to determine an appropriate exception message. For example, if a select command was issued, the context would be the path to the selected card file.
Throws:
CardServiceException - the status indicates an error
See Also:
ResponseAPDU.sw()

indicatesError

public boolean indicatesError(int status)
Checks whether a status word indicates an error. Unlike analyseStatus, this method does never throw an exception. There is also no context-sensitivity involved.
Parameters:
status - the status word to check. It is passed as an int rather than a short, to conformto the method sw in class ResponseAPDU.
Returns:
true if the status indicates an error, false otherwise
See Also:
analyseStatus(int, byte, java.lang.Object), ResponseAPDU.sw()