org.globalplatform
Interface SecureChannel

All Superinterfaces:
javacard.framework.Shareable
All Known Subinterfaces:
SecureChannelx, SecureChannelx2

public interface SecureChannel
extends javacard.framework.Shareable

This interface defines basic Secure Channel services used to manage entity authentication and protect APDU commands and responses. It is typically exposed by a Security Domain to its associated Applications.

Using an instance of this interface requires no knowledge of the underlying protocols, algorithms and secrets used to perform entity authentication and provide integrity and confidentiality of APDU commands and responses, which only need to be known by the provider of the instance.

An Application that wishes to delegate such activities to its associated Security Domain shall retrieve a SecureChannel instance provided by its associated Security Domain using the GPSystem.getSecureChannel() method. On some implementations, this SecureChannel instance may also be retrieved using the GPSystem.getService(javacard.framework.AID, short) method.

If the card supports logical channels, this interface is responsible for correctly handling any indication of a logical channel number present in the class byte of APDU commands. In particular, it shall be able to verify and remove (i.e. unwrap) the protection (if any) of an APDU command without altering such indication of a logical channel number. Upon successful initialization of a Secure Channel Session, the implementation shall establish both a compulsory Session Security Level and a Current Security Level:

See Card Specification v2.2.1 section 10.2.3 for details about abortion and termination of a Secure Channel Session.

Until it is aborted, a Secure Channel Session shall be bound to the following information:

Since:

Field Summary
static byte ANY_AUTHENTICATED
          Entity Any Authentication has occurred (0x40).
static byte AUTHENTICATED
          Entity Authentication has occurred as Application Provider (0x80).
static byte C_DECRYPTION
          The unwrap(byte[], short, short) method will decrypt incoming command data (0x02).
static byte C_MAC
          The unwrap(byte[], short, short) 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(byte[], short, short) method will encrypt the outgoing response data (0x20).
static byte R_MAC
          The wrap(byte[], short, short) method will generate a MAC for the outgoing response data (0x10).
 
Method Summary
 short decryptData(byte[] baBuffer, short sOffset, short sLength)
          Decrypts sensitive user data.
 short encryptData(byte[] baBuffer, short sOffset, short sLength)
          Encrypts sensitive user data.
 byte getSecurityLevel()
          Gets the Current Security Level.
 short processSecurity(javacard.framework.APDU apdu)
          Processes security related APDU commands, that is, APDU commands relating to the underlying security protocol.
 void resetSecurity()
          Terminates the current Secure Channel Session.
 short unwrap(byte[] baBuffer, short sOffset, short sLength)
          Verifies and removes the security protection of an incoming APDU command according to the Current Security Level.
 short wrap(byte[] baBuffer, short sOffset, short sLength)
          Computes and adds security protection to an outgoing APDU response according to the Current Security Level.
 

Field Detail

AUTHENTICATED

static final byte AUTHENTICATED
Entity Authentication has occurred as Application Provider (0x80).

Note:

See Also:
Constant Field Values

C_DECRYPTION

static final byte C_DECRYPTION
The unwrap(byte[], short, short) method will decrypt incoming command data (0x02).

Note:

See Also:
Constant Field Values

C_MAC

static final byte C_MAC
The unwrap(byte[], short, short) method will verify the MAC on an incoming command (0x01).

Note:

See Also:
Constant Field Values

R_ENCRYPTION

static final byte R_ENCRYPTION
The wrap(byte[], short, short) method will encrypt the outgoing response data (0x20).

Note:

See Also:
Constant Field Values

R_MAC

static final byte R_MAC
The wrap(byte[], short, short) method will generate a MAC for the outgoing response data (0x10).

Note:

See Also:
Constant Field Values

NO_SECURITY_LEVEL

static final byte NO_SECURITY_LEVEL
Entity Authentication has not occurred (0x00).

Note:

See Also:
Constant Field Values

ANY_AUTHENTICATED

static final byte ANY_AUTHENTICATED
Entity Any Authentication has occurred (0x40).

Note:

See Also:
Constant Field Values
Method Detail

processSecurity

short processSecurity(javacard.framework.APDU apdu)
                      throws javacard.framework.ISOException
Processes security related APDU commands, that is, APDU commands relating to the underlying security protocol.

As the intention is to allow an Application to use Secure Channel services without having any knowledge of the underlying security protocols, the Application may assume that APDU commands that it does not recognize are part of the security protocol and will be recognized by this SecureChannel instance. Therefore, the Application may either invoke this method prior to determining if it recognizes the command or only invoke this method for commands it does not recognize. In turn, this method will throw an ISOException if it does not recognize the APDU command as a security related APDU command.

