Generated by
JDiff

org.globalplatform Documentation Differences

This file contains all the changes in documentation in the package org.globalplatform as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Class Application

This interface defines a method through which an Application may forward input data to another Application.

This interface shall be implemented by an Application that wishes to receive personalization data forwarded by its associated Security Domain. In such a , without any scenario,intend to return response data.

ifIf the Application implements both the Application and the Personalization interface, then the Security Domain shall use the Personalization interface.

@see Personalization @since export file version 1.0


Class Authority

This interface allows performing operations such as recovering a cryptographic key or signing data. The required algorithms and credentials are known implicitly.

It is intended that Security Domains would be able to access an Authority instance through a Global Service by a Controlling Authority Security Domain (CASD) with a service name of (GPSystem.FAMILY_AUTHORITY<<8|0x00). @since

@deprecated Since export file version 1.8. There is no use of this interface for non-SD Applications.
Class Authority, short recoverKey(byte[], short, short, byte[], short)

Recovers a cryptographic key from a set of data structures provided in the input buffer (inBuff). As a mandatory step, the recovery mechanism includes the verification of the origin and integrity of the recovered key. This method knows, from the set of data structures present in the input buffer, which recovery mechanism is to be used. The recovered key is written in the ouputoutput buffer (outBuff) at specified offset (outOffset), in the form of a key data structure whose format depends on the type of the key. A call to this method resets this instance of the Authority interface to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to recover another key. The input and output buffers may overlap and shall be global arrays. @param inBuff containing input data. @param inOffset offset of input data. @param inLength length of input data. @param outBuff the buffer where recovered key data structure shall be written @param outOffset offset where recovered key data structure shall be written @return Length of the recovered key data structure written in outBuff at outOffset,or 0 if the recovery mechanism failed (e.g. recovered key was considered invalid). @throws CryptoException - with the following reason codes: @throws SecurityException if the inBuff or outBuff are not global arrays.

Class AuthoritySignature

This interface allows generating a signature over the input data provided by an Application.

To do so, the Application shall first select a signature mode using the .init method, then use the .update and .sign methods to provide input data and obtain output data. The to-be-signed data will typically include the input data provided by the Application and the output data will typically include a digital signature, however what data are signed and what output data are generated will depend on the selected mode (see {@code MODE_XXX} constants for details).

The signature algorithm and key cannot be chosen by the caller Application and will depend on how the implementation of this interface was created and personalized. However, for all modes, output data will include information about:

It is intended for Applications to access an AuthoritySignature instance through a Global Service registered by the Controlling Authority Security Domain (CASD) with a service name of (GPSystem.FAMILY_AUTHORITY_SIGNATURE<<8|0x00). @since

Class AuthoritySignature, byte MODE_INTEGRITY

Used with .init method to indicate integrity protection mode.

In this mode, this interface will sign the input data provided by the caller Application to protect its integrity, without performing any additional check.

For this mode, to-be-signed data and output data are described in [GPCS-A] section 5.3.

This mode does not require any additional parameters. @see #init


Class CVM

This interface defines basic Cardholder Verification Method services (e.g. comparison of CVM value, CVM state query). It is typically exposed to on-card Applications by a Global Services Application implementing one or more Cardholder Verification Methods. Some services are restricted to Applications having the CVM Management Privilege.

To retrieve an instance of this interface, an Application shall invoke the GPSystem.getCVM method, or shall use a GlobalService instance of the GPSystem.FAMILY_CVM family. For backward compatibility, the CVM instances retrieved using the GPSystem.getCVM method are mapped onto those retrieved as Global Services of the GPSystem.FAMILY_CVM family.

The CVM instance maintains the following data (see Card Specification v2.2.1 section 8.2.2 for more details):

Operations performed by this interface shall be independent of, and not interfere with, any transaction in progress (e.g. if the .verify method is invoked from within a transaction and this transaction is aborted, then the try counter is not revert to its original value). @since
Class CVM, boolean blockState()

Sets the CVM state to BLOCKED.

If the Application invoking this method does not have the CVM Management Privilege, then the CVM state is not updated.

The CVM state can only be set to BLOCKED if the CVM instance already entered the state ACTIVE once, that is, if the CVM instance is fully initialized. Notice that this method shall return true if the CVM state is already BLOCKED.

