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

com.ibm.opencard.access
Class MFCSecureMessenger

java.lang.Object
  |
  +--com.ibm.opencard.access.MFCSecurityHelper
        |
        +--com.ibm.opencard.access.MFCSecureMessenger
Direct Known Subclasses:
MFC35SecureMessenger, MFC41SecureMessenger
public abstract class MFCSecureMessenger
extends MFCSecurityHelper
implements MFCProtector, MFCEncryptor

Base class for combined protectors and encryptors. An exhaustive description of the responsibilities of a protector can be found in the interface MFCProtector. A shorter description of the responsibilities of an encryptor can be found in the interface MFCEncryptor.
The proprietary secure messaging for MFC 3.5 and 4.0 is significantly different from the ISO secure messaging supported by MFC 4.1 smartcards. On the other hand, the protocol introduced by the interfaces is the same for both, so this abstract base class can simplify implementing the card-specific helpers.

Version:
$Id: MFCSecureMessenger.java,v 1.1 1999/12/02 16:06:01 damke Exp $
See Also:
MFCProtector, MFCEncryptor

Field Summary
protected  SecureCredential phase_cred
          Holds the credential to use in the current phase.
protected  int phase_expected
          Holds the number of bytes expected for the response in the current phase.
protected  byte[] phase_random
          Holds the 8 byte random number sent to the smartcard in the current phase.
protected  boolean process_response
          Specifies whether the response has to be processed.
protected static byte[] zero_icv
          The initial chaining value for MAC computation, all zero by default.
 
Constructor Summary
MFCSecureMessenger(MFCCodes codes)
          Instantiates a new secure messenger.
 
Method Summary
 void abortEncryption()
          Leaves an encryption phase due to an error.
 void abortProtection()
          Leaves a protection phase due to an error.
abstract  CommandAPDU enterEncryption(MFCCardChannel channel, MFCCommandAPDU command, int number)
          Enters an encryption phase.
abstract  CommandAPDU enterProtection(MFCCardChannel channel, MFCCommandAPDU command, int number)
          Enters a protection phase.
protected  void finishPhase()
          Finishes a protection or encryption phase.
abstract  ResponseAPDU leaveEncryption(ResponseAPDU response)
          Leaves an encryption phase.
abstract  ResponseAPDU leaveProtection(ResponseAPDU response)
          Leaves a protection phase.
protected  void prepareResponse(MFCCardChannel channel, SecureCredential cred)
          Prepares a protected or encrypted smartcard response.
 
Methods inherited from class com.ibm.opencard.access.MFCSecurityHelper
getMFCCodes, lookupSecureCredential, lookupSignCredential, provideRandom, requestRandom, setCredentials
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

process_response

protected boolean process_response
Specifies whether the response has to be processed. This flag gets initialized on entering a protection or encryption phase. If the response to the command will include data that has to be checked or decrypted, this flag is set to true. Otherwise, it is set to false. The flag will be evaluated when leaving the respective phase.

phase_cred

protected SecureCredential phase_cred
Holds the credential to use in the current phase. This attribute gets initialized on entering a protection or encryption phase. It's value is valid only if process_response is set. If the response to a command does not have to be processed, that is if process_response is not set, there is no need to remeber the credential used to protect the command.
See Also:
process_response

phase_random

protected byte[] phase_random
Holds the 8 byte random number sent to the smartcard in the current phase. This attribute gets initialized on entering a protection or encryption phase. It's value is valid only if process_response is set. If the response to a command does not have to be processed, that is if process_response is not set, there is no need to send a random number to the card, so there is nothing to remember here.
See Also:
process_response

phase_expected

protected int phase_expected
Holds the number of bytes expected for the response in the current phase. This attribute gets initialized on entering an encryption phase. It's value is valid only if process_response is set, and the phase is an encryption phase.
See Also:
process_response

zero_icv

protected static final byte[] zero_icv
The initial chaining value for MAC computation, all zero by default.
Constructor Detail

MFCSecureMessenger

public MFCSecureMessenger(MFCCodes codes)
Instantiates a new secure messenger. MFC 4.1 supports a compatibility mode, but to use it MFC 4.0 command codes would have to be used. The standard mode for the MFC 4.1 is ISO secure messaging, which has to be implemented in a different class.
Parameters:
codes - the command codes for MFC 3.5 or 4.0
Method Detail

enterProtection

public abstract CommandAPDU enterProtection(MFCCardChannel channel,
                                            MFCCommandAPDU command,
                                            int number)
                                     throws CardServiceUnexpectedResponseException,
                                            CardTerminalException
Enters a protection phase. For an exhaustive description of protection phases, see the interface MFCProtector for which this method is required.
Specified by:
enterProtection in interface MFCProtector
Parameters:
channel - how to contact the smartcard
command - the APDU to compute a MAC for
number - identifier of the protection key
Returns:
the command APDU to send to the card, including a MAC if required
Throws:
CardServiceUnexpectedResponseException - A command sent to the smartcard failed.
CardTerminalException - The terminal failed sending a command to the smartcard.
See Also:
MFCProtector, leaveProtection(opencard.core.terminal.ResponseAPDU)