This method is responsible for receiving the data field of APDU commands that are recognized (i.e. that belong to the security protocol). When processing a command, this method shall write response data in the APDU buffer at offset ISO7816.OFFSET_CDATA or return a status word under the form of an ISOException. The Application is responsible for outputting such response data and/or status word.

Parameters:
apdu - the incoming APDU object.
Returns:
the number of bytes to be output (i.e. length of response data).
Throws:
javacard.framework.ISOException - with a reason code reflecting some error detected by the underlying security protocol, or with one of the following reason codes if the APDU command is not recognized and does not relate to the underlying security protocol:
  • '6E00' if the class byte of the command is not recognized by this method.
  • '6D00' if the instruction byte of the command is not recognized by this method.

wrap

short wrap(byte[] baBuffer,
           short sOffset,
           short sLength)
           throws javacard.framework.ISOException
Computes and adds security protection to an outgoing APDU response according to the Current Security Level.

If the Current Security Level is NO_SECURITY_LEVEL and is different from the compulsory Session Security Level (i.e. a previous Secure Channel Session was aborted but not fully terminated), then this method shall throw an exception (see below).

Otherwise, this method shall attempt computing and adding a security protection to the outgoing message according to the Current Security Level (e.g. R_MAC and/or R_ENCRYPTION). If the Current Security Level does not require any protection for APDU responses (which includes the case where there is no Secure Channel Session currently open), the outgoing response message shall remain as is in the within the baBuffer byte array and the returned length shall be set to a value of (sLength - 2), indicating the status bytes are no longer present at the end of the returned data.

Notes:

Parameters:
baBuffer - byte array containing response data (including the expected status bytes).
sOffset - offset of response data.
sLength - length of response data (including the expected status bytes).
Returns:
length of the reformatted (wrapped) response data, with security information added and status bytes removed.
Throws:
java.lang.SecurityException - if baBuffer is not accessible in the caller's context e.g. baBuffer is not a global array nor an array belonging to the caller context.
java.lang.NullPointerException - if baBuffer is null.
java.lang.ArrayIndexOutOfBoundsException - if writing security information in baBuffer would cause access of data outside array bounds.
javacard.framework.ISOException

unwrap

short unwrap(byte[] baBuffer,
             short sOffset,
             short sLength)
             throws javacard.framework.ISOException
Verifies and removes the security protection of an incoming APDU command according to the Current Security Level.

If the Current Security Level is NO_SECURITY_LEVEL and is different from the compulsory Session Security Level (i.e. a previous Secure Channel Session was aborted but not fully terminated), then this method shall throw an exception (see below).

If the class byte does not indicate secure messaging (according to ISO/IEC 7816-4), then this method shall not attempt to verify and remove any security protection: the incoming command shall remain as is within the baBuffer byte array and the returned length shall be set to the value of the sLength parameter.

If the class byte indicates secure messaging (according to ISO/IEC 7816-4), then this method shall attempt verifying and removing the security protection according to the Current Security Level:

Notes:

Parameters:
baBuffer - byte array containing the incoming APDU command.
sOffset - offset of the incoming APDU command, i.e. offset of the class byte.
sLength - length of the incoming APDU command, i.e length of the entire APDU command (header + data field).
Returns:
length of the reformatted (unwrapped) APDU command, i.e length of the entire APDU command (header + data field).
Throws:
javacard.framework.ISOException - with one of the following reason codes (other reason codes specific to the underlying security protocol may be returned):
  • '6985' if the Current Security Level is NO_SECURITY_LEVEL but the compulsory Session Security Level is different from NO_SECURITY_LEVEL, that is, a previous Secure Channel Session was aborted but not fully terminated.
  • '6982' if this method failed verifying or removing the security protection of the incoming APDU command.
java.lang.SecurityException - if baBuffer is not accessible in the caller's context e.g. baBuffer is not a global array nor an array belonging to the caller context.
java.lang.NullPointerException - if baBuffer is null.
java.lang.ArrayIndexOutOfBoundsException - if reading the incoming APDU command would cause access of data outside array bounds.

decryptData

short decryptData(byte[] baBuffer,
                  short sOffset,
                  short sLength)
                  throws javacard.framework.ISOException
Decrypts sensitive user data.

The decryption algorithm and cryptographic key used to decrypt data, as well as any padding method, are known implicitly and depend on the underlying security protocol.

If the Current Security Level is NO_SECURITY_LEVEL or the necessary cryptographic keys are not available, then this method shall throw an exception (see below).

Otherwise, the data shall be decrypted and the clear text data shall replace the encrypted data within the baBuffer byte array. The removal of padding may cause the length of the clear text data to be shorter than the length of the encrypted data. Any failure in the decryption or padding removal process shall result in an exception being thrown (see below).

