org.globalplatform
Class GPSystem

java.lang.Object
  extended by org.globalplatform.GPSystem

public class GPSystem
extends java.lang.Object

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:

Field Summary
static byte APPLICATION_INSTALLED
          The current applet context is in the Life Cycle State of INSTALLED (0x03).
static byte APPLICATION_LOCKED
          The current applet context is in the Life Cycle State of LOCKED (0x80).
static byte APPLICATION_SELECTABLE
          The current applet context is in the Life Cycle State of SELECTABLE (0x07).
static byte CARD_INITIALIZED
          The card is in the Life Cycle State of INITIALIZED (0x07).
static byte CARD_LOCKED
          The card is in the Life Cycle State of CARD_LOCKED (0x7F).
static byte CARD_OP_READY
          The card is in the Life Cycle State of OP_READY (0x01).
static byte CARD_SECURED
          The card is in the Life Cycle State of SECURED (0x0F).
static byte CARD_TERMINATED
          The card is in the Life Cycle State of TERMINATED (0xFF).
static byte CVM_ETSI_PIN_APP_1
          Indicates that the required CVM interface is the ETSI PIN App 1 (0x01).
static byte CVM_ETSI_PIN_APP_2
          Indicates that the required CVM interface is the ETSI PIN App 2 (0x02).
static byte CVM_ETSI_PIN_APP_3
          Indicates that the required CVM interface is the ETSI PIN App 3 (0x03).
static byte CVM_ETSI_PIN_APP_4
          Indicates that the required CVM interface is the ETSI PIN App 4 (0x04).
static byte CVM_ETSI_PIN_APP_5
          Indicates that the required CVM interface is the ETSI PIN App 5 (0x05).
static byte CVM_ETSI_PIN_APP_6
          Indicates that the required CVM interface is the ETSI PIN App 6 (0x06).
static byte CVM_ETSI_PIN_APP_7
          Indicates that the required CVM interface is the ETSI PIN App 7 (0x07).
static byte CVM_ETSI_PIN_APP_8
          Indicates that the required CVM interface is the ETSI PIN App 8 (0x08).
static byte CVM_GLOBAL_PIN
          Indicates that the required CVM interface is a Global PIN (0x11).
static byte FAMILY_AUHTORITY
          Deprecated. Use FAMILY_AUTHORITY instead.
static byte FAMILY_AUTHORITY
          Indicates the family of the Authority Service Identifier (0x83).
static byte FAMILY_CVM
          Indicates the family of the CVM Global Service Identifier (0x82).
static byte FAMILY_HTTP_ADMINISTRATION
          Indicates the family of the HTTP Administration Service Identifier (0x84).
static byte FAMILY_HTTP_REPORT
          Indicates the family of the HTTP Report Service Identifier (0x85).
static byte FAMILY_SECURE_CHANNEL
          Indicates the family of the Secure Channel Global Service Identifier (0x81).
static byte FAMILY_USSM
          Indicates the family of the USSM Global Service Identifier (0xA0).
static byte GLOBAL_SERVICE_IDENTIFIER
          Indicates the generic Global Service Identifier (0x80).
static byte SECURITY_DOMAIN_PERSONALIZED
          The Security Domain is in the Life Cycle State of PERSONALIZED (0x0F).
 
Constructor Summary
GPSystem()
           
 
Method Summary
static byte getCardContentState()
          Gets the Life Cycle State of the current applet context.
static byte getCardState()
          Gets the Life Cycle State of the card.
static CVM getCVM(byte bCVMIdentifier)
          Gets a reference to a CVM instance provided by the OPEN.
static GPRegistryEntry getRegistryEntry(javacard.framework.AID aid)
          Gets a GPRegistryEntry instance.
static SecureChannel getSecureChannel()
          Gets a SecureChannel instance.
static GlobalService getService(javacard.framework.AID serverAID, short sServiceName)
          Gets a GlobalService instance matching the specified service name (sServiceName).
static boolean lockCard()
          Locks the card.
static boolean setATRHistBytes(byte[] baBuffer, short sOffset, byte bLength)
          Sets the historical bytes of the Answer To Reset (ATR) string.
static boolean setCardContentState(byte bState)
          Sets the Life Cycle state of the Application invoking this method.
static boolean terminateCard()
          Terminates the card.
 
Methods inherited from class java.lang.Object
equals
 

Field Detail

APPLICATION_INSTALLED

public static final byte APPLICATION_INSTALLED
The current applet context is in the Life Cycle State of INSTALLED (0x03).

Note:

See Also:
Constant Field Values

APPLICATION_SELECTABLE

public static final byte APPLICATION_SELECTABLE
The current applet context is in the Life Cycle State of SELECTABLE (0x07).

Note:

See Also:
Constant Field Values

APPLICATION_LOCKED

public static final byte APPLICATION_LOCKED
The current applet context is in the Life Cycle State of LOCKED (0x80). To know whether an application is locked or not, a logical AND operation shall be performed between this constant and the current application life cycle state.

