public interface SecureChannel
extends javacard.framework.Shareable
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:
SecureChannelx.setSecurityLevel(byte)
method (if supported), but shall
never get below the minimum requirement defined by the compulsory Session
Security Level. The Current Security Level, as well as any information
relating to the Secure Channel Session (except the compulsory Session
Security Level), shall be reset upon abortion or termination of the Secure
Channel Session.
Until it is aborted, a Secure Channel Session shall be bound to the following information:
Modifier and Type | Field and Description |
---|---|
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). |
Modifier and Type | Method and Description |
---|---|
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.
|
static final byte AUTHENTICATED
Note:
wrap(byte[], short, short)
and unwrap(byte[], short, short)
methods are not necessarily related. A Security Domain, by default, could
verify the MAC on any command passed as a parameter in the unwrap(byte[], short, short)
method without
entity authentication previously having occurred. static final byte C_DECRYPTION
unwrap(byte[], short, short)
method will decrypt incoming command data (0x02).
Note:
static final byte C_MAC
unwrap(byte[], short, short)
method will verify the MAC on an incoming command (0x01).
Note:
unwrap(byte[], short, short)
method will decrypt the command data of incoming commands
and verify the MAC on incoming commands. static final byte R_ENCRYPTION
wrap(byte[], short, short)
method will encrypt the outgoing response data (0x20).
Note:
static final byte R_MAC
wrap(byte[], short, short)
method will generate a MAC for the outgoing response data (0x10).
Note:
unwrap(byte[], short, short)
method will verify the MAC on incoming commands and that the
wrap(byte[], short, short)
method will generate a MAC on outgoing response data. static final byte NO_SECURITY_LEVEL
Note:
wrap(byte[], short, short)
and unwrap(byte[], short, short)
methods are not necessarily related. A
Security Domain, by default, could verify the MAC on any command passed as a parameter in
the unwrap(byte[], short, short)
method without entity authentication previously having occurred.
wrap(byte[], short, short)
and unwrap(byte[], short, short)
methods will not apply any cryptographic
processing to command or response data. static final byte ANY_AUTHENTICATED
Note:
wrap(byte[], short, short)
and unwrap(byte[], short, short)
methods are not necessarily related. A Security Domain, by default, could
verify the MAC on any command passed as a parameter in the unwrap(byte[], short, short)
method without
entity authentication previously having occurred. short processSecurity(javacard.framework.APDU apdu) throws javacard.framework.ISOException
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.
apdu
- the incoming APDU
object.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:short wrap(byte[] baBuffer, short sOffset, short sLength) throws javacard.framework.ISOException
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:
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).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
short unwrap(byte[] baBuffer, short sOffset, short sLength) throws javacard.framework.ISOException
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 any secure messaging processing
on the incoming command. In this case, if the Current Security Level
requires secure messaging a security error shall be returned; otherwise 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:
NO_SECURITY_LEVEL
, AUTHENTICATED
or ANY_AUTHENTICATED
, then this method shall not
attempt to verify and remove any security protection, the incoming command
will remain as is within the baBuffer
byte array (with class
byte indicating secure messaging) and the returned length shall be set to
the value of the sLength
parameter.
baBuffer
byte array (a.k.a. unwrapped command). A reformatted
case 1 or case 2 command shall include an Lc byte set to '00'.
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).javacard.framework.ISOException
- with one of the following reason codes (other
reason codes specific to the underlying security protocol may be
returned):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.
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.short decryptData(byte[] baBuffer, short sOffset, short sLength) throws javacard.framework.ISOException
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:
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.javacard.framework.ISOException
- with one of the following reason codes (other
reason codes specific to the underlying security protocol may be
returned):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.short encryptData(byte[] baBuffer, short sOffset, short sLength) throws javacard.framework.ISOException
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:
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.javacard.framework.ISOException
- with one of the following reason codes (other
reason codes specific to the underlying security protocol may be
returned):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.void resetSecurity()
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:
Applet.deselect()
method. byte getSecurityLevel()
Notes:
Copyright © 2003-2018 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.