Notes:

Parameters:
baBuffer - byte array containing the data that shall be decrypted.
sOffset - offset of the data that shall be decrypted.
sLength - length of the data that shall be decrypted.
Returns:
length of the decrypted data, with any padding removed if a padding method is defined for the underlying security protocol.
Throws:
javacard.framework.ISOException - with one of the following reason codes (other reason codes specific to the underlying security protocol may be returned):
  • '6985' if there is no Secure Channel Session currently open.
  • '6700' if the length of the data that shall be decrypted is not valid (e.g. underlying algorithm requires data to be block-aligned and input data are not).
java.lang.SecurityException - if baBuffer is not accessible in the caller's context e.g. baBuffer is not a global array nor an array belonging to the caller context.
java.lang.NullPointerException - if baBuffer is null.
java.lang.ArrayIndexOutOfBoundsException - if reading user data or writing decrypted data would cause access of data outside array bounds.

encryptData

short encryptData(byte[] baBuffer,
                  short sOffset,
                  short sLength)
                  throws javacard.framework.ISOException
Encrypts sensitive user data.

If this method is not supported by the implementation or the underlying protocol does not define any sensitive data encryption mechanism, it shall do nothing and simply throw an exception (see below).

The encryption algorithm and cryptographic key used to encrypt data, as well as any padding method, are known implicitly and depend on the underlying security protocol.

If the Current Security Level is NO_SECURITY_LEVEL or the necessary cryptographic keys are not available, then this method shall throw an exception (see below).

Otherwise, the data shall be padded (NOTE: depends on the underlying protocol) and encrypted and the encrypted data shall replace the clear text data within the baBuffer byte array. The addition of padding may cause the length of the encrypted data to be longer than the length of the clear text data. Any failure in the padding or encryption process shall result in an exception being thrown (see below).

Notes:

Parameters:
baBuffer - byte array containing the data that shall be encrypted.
sOffset - offset of the data that shall be encrypted.
sLength - length of the data that shall be encrypted.
Returns:
length of the encrypted data.
Throws:
javacard.framework.ISOException - with one of the following reason codes (other reason codes specific to the underlying security protocol may be returned):
  • '6982' if this method is not supported by the implementation.
  • '6985' if there is no Secure Channel Session currently open.
  • '6700' if the length of the data that shall be encrypted is not valid (e.g. underlying algorithm requires data to be block-aligned and input data are not).
java.lang.SecurityException - if baBuffer is not accessible in the caller's context e.g. baBuffer is not a global array nor an array belonging to the caller context.
java.lang.NullPointerException - if baBuffer is null.
java.lang.ArrayIndexOutOfBoundsException - if reading user data or writing encrypted data would cause access of data outside array bounds.

resetSecurity

void resetSecurity()
Terminates the current Secure Channel Session. This method resets both the compulsory Session Security Level and the Current Security Level to NO_SECURITY_LEVEL and resets all information relating to the current Secure Channel Session (e.g. internal states, session keys).

This method shall not fail and shall simply return if no Secure Channel Session has been initiated.

Notes:

  • It is recommended that Applications using this interface invoke this method in the implementation of their Applet.deselect() method.


getSecurityLevel

byte getSecurityLevel()
Gets the Current Security Level. An Application shall invoke this method to ensure that its own specific security requirements are enforced by this interface. It shall also take into account that the Current Security Level may change during the Secure Channel Session (e.g. R_MAC may be enabled or disabled during a C_MAC session).

Notes:

  • The Current Security Level, as returned by this method, may be different for an Application invoking the method and its associated Security Domain depending on the underlying security protocol and the authenticated off-card entity's Application Provider ID (e.g. it may be ANY_AUTHENTICATED for the application and AUTHENTICATED for its associated Security Domain, and vice versa).

Returns:
The Current Security Level, which is a combination of one or more the following constants:


Copyright © 2003-2014 GlobalPlatform, Inc. All rights reserved. The technology provided or described in this specification is subject to updates, revisions, and extensions by GlobalPlatform. Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights or other intellectual property rights of which they may be aware which might be necessarily infringed by the implementation of the specification or other work product set forth in this document, and to provide supporting documentation.
THIS SPECIFICATION OR OTHER WORK PRODUCT IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NON-INFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY IMPLEMENTATION OF THIS SPECIFICATION OR OTHER WORK PRODUCT SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE COMPANY, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER DIRECTLY OR INDIRECTLY ARISING FROM THE IMPLEMENTATION OF THIS SPECIFICATION OR OTHER WORK PRODUCT.