See Also:
Constant Field Values

SECURITY_DOMAIN_PERSONALIZED

public static final byte SECURITY_DOMAIN_PERSONALIZED
The Security Domain is in the Life Cycle State of PERSONALIZED (0x0F).

See Also:
Constant Field Values

CARD_OP_READY

public static final byte CARD_OP_READY
The card is in the Life Cycle State of OP_READY (0x01).

See Also:
Constant Field Values

CARD_INITIALIZED

public static final byte CARD_INITIALIZED
The card is in the Life Cycle State of INITIALIZED (0x07).

See Also:
Constant Field Values

CARD_SECURED

public static final byte CARD_SECURED
The card is in the Life Cycle State of SECURED (0x0F).

See Also:
Constant Field Values

CARD_LOCKED

public static final byte CARD_LOCKED
The card is in the Life Cycle State of CARD_LOCKED (0x7F).

See Also:
Constant Field Values

CARD_TERMINATED

public static final byte CARD_TERMINATED
The card is in the Life Cycle State of TERMINATED (0xFF).

See Also:
Constant Field Values

CVM_GLOBAL_PIN

public static final byte CVM_GLOBAL_PIN
Indicates that the required CVM interface is a Global PIN (0x11).

See Also:
Constant Field Values

CVM_ETSI_PIN_APP_1

public static final byte CVM_ETSI_PIN_APP_1
Indicates that the required CVM interface is the ETSI PIN App 1 (0x01).

Since:
export file version 1.5
See Also:
Constant Field Values

CVM_ETSI_PIN_APP_2

public static final byte CVM_ETSI_PIN_APP_2
Indicates that the required CVM interface is the ETSI PIN App 2 (0x02).

Since:
export file version 1.5
See Also:
Constant Field Values

CVM_ETSI_PIN_APP_3

public static final byte CVM_ETSI_PIN_APP_3
Indicates that the required CVM interface is the ETSI PIN App 3 (0x03).

Since:
export file version 1.5
See Also:
Constant Field Values

CVM_ETSI_PIN_APP_4

public static final byte CVM_ETSI_PIN_APP_4
Indicates that the required CVM interface is the ETSI PIN App 4 (0x04).

Since:
export file version 1.5
See Also:
Constant Field Values

CVM_ETSI_PIN_APP_5

public static final byte CVM_ETSI_PIN_APP_5
Indicates that the required CVM interface is the ETSI PIN App 5 (0x05).

Since:
export file version 1.5
See Also:
Constant Field Values

CVM_ETSI_PIN_APP_6

public static final byte CVM_ETSI_PIN_APP_6
Indicates that the required CVM interface is the ETSI PIN App 6 (0x06).

Since:
export file version 1.5
See Also:
Constant Field Values

CVM_ETSI_PIN_APP_7

public static final byte CVM_ETSI_PIN_APP_7
Indicates that the required CVM interface is the ETSI PIN App 7 (0x07).

Since:
export file version 1.5
See Also:
Constant Field Values

CVM_ETSI_PIN_APP_8

public static final byte CVM_ETSI_PIN_APP_8
Indicates that the required CVM interface is the ETSI PIN App 8 (0x08).

Since:
export file version 1.5
See Also:
Constant Field Values

FAMILY_SECURE_CHANNEL

public static final byte FAMILY_SECURE_CHANNEL
Indicates the family of the Secure Channel Global Service Identifier (0x81).

Since:
export file version 1.1
See Also:
Constant Field Values

FAMILY_CVM

public static final byte FAMILY_CVM
Indicates the family of the CVM Global Service Identifier (0x82).

Since:
export file version 1.1
See Also:
Constant Field Values

FAMILY_AUHTORITY

public static final byte FAMILY_AUHTORITY
Deprecated. Use FAMILY_AUTHORITY instead.
Since:
export file version 1.2
See Also:
Constant Field Values

FAMILY_AUTHORITY

public static final byte FAMILY_AUTHORITY
Indicates the family of the Authority Service Identifier (0x83).

Since:
export file version 1.2
See Also:
Constant Field Values

FAMILY_HTTP_ADMINISTRATION

public static final byte FAMILY_HTTP_ADMINISTRATION
Indicates the family of the HTTP Administration Service Identifier (0x84).

Since:
export file version 1.3
See Also:
Constant Field Values

FAMILY_HTTP_REPORT

public static final byte FAMILY_HTTP_REPORT
Indicates the family of the HTTP Report Service Identifier (0x85).

Since:
export file version 1.3
See Also:
Constant Field Values

FAMILY_USSM

public static final byte FAMILY_USSM
Indicates the family of the USSM Global Service Identifier (0xA0).

Since:
export file version 1.1
See Also:
Constant Field Values

GLOBAL_SERVICE_IDENTIFIER

public static final byte GLOBAL_SERVICE_IDENTIFIER
Indicates the generic Global Service Identifier (0x80).

Since:
export file version 1.1
See Also:
Constant Field Values
Constructor Detail