If a transaction is in progress, updates of the CVM state shall participate in the transaction, and shall be reverted if the transaction is aborted.

Notes:

@return true if the CVM state was set to BLOCKED, false otherwise. @see GPRegistryEntry#PRIVILEGE_CVM_MANAGEMENT
Class CVM, boolean resetAndUnblockState()

Resets the CVM state to ACTIVE, even if it is currently BLOCKED.

If the Application invoking this method does not have the CVM Management Privilege, then the CVM state is not updated.

The CVM state can only be set to ACTIVE if the CVM instance already entered the state ACTIVE once, that is, if the CVM instance is fully initialized. If the CVM state is successfully reset, then this method also resets the CVM try counter to the CVM try limit.

Even if a transaction is in progress, updates of the CVM try counter and CVM state shall not participate in the transaction, and shall not be reverted if the transaction is aborted.

Notes:

@return true if the CVM state was reset to ACTIVE, false otherwise. @see GPRegistryEntry#PRIVILEGE_CVM_MANAGEMENT
Class CVM, boolean resetState()

Resets the CVM state to ACTIVE.

The CVM state can only be reset to ACTIVE from the states ACTIVE, INVALID_SUBMISSION or VALIDATED. In particular, it cannot be reset to ACTIVE if it is in state BLOCKED or if the CVM instance never entered the state ACTIVE, that is, if the CVM instance is not fully initialized.

If a transaction is in progress, updates of the CVM state shall participate in the transaction, and shall be reverted if the transaction is aborted.

@return true if the CVM state was reset, false otherwise.

Class CVM, boolean setTryLimit(byte)

Sets the CVM try limit, that is, the maximum value of the CVM try counter.

If the Application invoking this method does not have the CVM Management Privilege, then the CVM try limit is not set.

If the CVM try limit is successfully set, then this method also resets the CVM try counter to the new CVM try limit. If the CVM value has already been successfully set previously, then this method also (re)sets the CVM state to ACTIVE.

If a transaction is in progress, updates of the CVM try limit, CVM try counter and CVM state shall participate in the transaction, and shall be reverted if the transaction is aborted.

Notes:

@param bTryLimit the maximum number of tries for the CVM. @return true if the try limit was set, false otherwise. @see GPRegistryEntry#PRIVILEGE_CVM_MANAGEMENT
Class CVM, boolean update(byte[], short, byte, byte)

Updates the CVM value.

If the Application invoking this method does not have the CVM Management Privilege, or if the specified format (bFormat) is unknown (or not supported by this CVM instance), or if the new CVM value is not consistent with respect to the specified format, then the CVM value is not updated.

If the CVM value is successfully updated and the CVM try limit has already been successfully set previously, then this method also resets the CVM try counter to the CVM try limit, and (re)sets the CVM state to ACTIVE.

If a transaction is in progress, updates of the CVM value, CVM try counter and CVM state shall participate in the transaction, and shall be reverted if the transaction is aborted.

Notes:

@param baBuffer byte array containing the new CVM value. Must be a global byte array. @param sOffset offset of the new CVM value within baBuffer. @param bLength length of the new CVM value. @param bFormat format of the new CVM value: .FORMAT_ASCII, .FORMAT_BCD or .FORMAT_HEX. @return true if the CVM value was successfully updated, false otherwise. @see GPRegistryEntry#PRIVILEGE_CVM_MANAGEMENT @exception SecurityException if baBuffer is not a global byte array. @exception NullPointerException if baBuffer is null. @exception ArrayIndexOutOfBoundsException if reading the new CVM value would cause access of data outside array bounds.
Class CVM, short verify(byte[], short, byte, byte)

Compares a value with the stored CVM value.

If the CVM state is BLOCKED, or if the submitted format (bFormat) is unknown (or not supported by this CVM instance), or if this method throws a NullPointerException or an ArrayIndexOutOfBoundsException, then the comparison is deemed unsuccessful.

If the submitted CVM value is not in the same format as the stored CVM value, then format conversion shall occur according to the following rules prior to comparing values:

If the comparison is unsuccessful and the CVM state is not BLOCKED, then the CVM try counter must be decremented (by 1). In this case, if the CVM try counter reaches a value of '0' then the CVM state shall be set to BLOCKED, otherwise the CVM state shall be set to INVALID_SUBMISSION.

