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

Class Authority, void init(byte)

Initializes the Authority interface with the appropriate mode (MODE_SIGN or MODE_KEY_RECOVERY). @param theMode one of .MODE_SIGN or .MODE_KEY_RECOVERY. @exception CryptoException with the following reason code:
Class Authority, void update(byte[], short, short)

Accumulates input data. for the current operation (MODE_SIGN or MODE_KEY_RECOVERY).

When this method is used, temporary storage of intermediate results is required. This method should only be used if all the input data required for the current operation is not available in one byte array. The sign or recoverKey methods are recommended whenever possible. The inBuff shall be global array. @param inBuff buffer containing input data @param inOffset offset of input data @param inLength length of input data @throws CryptoException with the following reason codes:

@throws SecurityException if the inBuff is not global array.

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 ApplicationApplication registered within 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_CVM @see GPSystem#FAMILY_SECURE_CHANNEL @see GPSystem#FAMILY_USSM @see GPSystem#FAMILY_AUTHORITY @see GPSystem#FAMILY_HTTP_ADMINISTRATION @see GPSystem#FAMILY_HTTP_REPORT
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 the specified service name:

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.

@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_CVM @see GPSystem#FAMILY_SECURE_CHANNEL @see GPSystem#FAMILY_USSM @see GPSystem#FAMILY_AUTHORITY @see GPSystem#FAMILY_HTTP_ADMINISTRATION @see GPSystem#FAMILY_HTTP_REPORT

Class GPSystem

This class exposes a subset of the behavior of the OPEN to the outside world. The OPEN implements and enforces a Card Issuer's security policy relating to these services. It provides functionality at the same level as the JCRE, i.e. the "system" context with special privileges. @since
Class GPSystem, CVM getCVM(byte)

Gets a reference to a CVM instance provided by the OPEN.

Since export file version 1.1, this method allows looking up for CVM instances registered as Global Services by so-called Global Services Applications (i.e. Applications having the Global Service Privilege) and the following mechanism is defined to retrieve such instances:

For backward compatibility, the .CVM_GLOBAL_PIN constant can still be used to access a Global Service registered with the (.FAMILY_CVM<<8|.CVM_GLOBAL_PIN) identifier, or uniquely registered for the entire .FAMILY_CVM family. Whether such a service is available or not still depends on the issuer's policy. @param bCVMIdentifier identifies the requested CVM instance. @return requested CVM instance, or null if the requested CVM instance is not available. @see #FAMILY_CVM @see #CVM_GLOBAL_PINPIN @see #getService
Class GPSystem, SecureChannel getSecureChannel()

Gets a SecureChannel instance.

This method allows the Application associated with the current applet context to retrieve a SecureChannel instance provided by its associated Security Domain.

Since export file version 1.1, although not required, this method may be implemented using the Global Service facility, in which case SecureChannel instances would be registered by Security Domains as Global Services. In this case, Security Domains shall check that they only provide such SecureChannel instances to their associated Applications.

@return the SecureChannel interface object reference. @see #FAMILY_SECURE_CHANNEL @see #getService @see #getCVM the GPSystem.getCVM() method for an example of how to access a Global Service.

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 #GLOBAL_SERVICE_IDENTIFIER @see #FAMILY_CVM @see #FAMILY_SECURE_CHANNEL @see #FAMILY_USSM @see #FAMILY_AUTHORITY @see #FAMILY_HTTP_ADMINISTRATION @see #FAMILY_HTTP_REPORT @see GPRegistryEntry#registerService @since export file version 1.1
Class GPSystem, byte FAMILY_CVM

Indicates the family of the CVM Global Service Identifier (0x82). @since export file version 1.1
Class GPSystem, byte FAMILY_SECURE_CHANNEL

Indicates the family of the Secure Channel Global Service Identifier (0x81). @since export file version 1.1
Class GPSystem, byte GLOBAL_SERVICE_IDENTIFIER

Indicates the generic Global Service Identifier (0x80). @since export file version 1.11 @see #getService

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 acces 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_CVM @see GPSystem#FAMILY_SECURE_CHANNEL @see GPSystem#FAMILY_USSM @see GPSystem#FAMILY_AUTHORITY @see GPSystem#FAMILY_HTTP_ADMINISTRATION @see GPSystem#FAMILY_HTTP_REPORT

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


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, 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 to verify andany secure messaging removeprocessing on any securitythe incoming protection: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 the baBuffer bytebyte array and the returned length shall be set to to the value of thethe 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 SecureChannelx2

This interface is an extension of the SecureChannel interface that defines one supplementary method overridingoverloading the SecureChannel.processSecurity method.

An Application that wishes to use the SecureChannelx2 interface shall obtain a reference to a SecureChannel instance and try to cast it to the SecureChannelx2 interface. Whether the objects returned by the GPSystem.getSecureChannel method also implement the SecureChannelx2 interface is implementation dependent, however, this may be expressed as a requirement in specific GlobalPlatform configuration documents. @since