GPSystem

public GPSystem()
Method Detail

getCardContentState

public static byte getCardContentState()
Gets the Life Cycle State of the current applet context.

Returns:
the Life Cycle State of the current applet context.
See Also:
APPLICATION_INSTALLED, APPLICATION_SELECTABLE, APPLICATION_LOCKED

getCardState

public static byte getCardState()
Gets the Life Cycle State of the card.

Returns:
the Life Cycle State of the card.
See Also:
CARD_OP_READY, CARD_INITIALIZED, CARD_SECURED, CARD_LOCKED, CARD_TERMINATED

getCVM

public static CVM getCVM(byte bCVMIdentifier)
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.

Parameters:
bCVMIdentifier - identifies the requested CVM instance.
Returns:
requested CVM instance, or null if the requested CVM instance is not available.
See Also:
CVM_GLOBAL_PIN

getSecureChannel

public static 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.

Returns:
the SecureChannel interface object reference.
See Also:
the GPSystem.getCVM() method for an example of how to access a Global Service.

lockCard

public static boolean lockCard()
Locks the card. This method shall be used to transition the card to CARD_LOCKED Life Cycle State.

The OPEN shall check that the Application invoking this method has the Card Lock Privilege. If not, the transition shall be rejected.

Returns:
true if the card was locked, false otherwise.

terminateCard

public static boolean terminateCard()
Terminates the card. This method shall be used to transition the card to CARD_TERMINATED Life Cycle State.

The OPEN shall check that the Application invoking this method has the Card Terminate Privilege. If not, the transition shall be rejected.

Returns:
true if the card was terminated, false otherwise.

setATRHistBytes

public static boolean setATRHistBytes(byte[] baBuffer,
                                      short sOffset,
                                      byte bLength)
Sets the historical bytes of the Answer To Reset (ATR) string.

This method only updates the ATR string that is used for the contact-based IO interface (as specified by [ISO/IEC 7816] upon power-up or cold reset. The ATR string used for warm reset shall remain unchanged. The new historical bytes shall be visible upon next power-up or cold reset.

The OPEN shall check that the Application invoking this method has the Card Reset Privilege and that the bLength is both positive and lower than 16. If not, the change shall be rejected.

Notes:

Parameters:
baBuffer - byte array containing the ATR historical bytes.
sOffset - offset of the ATR historical bytes.
bLength - length of the ATR historical bytes.
Returns:
true if ATR historical bytes were set, false otherwise.

setCardContentState

public static boolean setCardContentState(byte bState)
Sets the Life Cycle state of the Application invoking this method. This method allows the Application associated with the current applet context to lock itself or to change its state from an application specific Life Cycle State to another application specific Life Cycle State. An Application cannot unlock itself.

The OPEN shall check that the Application is currently in an application specific Life Cycle State (i.e. in the range [0x07 .. 0x7F] and with its 3 low order bits set to 1), in particular that it is not in the APPLICATION_INSTALLED state and not currently locked. If not, the change shall be rejected. The OPEN shall check that bState either encodes an application specific Life Cycle State or has its high order bit (b8) set to 1: the latter case shall be interpreted as a request from the the Application to lock itself.

Parameters:
bState - either an application specific Life Cycle State (i.e. in the range [0x07 .. 0x7F] and with its 3 low order bits set to 1), or any value having its high order bit (b8) set to 1. A value of APPLICATION_LOCKED may be used to request locking the Application.
Returns:
true if the Life Cycle State of the Application was changed, false otherwise.
Since:
  • export file version 1.0: initial version.
  • export file version 1.5: this method now allows the application associated with the current applet context to lock itself.
See Also:
APPLICATION_INSTALLED, APPLICATION_LOCKED

getRegistryEntry

public static GPRegistryEntry getRegistryEntry(javacard.framework.AID aid)
Gets a GPRegistryEntry instance.

This method allows the Application associated with the current applet context to get its own GPRegistryEntry instance or the one of another Application. If the aid parameter is not null and does not identify the Application invoking this method, the OPEN shall check that the Application invoking this method has the Global Registry Privilege. If not, this method shall return null.

Parameters:
aid - the AID of the Application whose GPRegistryEntry instance is requested. Use null to retrieve the GPRegistryEntry instance of the current applet context.
Returns:
the requested GPRegistryEntry instance if it was found in the GlobalPlatform Registry and the Application invoking this method is allowed to access that entry, null otherwise.
Since:
export file version 1.1

getService

public static GlobalService getService(javacard.framework.AID serverAID,
                                       short sServiceName)
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(javacard.framework.AID, byte) 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.

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

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:

Returns:
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.
Since:
export file version 1.1
See Also:
GLOBAL_SERVICE_IDENTIFIER, FAMILY_CVM, FAMILY_SECURE_CHANNEL, FAMILY_USSM, FAMILY_AUTHORITY, FAMILY_HTTP_ADMINISTRATION, FAMILY_HTTP_REPORT, GPRegistryEntry.registerService(short)


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