If the comparison is successful, then the CVM try counter shall be reset to the CVM try limit and the CVM state shall be set to VALIDATED.

TheEven if a transaction is in progress, updates of the CVM try counter and theand CVM state shall not conform to a transaction participate in progress,the i.e.transaction, theyand shall not revert to abe previousreverted value if a the transaction in progress is aborted.

@param baBuffer byte array containing the submitted CVM value. Must be a global byte array. @param sOffset offset of the submitted CVM value within baBuffer. @param bLength length of the submitted CVM value. @param bFormat format of the submitted CVM value: .FORMAT_ASCII, .FORMAT_BCD or .FORMAT_HEX. @return .CVM_SUCCESS if the comparison was successful, .CVM_FAILURE otherwise. @exception SecurityException if baBuffer is not a global byte array. @exception NullPointerException if baBuffer is null. @exception ArrayIndexOutOfBoundsException if reading the submitted CVM value would cause access of data outside array bounds.


Class GPRegistryEntry

This interface allows querying and potentially modifying the registry data of an Application registered within the GlobalPlatform Registry.

Every GPRegistryEntry instance corresponds to an Application registered within the GlobalPlatform Registry.

To retrieve an instance of this interface, an Application shall invoke the GPSystem.getRegistryEntry method. @since

Class GPRegistryEntry, void deregisterService(short)

Deregisters a service name.

The OPEN shall check that the Application invoking this method corresponds to this entry, that it has the Global Service Privilege, and that the specified service name was previously uniquely registered by that same Application. If not, this method shall throw an exception (see below).

@param sServiceName the service name that shall be deregistered.

A service name is encoded on 2 bytes, the 1st byte identifying a family of services and the 2nd byte identifying a service within that family.

The GPSystem class defines a set of constants FAMILY_XXX (of the byte type) that may be used to build a service name (of the short type) suitable to invoke this method as shown in the following examples:

@exception ISOException if this method is not supported or if the service name was not found or if the conditions allowing to deregister the service name are not satisfied. @see #registerService @see GPSystem#FAMILY_SECURE_CHANNEL @see GPSystem#FAMILY_CVM @see GPSystem#FAMILY_SECUREHTTP_CHANNEL ADMINISTRATION @see GPSystem#FAMILY_USSM PRIVACY_PROTOCOL @see GPSystem#FAMILY_AUTHORITY AUTHORITY_SIGNATURE @see GPSystem#FAMILY_HTTPBROKER @see GPSystem#FAMILY_GLOBAL_MASTER_FILE @see GPSystem#FAMILY_COAP_ADMINISTRATION @see GPSystem#FAMILY_HTTPCRYPTO_SERVICE_REPORTPROVIDER
Class GPRegistryEntry, boolean isAssociated(AID)

Checks whether the Application corresponding to this entry is associated with the specified Security Domain.

The OPEN shall check that the specified sdAID indeed identifies a Security Domain present on the card, and check that the Application corresponding to this entry is associated with this Security Domain. If not, this method shall return false.

@param sdAID AID of a Security Domain. This AID instance shall be accessible in the caller's context (i.e. either a JCRE-owned AID object or created by the caller of this method). @return true if the Application corresponding to this entry is associated with the specified Security Domain, false otherwise. @exception SecurityException if sdAID is not accessible in the caller's context.

Class GPRegistryEntry, void registerService(short)

Registers a service name identifying a service provided by the Application corresponding to this entry.

The specified service name (sServiceName) shall be unique among all the service names previously registered in the GlobalPlatform Registry using this method. Following successful invocation of this method, this service name is known to be uniquely registered: no other Application on the card will be able to register the same service name (until this service name is deregistered (see .deregisterService)). If the service name identifies a family of service, no other Application on the card will be able to register a service of that family.

The OPEN shall first check that the Application invoking this method corresponds to this entry and that it has the Global Service Privilege.

Then the OPEN shall check that:

If any of the above conditions is not satisfied, this method shall throw an exception (see below). Otherwise, the specified service name shall be uniquely registered in the GlobalPlatform Registry.

Note:

Even if a service name (exact name or family name) is recorded for an Application, another Application may still uniquely register a service with that service name. @param sServiceName the service name that shall be uniquely registered.

