org.globalplatform
Interface SecureChannel

All Superinterfaces:

javacard.framework.Shareable

public interface SecureChannel

extends javacard.framework.Shareable

This interface may be used by an applet wishing to delegate the handling of entity authentication and APDU security to its associated Security Domain. This interface is designed to offer interoperability to the applet in that it requires no knowledge of the mechanisms used to perform the authentication or of the scheme used for APDU security and shall allow an applet to interface correctly with a Security Domain immaterial of the mechanisms or schemes used. Prior to using this interface, an Application is required to obtain a handle to its associated Security Domain by invoking the GPSystem.getSecureChannel() method. The Secure Channel Interface shall only be exposed through the GPSystem.getSecureChannel method

The byte value returned by the getSecurityLevel() method is a bit map indicating whether Entity Authentication has occurred and what level of security will be applied when invoking the wrap and unwrap methods. This byte value is coded according to table A-1. Note that more than one security level may be set.

Field Summary

static byte	AUTHENTICATED Entity Authentication has occurred (0x80).
static byte	C_DECRYPTION The unwrap method will decrypt incoming command data (0x02).
static byte	C_MAC The unwrap method will verify the MAC on an incoming command (0x01).
static byte	NO_SECURITY_LEVEL Entity Authentication has not occurred (0x00).
static byte	R_ENCRYPTION The wrap method will encrypt the outgoing response data (0x20).
static byte	R_MAC The wrap method will generate a MAC for the outgoing response data (0x10).

Method Summary

short	decryptData(byte[] baBuffer, short sOffset, short sLength) This method is used to decrypt data located in the input buffer.
short	encryptData(byte[] baBuffer, short sOffset, short sLength) This method is used to encrypt data located in the input buffer.
byte	getSecurityLevel() This method is used to determine whether the Security Domain has performed authentication and to determine what level of security will be applied by the wrap and unwrap methods.
short	processSecurity(javacard.framework.APDU apdu) Processes security related APDU commands.
void	resetSecurity() This method is used to reset information relating to the current Secure Channel.
short	unwrap(byte[] baBuffer, short sOffset, short sLength) This method is used to process and verify the secure messaging of an incoming command according to the security level.
short	wrap(byte[] baBuffer, short sOffset, short sLength) This method is used to apply additional security processing to outgoing response data and Status Words according to the security level.

Field Detail

AUTHENTICATED

public static final byte AUTHENTICATED

Entity Authentication has occurred (0x80).

Note:

• Entity Authentication and the level of security that will be applied by the wrap and unwrap methods are not necessarily related. A Security Domain, by default, could verify the MAC on any command passed as a parameter in the unwrap method without entity authentication previously having occurred.

  See Also:

  Constant Field Values

C_DECRYPTION

public static final byte C_DECRYPTION

The unwrap method will decrypt incoming command data (0x02).

Note:

• Command data decryption could be indicated along with entity authentication and one or more levels of security.

  See Also:

  Constant Field Values

C_MAC

public static final byte C_MAC

The unwrap method will verify the MAC on an incoming command (0x01).

Note:

• MAC verification could be indicated along with entity authentication and one or more levels of security, e.g. a value of '03' indicates that while entity authentication has not occurred, the unwrap method will decrypt the command data of incoming commands and verify the MAC on incoming commands.

  See Also:

  Constant Field Values

R_ENCRYPTION

public static final byte R_ENCRYPTION

The wrap method will encrypt the outgoing response data (0x20).

Note:

• Response data encryption could be indicated along with entity authentication and one or more levels of security.

  See Also:

  Constant Field Values

R_MAC

public static final byte R_MAC

The wrap method will generate a MAC for the outgoing response data (0x10).

Note:

• MAC generation could be indicated along with entity authentication and one or more levels of security, e.g. a value of '91' indicates that entity authentication has occurred, that the unwrap method will verify the MAC on incoming commands and that the wrap method will generate a MAC on outgoing response data.

  See Also:

  Constant Field Values

NO_SECURITY_LEVEL

public static final byte NO_SECURITY_LEVEL

Entity Authentication has not occurred (0x00).

Note:

• Entity Authentication and the level of security that will be applied by the wrap and unwrap methods are not necessarily related. A Security Domain, by default, could verify the MAC on any command passed as a parameter in the unwrap method without entity authentication previously having occurred.
• The wrap and unwrap methods will not apply any cryptographic processing to command or response data.

  See Also:

  Constant Field Values

Method Detail

processSecurity

public short processSecurity(javacard.framework.APDU apdu)
                      throws javacard.framework.ISOException

Processes security related APDU commands.

This method is used by an applet to process APDU commands that possibly relate to the security mechanism used by the Security Domain. As the intention is to allow an applet to be associated with a Security Domain without having any knowledge of the security mechanisms used by the Security Domain, the applet assumes that APDU commands that it does not recognize are part of the security mechanism and will be recognized by the Security Domain. The applet can either invoke this method prior to determining if it recognizes the instruction or only invoke this method for instructions it does not recognize.

Notes:

• The method is responsible for receiving the data field of commands that are recognized.
• The applet is responsible for recognizing instructions that the method refused to process.
• The applet is responsible for outputting status words returned due to the processing of instructions recognized by the method.
• If response data is present, this data will be placed in the APDU buffer at offset ISO7816.OFFSET_CDATA. The return value indicates the length and the applet is responsible for outputting this data if necessary.

Parameters:

apdu - the incoming APDU object.

Returns:

the number of bytes to be output.

Throws:

javacard.framework.ISOException - with the following reason codes (other security mechanism related status words may be returned):