leaveProtection

public abstract ResponseAPDU leaveProtection(ResponseAPDU response)
                                      throws CardServiceUnexpectedResponseException,
                                             CardServiceInvalidCredentialException
Leaves a protection phase. For an exhaustive description of protection phases, see the interface MFCProtector for which this method is required. This method expects that the response's status is ok. It may not be invoked with an error or null response APDU.
Specified by:
leaveProtection in interface MFCProtector
Parameters:
response - the APDU received from the smartcard
Returns:
the smartcard's response, without the MAC
Throws:
CardServiceUnexpectedResponseException - The response to verify has a bad message format.
CardServiceUnexpectedResponseException - The response to verify is not authentic.
See Also:
MFCProtector, enterProtection(com.ibm.opencard.service.MFCCardChannel, com.ibm.opencard.service.MFCCommandAPDU, int)

abortProtection

public final void abortProtection()
Leaves a protection phase due to an error. This method is invoked if the smartcard's response to the command sent in the protection phase could not be received or indicated an error. There is no response for which a MAC may have to be checked.
This method is also invoked internally, to reset the phase attributes on regular phase termination.
Specified by:
abortProtection in interface MFCProtector

enterEncryption

public abstract CommandAPDU enterEncryption(MFCCardChannel channel,
                                            MFCCommandAPDU command,
                                            int number)
                                     throws CardServiceUnexpectedResponseException,
                                            CardTerminalException
Enters an encryption phase. Encryption phases are similiar to protection phases. For an exhaustive description of protection phases, see the interface MFCProtector. The interface MFCEncryptor, for which this method is required, has a similiar structure.
Specified by:
enterEncryption in interface MFCEncryptor
Parameters:
channel - how to contact the smartcard
command - the APDU to encrypt (potentially)
number - identifier of the encryption key
Returns:
the command APDU to send to the card, including a MAC if required
Throws:
CardServiceUnexpectedResponseException - A command sent to the smartcard failed.
CardTerminalException - The terminal failed sending a command to the smartcard.
See Also:
MFCProtector, MFCEncryptor, leaveEncryption(opencard.core.terminal.ResponseAPDU), abortEncryption()

leaveEncryption

public abstract ResponseAPDU leaveEncryption(ResponseAPDU response)
                                      throws CardServiceUnexpectedResponseException,
                                             CardServiceInvalidCredentialException
Leaves an encryption phase. Encryption phases are similiar to protection phases, which are described exhaustively in the interface MFCProtector. The interface MFCEncryptor, for which this method is required, has the same structure.
This method expects that the response's status is ok. It may not be invoked with an error or null response APDU.
Specified by:
leaveEncryption in interface MFCEncryptor
Parameters:
response - the APDU received from the smartcard
Returns:
the smartcard's unencrypted response
Throws:
CardServiceUnexpectedResponseException - The response to decrypt has a bad message format.
CardServiceInvalidCredentialException - The response to decrypt is not authentic.
See Also:
MFCProtector, MFCEncryptor, enterEncryption(com.ibm.opencard.service.MFCCardChannel, com.ibm.opencard.service.MFCCommandAPDU, int)

abortEncryption

public final void abortEncryption()
Leaves an encryption phase due to an error. This method is invoked if the smartcard's response to the command sent in the encryption phase could not be received or indicated an error. There is no response which may have to be decrypted.
This method is also invoked internally, to reset the phase attributes on regular phase termination.
Specified by:
abortEncryption in interface MFCEncryptor
See Also:
enterEncryption(com.ibm.opencard.service.MFCCardChannel, com.ibm.opencard.service.MFCCommandAPDU, int), leaveEncryption(opencard.core.terminal.ResponseAPDU)

prepareResponse

protected final void prepareResponse(MFCCardChannel channel,
                                     SecureCredential cred)
                              throws CardServiceUnexpectedResponseException,
                                     CardTerminalException
Prepares a protected or encrypted smartcard response. This method sends a random number to the smartcard, which will be used to protect or encrypt the response. It also sets the flag process_response and stores the random number in phase_random and the credential in phase_cred. Only phase_expected is not initialized, since it's value depends on data not known in this method.
This method is invoked on entering a protection or encryption phase, and only if the response will contain protected or encrypted data. The counterpart is finishPhase, which will reset the attributes mentioned above, whether they have been set here or not.
Parameters:
channel - the contact to the smartcard
cred - the credential to get the random number from
Throws:
CardServiceUnexpectedResponseException - The command sending a random number to the smartcard failed.
CardTerminalException - The terminal failed sending the command to the smartcard.
See Also:
process_response, phase_random, phase_cred, phase_expected, finishPhase()

finishPhase

protected final void finishPhase()
Finishes a protection or encryption phase. The attributes valid only during a phase get reset. This method is a kind of counterpart to prepareResponse, since most of the attributes valid during a phase get set there.