A service name is encoded on 2 bytes, the 1st byte identifying a family of services and the 2nd byte identifying a service within that family. If the 2nd byte is set to 0x00, the caller of this method is registering an entire family of service.

The GPSystem class defines a set of constants FAMILY_XXX (of the byte type) that may be used to build a service name (of the short type) suitable to invoke this method as shown in the following examples:

@exception ISOException if this method is not supported or if the conditions allowing to register the service name are not satisfied. @see #deregisterService @see GPSystem#getService @see GPSystem#FAMILY_SECURE_CHANNEL @see GPSystem#FAMILY_CVM @see GPSystem#FAMILY_SECUREHTTP_CHANNEL ADMINISTRATION @see GPSystem#FAMILY_PRIVACY_PROTOCOL @see GPSystem#FAMILY_USSM AUTHORITY_SIGNATURE @see GPSystem#FAMILY_AUTHORITY BROKER @see GPSystem#FAMILY_HTTPGLOBAL_MASTER_FILE @see GPSystem#FAMILY_COAP_ADMINISTRATION @see GPSystem#FAMILY_HTTPCRYPTO_SERVICE_REPORTPROVIDER
Class GPRegistryEntry, boolean setState(byte)

Sets the Life Cycle state of the Application corresponding to this entry.

This method enforces the Life Cycle State transition rules described in Card Specification v2.2.1 section 5.

If this entry corresponds to the Issuer Security Domain (ISD), then the OPEN shall check that the requested transition complies with Card Life Cycle State transition rules. If needed, the OPEN shall check that the Application invoking this method has the Card Lock Privilege or the Card Terminate Privilege.

Otherwise, the following rules shall apply:

@param bState the new Life Cycle State. See Card Specification v2.2.1 section 11.1.1 for details on Life Cycle State Coding. A value of GPSystem.APPLICATION_LOCKED (resp. 0x00) may be used to request locking (resp. unlocking) an Application or a Security Domain (other than the ISD). @return true if the transition was successful, false otherwise.

Class GPSystem, short getCardInfo(byte[], short, short)

Gets card specific information.