• ISO7816.SW_CLA_NOT_SUPPORTED class byte is not recognized by the method.
• ISO7816.SW_INS_NOT_SUPPORTED instruction byte is not recognized by the method.

wrap

public short wrap(byte[] baBuffer,
                  short sOffset,
                  short sLength)
           throws java.lang.ArrayIndexOutOfBoundsException,
                  javacard.framework.ISOException

This method is used to apply additional security processing to outgoing response data and Status Words according to the security level.

Notes:

• The applet is able to ensure that the security level it requires (R_MAC, R_ENCRYPTION) will be applied by invoking the getSecurityLevel() method.
• The getSecurityLevel() method invocation may also indicate that entity authentication (AUTHENTICATED) has previously occurred.
• If NO_SECURITY_LEVEL is indicated, this method will do no processing.

Parameters:

baBuffer - the source of the data to be wrapped. This buffer must be global.

sOffset - the offset within baBuffer of the data to wrap.

sLength - the length of the data to wrap.

Returns:

the length of the wrapped data.

Throws:

javacard.framework.ISOException - security mechanism related status words might be returned.

java.lang.ArrayIndexOutOfBoundsException - if wrapping produces data outside array bounds.

unwrap

public short unwrap(byte[] baBuffer,
                    short sOffset,
                    short sLength)
             throws javacard.framework.ISOException

This method is used to process and verify the secure messaging of an incoming command according to the security level.

Notes:

• The applet is able to query what level of security will be assumed (C_MAC, C_DECRYPTION) to be present by the Security Domain by invoking the getSecurityLevel() method.
• The getSecurityLevel() method invocation may also indicate that entity authentication (AUTHENTICATED) has previously occurred.
• If NO_SECURITY_LEVEL is indicated, this method will do no processing.
• If the class byte does not indicate secure messaging (ISO 7816-4), this method will do no processing.
• The applet is responsible for receiving the data field of the command.
• Correct processing of the unwrap method will result in the incoming command being reformatted within the incoming APDU object with all data relating to the Secure Messaging removed.
• Incorrect processing of the unwrap method will result in the information relating to the current Secure Channel being reset.

Parameters:

baBuffer - the source of the data to be unwrapped. This buffer must be global.

sOffset - the offset within baBuffer of the data to unwrap.

sLength - the length of the data to unwrap.

Returns:

the length of the unwrapped data.

Throws:

javacard.framework.ISOException - with the following reason code (other security mechanism related status words may be returned):

• ISO7816.SW_CLA_NOT_SUPPORTED class byte is not recognized by the method.

decryptData

public short decryptData(byte[] baBuffer,
                         short sOffset,
                         short sLength)
                  throws javacard.framework.ISOException

This method is used to decrypt data located in the input buffer.

Notes:

• The Security Domain implicitly knows the key to be used for decryption.
• The Security Domain is implicitly aware of any padding that may be present in the decrypted data and this is discarded.
• The clear text data replaces the ciphered data within the byte array. The removal of padding may cause the length of the clear text data to be shorter than the length of the ciphered data.
• The applet is responsible for checking the integrity of the decrypted data.

Parameters:

baBuffer - the byte array containing the data to be processed. This buffer must be global.

sOffset - offset within the byte array to start the decryption.

sLength - the number of bytes to decrypt.

Returns:

The length of the clear text data.

Throws:

javacard.framework.ISOException - if the length of data to be decrypted is not valid.

encryptData

public short encryptData(byte[] baBuffer,
                         short sOffset,
                         short sLength)
                  throws java.lang.ArrayIndexOutOfBoundsException

This method is used to encrypt data located in the input buffer.

Notes:

• The Security Domain is implicitly aware of any padding that must be applied to the clear text data prior to encryption.
• The Security Domain implicitly knows the key to be used for encryption.
• The ciphered data replaces the clear text data within the byte array.
• Due to padding, the length of the ciphered data may be longer than the length of the clear text data and the applet must make allowances for this.

Parameters:

baBuffer - the byte array containing the data to be processed. This buffer must be global.

sOffset - offset within the byte array to start the encryption.

sLength - the number of bytes to encrypt.

Returns:

The length of the encrypted data.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if enciphering produces data outside array bounds.

resetSecurity

public void resetSecurity()

This method is used to reset information relating to the current Secure Channel.

Notes:

• Applets using the services of a Security Domain should invoke this method in the Applet.deselect() method.
• The Security Domain will reset all information relating to the current Secure Channel, i.e. all Secure Channel session keys, state information and security level information will be erased.
• This method shall not fail if no Secure Channel has been initiated.

getSecurityLevel

public byte getSecurityLevel()

This method is used to determine whether the Security Domain has performed authentication and to determine what level of security will be applied by the wrap and unwrap methods.

Notes:

• Applets must invoke this method to ensure that application specific security requirements have been previously met or will be enforced by the Security Domain.
• More than one level of security may be active and these may change during a Secure Channel, e.g. an R_MAC session may be initiated during a C_MAC session.

Returns:

NO_SECURITY_LEVEL (0x00) indicating that Entity Authentication has not occurred and that the wrap and unwrap methods will not apply any cryptographic processing to command or response data, or a bitmap of the security level as follows:

• AUTHENTICATED (0x80): Entity authentication has occurred.
• C_MAC (0x01): The unwrap method will verify the MAC on the incoming command.
• R_MAC (0x10): The wrap method will generate a MAC for the outgoing response data.
• C_DECRYPTION (0x02): The unwrap method will decrypt the incoming command data.
• R_ENCRYPTION (0x20): The wrap method will encrypt the outgoing response data.