|
Generated by JDiff |
|||||||
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES |
This file contains all the changes in documentation in the packageorg.globalplatform
as colored differences. Deletions are shownlike 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.
This interface allows performing operations such as recovering a cryptographic key or signing data. The required algorithms and credentials are known implicitly.Class Authority, void init(byte)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
- export file version 1.2: initial version.
- export file version 1.6: reviewed overall description of this interface.
Initializes the Authority interface with the appropriate mode (Class Authority, void update(byte[], short, short)MODE_SIGN
orMODE_KEY_RECOVERY
). @param theMode one of .MODE_SIGN or .MODE_KEY_RECOVERY. @exception CryptoException with the following reason code:
if theMode option is an undefined value.
ILLEGUALILLEGAL_VALUE
Accumulates input data.for the current operation (MODE_SIGN
orMODE_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
orrecoverKey
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.
INVALID_INIT
if this Authority interface is not initialized.
This interface allows querying and potentially modifying the registry data of an Application registered within the GlobalPlatform Registry.Class GPRegistryEntry, void deregisterService(short)Every GPRegistryEntry instance corresponds to an
ApplicationApplication registeredwithinwithin the GlobalPlatform Registry.To retrieve an instance of this interface, an Application shall invoke the GPSystem.getRegistryEntry method.
@since
- export file version 1.1: initial version.
- export file version 1.6: reviewed overall description of this interface.
Deregisters a service name.Class GPRegistryEntry, void registerService(short)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 thebyte
type) that may be used to build a service name (of theshort
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
(short)((GPSystem.FAMILY_CVM<<8)|0x11)
(short)((GPSystem.FAMILY_HTTP_ADMINISTRATION<<8)|0x00)
Registers a service name identifying a service provided by the Application corresponding tothis
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.
- is not already uniquely registered in the GlobalPlatform Registry; if the service name identifies an entire family of services, then the OPEN shall check that no service name of that family is registered.
- was previously recorded for the Application corresponding to
this
entry (i.e. specified as part of System Install Parameters in the INSTALL command).@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 thebyte
type) that may be used to build a service name (of theshort
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
(short)((GPSystem.FAMILY_CVM<<8)|0x11)
(short)((GPSystem.FAMILY_HTTP_ADMINISTRATION<<8)|0x00)
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. @sinceClass GPSystem, CVM getCVM(byte)
- export file version 1.0: initial version.
- export file version 1.1: new services and/or constants added.
- export file version 1.3: new services and/or constants added.
- export file version 1.5: new services and/or constants added.
- export file version 1.6: reviewed overall description of this interface.
- export file version 1.7: new .getCardInfo and .getCardInfoLength methods and related constants.
Gets a reference to a CVM instance provided by the OPEN.Class GPSystem, SecureChannel getSecureChannel()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
- The OPEN looks up in the GlobalPlatform Registry for a Global Services Application (i.e. having the Global Service Privilege) that registered a Global Service with the specified
bCVMIdentifier
identifier for the .FAMILY_CVM family, or that uniquely registered a Global Service for the entire .FAMILY_CVM family.- The OPEN then retrieves the corresponding 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 theparameter
parameter set to .GLOBAL_SERVICE_IDENTIFIER.- The OPEN then retrieves a Shareable instance by invoking the GlobalService.getServiceInterface method with the
clientRegistryEntry
parameter set to the GPRegistryEntry instance of the current applet context (i.e. the one invoking this method), with thesServiceName
set to(.FAMILY_CVM<<8|bCVMIdentifier)
, thebaBuffer
parameter set tonull
, and thesOffset
andsLength
set to zero.- Finally, the OPEN casts the retrieved Shareable instance to the CVM interface before returning it.
- If any of the above steps fails, the requested CVM instance is deemed to be unavailable.
(.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, ornull
if the requested CVM instance is not available. @see #FAMILY_CVM @see #CVM_GLOBAL_PINPIN @see #getService
Gets a SecureChannel instance.Class GPSystem, GlobalService getService(AID, short)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.
Gets a GlobalService instance matching the specified service name (Class GPSystem, byte FAMILY_CVMsServiceName
).The
serverAID
parameter is optional (i.e. may be set tonull
) 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
- If the
serverAID
parameter isnull
, then the OPEN shall look for the specified service name among the set of uniquely registered service names (see GPRegistryEntry.registerService). If the requested service name only identifies a family of services, then the OPEN shall look for a uniquely registered service name of the requested family (the search strategy remains implementation dependent). If a matching service name is found, the Global Services Application is the one that uniquely registered that service name.- Otherwise, if the
serverAID
parameter is notnull
, then the OPEN shall look in the GlobalPlatform Registry for the corresponding Application:
- If the Application does not have the Global Service Privilege, then the search is deemed to be unsuccessful.
- If the requested service name (or family of service) was not previously recorded for that Application (i.e. not specified as part of System Install Parameters in the INSTALL command), then the search is deemed to be unsuccessful.
clientAID
parameter set to the AID of the current applet context (i.e. the one invoking this method) and theparameter
parameter set to .GLOBAL_SERVICE_IDENTIFIER. @param serverAID AID of the Global Services Application providing the requested service, ornull
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 thebyte
type) that may be used to build a service name (of theshort
type) suitable to invoke this method as shown in the following examples:@return the GlobalService instance giving access to the requested service, or
(short)((.FAMILY_CVM<<8)|0x11)
(short)((.FAMILY_HTTP_ADMINISTRATION<<8)|0x00)
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
Indicates the family of the CVMClass GPSystem, byte FAMILY_SECURE_CHANNELGlobalService Identifier (0x82). @since export file version 1.1
Indicates the family of the Secure ChannelClass GPSystem, byte GLOBAL_SERVICE_IDENTIFIERGlobalService Identifier (0x81). @since export file version 1.1
Indicates the generic Global Service Identifier (0x80). @since export file version 1.11 @see #getService
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 specifiedclientRegistryEntry
, and possibly based on the data contained in thebaBuffer
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.
- It shall be noticed that an Application having the Global Registry Privilege could potentially invoke this method with the
clientRegistryEntry
parameter set to the GPRegistryEntry instance of another Application. If the Global Services Application itself has the Global Registry Privilege, it may explicitly retrieve and check the GPRegistryEntry instance of the Application invoking this method, by performing the following call:GPSystem.getRegistryEntry(JCSystem.getPreviousContextAID())
.@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 thebyte
type) that may be used to build a service name (of theshort
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
(short)((GPSystem.FAMILY_CVM<<8)|0x11)
(short)((GPSystem.FAMILY_HTTP_ADMINISTRATION<<8)|0x00)
null
if the service is not available or the request was rejected. Alternatively, this method may reject the request by throwing anISOException
. @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
- '6A88' if the specified service was not found or is not available.
- '6982' if some security conditions are not satisfied.
- '6985' if some other conditions are not satisfied.
null
. @exception SecurityException if the Global Services Application requires reading data frombaBuffer
andbaBuffer
is not a global byte array. @exception NullPointerException if the Global Services Application requires reading data frombaBuffer
andbaBuffer
isnull
. @exception ArrayIndexOutOfBoundsException if the Global Services Application requires reading data frombaBuffer
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
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
- export file version 1.3: initial version.
- export file version 1.6: reviewed overall description of this interface.
Encrypts sensitive user data.Class SecureChannel, short unwrap(byte[], short, short)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):
- The Application is responsible for adding application specific padding, if needed. For example, if the underlying security protocol is SCP '02', then no padding method is defined and this method by itself will not add any padding, which may lead to an exception being thrown (see below) if input data are not block-aligned.
@exception SecurityException if
- '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).
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 ifbaBuffer
isnull
. @exception ArrayIndexOutOfBoundsException if reading user data or writing encrypted data would cause access of data outside array bounds.
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 messagingremoveprocessing onany securitythe incomingprotection: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 withinthethebaBuffer
bytebyte array and the returned length shall be settoto the value ofthethesLength
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:
- If the Current Security Level is .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 thesLength
parameter.- Incorrect verification and removal of the security protection shall result in an exception being thrown (see below) and the current Secure Channel Session being aborted: all information relating to the Secure Channel Session, except the compulsory Session Security Level, shall be reset.
- Correct verification and removal of the security protection shall result in the incoming command being reformatted within the
baBuffer
byte array (a.k.a. unwrapped command). A reformatted case 1 or case 2 command shall include an Lc byte set to '00'.@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):
- The Application is implicitly responsible for receiving the data field of the incomping APDU command prior to invoking this method.
- Depending on the underlying security protocol, if R_MAC is indicated by the Current Security Level, R-MAC computation may be initiated on the reformatted command once secure messaging processing of the incoming command has successfully completed. If no secure messaging processing was required for the incoming command, R-MAC computation would be initiated on the unmodified incoming command, appended with a Lc byte of '00' in the event of a case 1 or case 2 command.
@exception SecurityException if
- '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.
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 ifbaBuffer
isnull
. @exception ArrayIndexOutOfBoundsException if reading the incoming APDU command would cause access of data outside array bounds.
This interface is an extension of the SecureChannel interface that defines one supplementary methodoverridingoverloading 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
- export file version 1.4: initial version.
- export file version 1.6: reviewed overall description of this interface.