Writes the requested data in the specified buffer. If the requested data is a BER-TLV encoded data object (i.e. to be retrieved from the ISD's Data Store), then only the value part shall be written. @since export file version 1.7 @see #getCardInfoLength @param buffer byte array where requested information shall be written @param offset offset where requested information shall be written @param info value identifying the requested information. The following rules apply:

@return (offset + length of data written in buffer) @exception ArrayIndexOutOfBoundsException if writing data to buffer would cause access outside array bounds or the offset is negative. @exception NullPointerException if buffer is null @exception ISOException with reason code:
Class GPSystem, GlobalService getService(AID, short)

Gets a GlobalService instance matching the specified service name (sServiceName).

The serverAID parameter is optional (i.e. may be set to null) and identifies the Global Services Application providing the service.

The OPEN shall look for the Global Services Application providing the service:

If a Global Services Application was found, then the OPEN shall retrieve the GlobalService instance by invoking the Applet.getShareableInterfaceObject method of that Global Services Application with the clientAID parameter set to the AID of the current applet context (i.e. the one invoking this method) and the parameter parameter set to .GLOBAL_SERVICE_IDENTIFIER. @param serverAID AID of the Global Services Application providing the requested service, or null if the caller of this method is requesting a uniquely registered service name.

@param sServiceName service name identifying a service or a family of services.

A service name is encoded on 2 bytes, the 1st byte identifying a family of services and the 2nd byte identifying a service within that family. If the 2nd byte is set to 0x00, the caller of this method is requesting a service of the specified family, but does not care exactly which service within that family.

This class defines a set of constants FAMILY_XXX (of the byte type) that may be used to build a service name (of the short type) suitable to invoke this method as shown in the following examples:

@return the GlobalService instance giving access to the requested service, or null if the Global Services Application could not be found or did not provide a GlobalService instance. @see #GLOBALFAMILY_SERVICESECURE_IDENTIFIER CHANNEL @see #FAMILY_CVM @see #FAMILY_SECUREHTTP_CHANNEL ADMINISTRATION @see #FAMILY_USSM PRIVACY_PROTOCOL @see #FAMILY_AUTHORITY AUTHORITY_SIGNATURE @see #FAMILY_HTTPBROKER @see #FAMILY_GLOBAL_MASTER_FILE @see #FAMILY_COAP_ADMINISTRATION @see #FAMILY_HTTPCRYPTO_SERVICE_REPORT PROVIDER @see GPRegistryEntry#registerService @since export file version 1.1
Class GPSystem, short CARD_INFO_ATR_HISTORICAL_BYTES

The requested information is the Historical Bytes of the Answer-To-Reset last returned ontheon the contact IO interface (as specified by [ISO7816]) (cold or warm reset). If the platform does not provide a contact IO interface (as specified by [ISO7816], or if the contact interface is not initialized, an error shall be returned. @see #getCardInfo @since export file version 1.7
Class GPSystem, byte FAMILY_AUTHORITY

Indicates the family of the Authority Service Identifier (0x83). @since export file version 1.22 @deprecated Since export file version 1.8. Use of Authority interface is deprecated.
Class GPSystem, byte FAMILY_HTTP_REPORT

Indicates the family of the HTTP Report Service Identifier (0x85). @since export file version 1.33 @deprecated Since export file version 1.8. Use AdminSessionListener.SERVICE_ADMIN_SESSION_REPORT instead.
Class GPSystem, byte FAMILY_USSM

Indicates the family of the USSM Global Service Identifier (0xA0). @since export file version 1.1 @deprecated Since export file version 1.8.

Class GlobalService, Shareable getServiceInterface(GPRegistryEntry, short, byte[], short, short)

Gets a Shareable Interface Object (SIO) actually providing the requested service.

The Application invoking this method shall set the clientRegistryEntry to its own GPRegistryEntry instance.

The Global Services Application shall verify the validity of the request according to its own security policies for the specified sServiceName, based on the identity and characteristics of the Application invoking this method as registered by the specified clientRegistryEntry, and possibly based on the data contained in the baBuffer byte array.

If the request is valid, the Global Service Application returns a SIO implementing the actual service: this SIO may either be this GlobalService instance or another object. If the request is deemed to be invalid, the Global Services Application shall reject the request by either throwing an exception or returning null.

It is assumed that the Application invoking this method is aware of the interface (extension of the Shareable interface) to which the retrieved SIO shall be casted in order to accesaccess the service.

Notes:

@param clientRegistryEntry the GPRegistryEntry instance of the requesting Application.

@param sServiceName a service name identifying the requested service.

A service name is encoded on 2 bytes, the 1st byte identifying a family of services and the 2nd byte identifying a service within that family.

The GPSystem class defines a set of constants FAMILY_XXX (of the byte type) that may be used to build a service name (of the short type) suitable to invoke this method as shown in the following examples:

@param baBuffer byte array containing additional parameters of the request, potentially authentication data. Must be global byte array. @param sOffset offset of the additional parameters. @param sLength length of the additional parameters. @return the SIO providing the actual service, or null if the service is not available or the request was rejected. Alternatively, this method may reject the request by throwing an ISOException. @exception ISOException if the request was rejected. Although not mandatory, it is recommended to use one of the following reason codes: Alternatively, this method may reject the request by returning null. @exception SecurityException if the Global Services Application requires reading data from baBuffer and baBuffer is not a global byte array. @exception NullPointerException if the Global Services Application requires reading data from baBuffer and baBuffer is null. @exception ArrayIndexOutOfBoundsException if the Global Services Application requires reading data from baBuffer and reading data would cause access of data outside array bounds. @see GPSystem#getService @see GPSystem#FAMILY_SECURE_CHANNEL @see GPSystem#FAMILY_CVM @see GPSystem#FAMILY_SECUREHTTP_CHANNEL ADMINISTRATION @see GPSystem#FAMILY_USSM PRIVACY_PROTOCOL @see GPSystem#FAMILY_AUTHORITY AUTHORITY_SIGNATURE @see GPSystem#FAMILY_HTTPBROKER @see GPSystem#FAMILY_COAP_ADMINISTRATION @see GPSystem#FAMILY_HTTP_REPORTUSSM

Class HTTPAdministration

This interface defines a method to trigger a new HTTP administration session.

To retrieve an instance of this interface, an Application shall use the GlobalService instance, if available, registered with a service name of (GPSystem.FAMILY_HTTP_ADMINISTRATION<<8|0x00). @see GlobalService @see GPSystem#getService @since

@deprecated Since export file version 1.8. Use AdministrationSession instead.
Class HTTPAdministration, void requestHTTPAdministrationSession(byte[], short, short)

Triggers a new administration session.

The Security Domain of the Application invoking this method will handle the SCP81 (PSK TLS) security of the communication.

The Application invoking this method will be notified of the result of the request if it implements the HTTPReportListener interface.

@param triggeringParameters byte array containing administration session triggering parameters. @param offset offset of triggering parameters within triggeringParameters. @param length length of triggering parameters. @exception SecurityException if triggeringParameters is not accessible in the caller's context. @exception NullPointerException if triggeringParameters is null. @exception ArrayIndexOutOfBoundsException if reading triggering parameters command would cause access of data outside array bounds. @exception ISOException with one of the following reason codes:

@deprecated Since export file version 1.8. Use AdministrationSession.requestAdministrationSession(byte[], short, short) instead.

Class HTTPReportListener

This interface defines a method to receive a notification upon completion (success or failure) of an HTTP Administration Session.

An Application that wishes to receive such a notification shall implement the javacard.framework.Applet.getShareableInterfaceObject to return an HTTPReportListener instance when the clientAID parameter is set to null, and the parameter parameter is set to GPSystem.FAMILY_HTTP_REPORT. @since

@deprecated Since export file version 1.8. Use AdminSessionListener instead.
Class HTTPReportListener, void httpAdministationSessionReport(short)

Notifies the Application that the requested HTTP Administration Session successfully completed or not.

The OPEN notifies the Application when the HTTP Administration Session ends or when the retry policy is exhausted.

@param status Either .HTTP_SESSION_NO_ERROR (failuresuccess) or .HTTP_SESSION_ERROR (successfailure). @deprecated Since export file version 1.8. Use AdminSessionListener.administrationSessionReport(short) instead.

Class HTTPReportListener, short HTTP_SESSION_ERROR

Constant notifying that a HTTP Administration Session failed. That is, the retry policy of the session is exhausted and the administration session request is aborted. @deprecated Since export file version 1.8. Use AdminSessionListener.ADMIN_SESSION_ERROR instead.
Class HTTPReportListener, short HTTP_SESSION_NO_ERROR

Constant notifying that a HTTP Administration Session ended successfullysuccessfully @deprecated Since export file version 1.8. Use AdminSessionListener.ADMIN_SESSION_NO_ERROR instead.

Class Personalization

This interface defines a method through which an Application may forward input data to another Application and retrieve output data from that Application.

This interface shall be implemented by an Application that wishes to receive personalization data forwarded by its associated Security Domain and request outputting response data. In such a scenario,

ifIf the Application implements both the Application and the Personalization interface, then the Security Domain shall use the Personalization interface.

@see Application @since export file version 1.2

Class Personalization, short processData(byte[], short, short, byte[], short)

Processes application specific data received from another on-card entity.

If the Application invoking this method is a Security Domain then it shall be assumed that:

Notes:

@param inBuffer byte array containing input data. Must be a global byte array. @param inOffset offset of input data within inBuffer. @param inLength length of input data. @param outBuffer byte array where output data shall be written. Must be a global byte array. @param outOffset offset where output data shall be written within inBuffer. @return the number of bytes written to outBuffer. @exception SecurityException if inBuffer or outBuffer is not a global byte array. @exception NullPointerException if inBuffer or outBuffer is null. @exception ArrayIndexOutOfBoundsException if reading intputinput data or writing output data would cause access of data outside array bounds.

Class SecureChannel

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 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.23.1 (or higher), 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
Class SecureChannel, short decryptData(byte[], short, short)

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:

@param baBuffer byte array containing the data that shall be decrypted. @param sOffset offset of the data that shall be decrypted. @param sLength length of the data that shall be decrypted. @return length of the decrypted data, with any padding removed if a padding method is defined for the underlying security protocol. @exception ISOException with one of the following reason codes (other reason codes specific to the underlying security protocol may be returned): @exception 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. @exception NullPointerException if baBuffer is null. @exception ArrayIndexOutOfBoundsException if reading user data or writing decrypted data would cause access of data outside array bounds.
Class SecureChannel, short encryptData(byte[], short, short)

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:

@param baBuffer byte array containing the data that shall be encrypted. @param sOffset offset of the data that shall be encrypted. @param sLength length of the data that shall be encrypted. @return length of the encrypted data. @exception ISOException with one of the following reason codes (other reason codes specific to the underlying security protocol may be returned): @exception 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. @exception NullPointerException if baBuffer is null. @exception ArrayIndexOutOfBoundsException if reading user data or writing encrypted data would cause access of data outside array bounds.
Class SecureChannel, 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:

@return The Current Security Level, which is a combination of one or more the following constants:
Class SecureChannel, short processSecurity(APDU)

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 and/or return a status word under the form of an ISOException. The Application is responsible for outputting such response data and/or status word. The state of the APDU object upon return of this method is STATE_FULL_INCOMING

This method may support the retrieval of Security Domain data objects of the Security Domain that offers this SecureChannel service. For this purpose GET_DATA (without secure messaging) and GET_RESPONSE commands may be recognized and handled by the Security Domain. If pending response data of GET_DATA or GET_RESPONSE is longer than 256 bytes, 256 bytes of pending response data are witten to the APDU buffer and an ISOException is thrown. The state machine allowing to retrieve remaining response bytes using one or more GET_RESPONSE commands is reset if a new recognized GET_DATA or any recognized protocol command is processed on the same logical channel. The state machine is not reset by a call to this method performed on another logical channel (on that same SD). The implementation may either reject the call or, if enough resources are available, manage it independently. @param apdu the incoming APDU object. @return the number of bytes to be output (i.e. length of response data). @exception ISOException with a reason code reflecting some error detected detected by the underlying security protocol, or

Class SecureChannel, 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:

Class SecureChannel, short unwrap(byte[], short, short)

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 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:

Notes: @param baBuffer byte array containing the incoming APDU command. @param sOffset offset of the incoming APDU command, i.e. offset of the class byte. @param sLength length of the incoming APDU command, i.e. length of the entire APDU command (header + data field). @return length of the reformatted (unwrapped) APDU command, i.e. length of the entire APDU command (header + data field). @exception ISOException with one of the following reason codes (other reason codes specific to the underlying security protocol may be returned): @exception 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. @exception NullPointerException if baBuffer is null. @exception ArrayIndexOutOfBoundsException if reading the incoming APDU command would cause access of data outside array bounds.
Class SecureChannel, short wrap(byte[], short, short)

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:

@param baBuffer byte array containing response data (including the expected status bytes). @param sOffset offset of response data. @param sLength length of response data (including the expected status bytes). @return length of the reformatted (wrapped) response data, with security information added and status bytes removed. @exception ISOException with one of the following reason codes (other reason codes specific to the underlying security protocol may be returned): @exception 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. @exception NullPointerException if baBuffer is null. @exception ArrayIndexOutOfBoundsException if writing security information in baBuffer would cause access of data outside array bounds.

Class SecureChannelx, void setSecurityLevel(byte)

Updates the Current Security Level. 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 Current Security Level cannot be set below the compulsory Session Security Level, but only equal or above. It may be increased or decreased during a Secure Channel Session as long as it is at least equal to the compulsory Session Security Level.

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

The new Current Security Level shall apply for all subsequent invocations of SecureChannel.wrap and SecureChannel.unwrap methods, except when there is no current Secure Channel Session.

@param bSecurityLevel The new Current Security Level, which shall be a combination of one or more the following constants:

@exception ISOException with one of the following reason codes (other reason codes specific to the underlying security protocol: may

Class SecureChannelx2, short processSecurity(byte[], short, short, short)

Processes security related APDU commands, that is, APDU commands relating to the underlying security protocol.

This method shall be used in the same way as the SecureChannel.processSecurity method, except that the incoming APDU command shall be read from, and any response data shall be written to the baBuffer byte array.

Notes:

@param baBuffer byte array containing the incoming APDU command. @param sInOffset offset of the incoming APDU command, i.e. offset of the class byte. @param sInLength length of the incoming APDU command, i.e length of the entire APDU command (header + data field). @param sOutOffset offset within baBuffer where response data (if any) shall be written. @return the number of bytes to be output (i.e. length of response data). @exception 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: @exception 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. @exception NullPointerException if baBuffer is null. @exception ArrayIndexOutOfBoundsException if reading the incoming APDU command would cause access of data outside array bounds.