| Runtime Environment Specification, Java Card Platform, v3.0.1, Connected Edition |    
|
| C H A P T E R 8 |
|
Card Management |
The requirements of a card manager on the Connected Edition are described in this chapter.
This chapter describes the following aspects of card management:
The card manager application is an on-card application that manages the secure loading, configuring and deleting of applications and libraries on the Java Card platform. The card manager application MAY be a web application or an extended applet application. A Java Card platform may support multiple card manager applications.
On a Java Card platform that supports post-issuance download, an off-card client MUST be able to establish a communication session with the card manager application. The actual communication dialog used by the off-card client to communicate with the card manager application is implementation specific. On a Java Card platform that supports post-issuance download, the card manager application MUST be able to perform the following operations upon request from the off-card client:
In addition, the card manager application relies on the card management facility of the Java Card Platform to perform the card management operations, the loading and unloading of applications and the instantiating and deleting of application instances. The card manager application interacts with the card management facility in an implementation specific manner. The Application Programming Interface Specification, Java Card Platform, Version 3.0.1, Connected Edition includes an informative section that contains the recommended Card Management System Programming Interface between the card manager application and the card management facility.
The card management facility is the Java Card platform layer responsible for securely adding and removing application code and instances onto the platform. The card management facility MUST check if the caller has card management application permissions (see CardManagementPermission in Section 6.2, Permission-based Security), based on the caller’s protection domain, prior to performing any card management functions. On a Java Card platform that supports post-issuance download, the card manager facility MUST be able to perform the following operations upon request from the card manager application:
An application is distributed and deployed as an application module JAR file.
Libraries are distributed and deployed as standard library JAR files containing the library classes.
Applications and libraries MUST be distributed in the public domain in the formats described in this specification. An application module or library MAY be transformed during deployment on the card only if the deployment format is visible within a private network domain and nowhere else. See “Public Representation of Java Applications and Resources” in the Virtual Machine Specification, Java Card Platform, Version 3.0.1, Connected Edition.
Thus, the card manager MUST support three types of distribution and deployment units. They are:
The card manager, when operating in a public network domain, MUST reject distribution and deployment unit formats other than the three defined above.
The section describes distribution and deployment unit formats, as well as the descriptors, including the web application deployment descriptor, the applet application deployment descriptor, the Java Card Platform-specific application descriptor, and the runtime descriptor.
The assertions which use the MUST directive MUST be enforced by any validating tool, as well the card manager, when processing the application and library distribution formats described in this chapter. Violations MUST result in an error being flagged by the tool or the rejection of the application or library by the card manager.
The application module distribution format is a Java Archive (JAR) format described in the Java Platform, Standard Edition JAR file specification and is used to encapsulate a single application that can be deployed on a Java Card platform. The format used by each of the application types follows a common directory structure template. The common directory structure includes:
The following sections describe the individual variants for the web application model type, the extended application model type and the classic application model type respectively.
FIGURE 8-1 shows the directory structure of the web application module distribution format. The structure MUST be that of the web archive (.war) file with the following differences:
FIGURE 8-1 Web Application Module Distribution Format
The WEB-INF directory at the root of the JAR directory structure contains the classes directory for the web application module and the web application deployment descriptor file (web.xml). Each Java class file (.class) MUST be in a directory with a relative directory path that matches the package name for that class within the classes directory, to be successfully located by the class loader. Additional resource files may also be present along with the class files. The format of this web application deployment descriptor is specified in Section 8.5.4, Web Application Deployment Descriptor.
The META-INF/MANIFEST.MF file contains standard JAR file meta data information. The Java Card Platform defines additional runtime descriptor information in the META-INF/MANIFEST.MF file. The format of this descriptor is specified in Section 8.5.6, The Runtime Descriptor. The META-INF directory also contains the Java Card Platform-specific application descriptor file javacard.xml.
Additional, implementation specific meta data information files, MAY be present only in the META-INF and WEB-INF directories within the JAR file. The card management facility MUST silently ignore the files that it does not recognize.
All other files, outside the META-INF and WEB-INF directory hierarchies, included in the JAR file are not directly processed by the Java Card platform and simply stored as application resource files. These resource files are static web resources serviced by the web container to off-card clients. The various elements of a web application are described in Chapter 9 of Java Servlet Specification, Java Card Platform, Version 3.0.1, Connected Edition.
The recommended file name extension for the web application module distribution format file is war.
FIGURE 8-2 shows the directory structure of the extended applet application module distribution format.
FIGURE 8-2 Extended Applet Application Module Distribution Format
The APPLET-INF directory at the root of the JAR directory structure contains the classes directory for the extended applet application module and the applet application deployment descriptor file (applet.xml). Each Java class file (.class) MUST be in a directory with a relative directory path that matches the package name for that class within the classes directory, to be successfully located by the class loader. Additional resource files may also be present along with the class files. The format of this applet application deployment descriptor is specified in Section 8.5.5, Applet Application Deployment Descriptor.
The META-INF/MANIFEST.MF file contains standard JAR file meta data information. The Java Card Platform defines additional runtime descriptor information in the META-INF/MANIFEST.MF file. The format of this descriptor is specified in Section 8.5.6, The Runtime Descriptor. The META-INF directory also contains the Java Card Platform-specific application descriptor file javacard.xml.
Additional, implementation specific meta data information files, MAY be present only in the META-INF and APPLET-INF directories within the JAR file. The card management facility MUST silently ignore the files that it does not recognize.
The card management facility MUST silently ignore all other files, outside the META-INF and APPLET-INF directory hierarchies, that are included in the JAR file.
The recommended file name extension for the extended applet application module distribution format file is eap.
FIGURE 8-3 shows the directory structure of the classic applet application module distribution format. The structure is similar to that of the extended applet application module (Section 8.4.1.2, Extended Applet Application Module Distribution Format) with the following differences:
FIGURE 8-3 Classic Applet Application Module Distribution Format
The APPLET-INF directory at the root of the JAR directory structure contains the classes directory for the classic application module and the applet application deployment descriptor file (applet.xml). Each Java class file (.class) MUST be in a directory with a relative directory path that matches the package name for that class within the classes directory, to be successfully located by the class loader. The class files MUST belong to a single named package.
The META-INF/MANIFEST.MF file contains standard JAR file meta data information. The Java Card Platform defines additional runtime descriptor information in the META-INF/MANIFEST.MF file. The format of this descriptor is specified in Section 8.5.6, The Runtime Descriptor. The META-INF/ directory also contains the Java Card Platform-specific application descriptor file javacard.xml.
The CAP file components (*.cap) MUST be present in a directory named javacard that is in a subdirectory representing the application package directory as described in Virtual Machine Specification, Java Card Platform, Version 3.0.1, Classic Edition. The format of the CAP file components are described in Virtual Machine Specification, Java Card Platform, Version 3.0.1, Classic Edition. The presence of the CAP file components and their structural and semantic correctness MUST be verified by off-card tools. Validation by the card management facility is not required.
Additional, implementation specific meta data information files, MAY be present only in the META-INF and APPLET-INF directories within the JAR file. The card management facility MUST silently ignore the files that it does not recognize.
The card management facility MUST silently ignore all other files, outside the META-INF and APPLET-INF directory hierarchies, that are included in the JAR file.
The recommended file name extension for the classic applet application module distribution format file is cap.
The extension library distribution format uses the Java Platform Standard Edition library JAR file structure. FIGURE 8-4 shows the format of a Java Platform Standard Edition library JAR file format.
FIGURE 8-4 Java Platform Standard Edition Library JAR Format
Each Java class file (.class) MUST be in a directory with a relative directory path starting at the root of the library structure that matches the package name for that class, to be successfully located by the class loader.
The META-INF/MANIFEST.MF file at the root level of the extension library distribution format contains standard JAR file meta data information defined in the Java Platform Standard Edition JAR specification. Java Card Platform does not define any additional information.
The recommended file name extension for the extension library distribution format file is jar.
FIGURE 8-5 shows the format of a classic library distribution format. The classic library distribution format uses the Java Platform Standard Edition library JAR file format (see FIGURE 8-4) with the following restrictions and additions:
FIGURE 8-5 Classic Library Distribution Format
The META-INF/MANIFEST.MF file at the root level of the classic library distribution format contains standard JAR file meta data information defined in the Java Platform Standard Edition JAR specification. Java Card Platform does not define any additional information. The Sealed attribute SHOULD be set as true (by off-card tools) to ensure backward compatibility with the classic platform.
Files other than the <package name> directory and the META-INF/MANIFEST.MF file MAY be silently discarded by the card management facility.
The recommended file name extension for the classic library distribution format file is cap.
All diagrams in this section that illustrate XML format structures follow the convention displayed in FIGURE 8-6. Note that elements with attributes may also use the occurrence notation using a circle. The sequential ordering requirement of sub-elements within an element are shown using a red arrow. See the individual descriptor schema for more detailed information on the exact syntax.
FIGURE 8-6 Conventions Used in Diagrams of Elements
This section lists some general rules that the card management facility MUST implement and that the developer must account for concerning the processing of all the XML descriptors within the Java Card application distribution unit.
The Java Card Platform-specific application descriptors convey Java Card Platform-specific elements and configuration information of an application between application developers, application assemblers, and deployers. The Java Card Platform-specific application descriptor is an optional file named META-INF/javacard.xml which MAY be present in the application module JAR file. If the file is absent, all elements within the javacard-app root element of the descriptor are assumed to be absent.
The Java Card Platform-specific application descriptor structure, content and semantics are defined in an XML schema document.
The following types of configuration and deployment information MUST be supported in the Java Card Platform-specific application descriptor:
This section illustrates the elements in a Java Card Platform-specific application descriptor. The notation convention used here is described previously in Section 8.5.1, Conventions Used in XML Descriptor Element Diagrams.
The javacard-app element is the root element of the Java Card Platform-specific application descriptor. This element has a required attribute version to specify to which version of the schema the Java Card Platform-specific application descriptor conforms. The attribute value MUST be “3.0”. FIGURE 8-7 shows the structure of the javacard-app element. Each sub-element is described in the next sections.
FIGURE 8-7 javacard-app Element Structure
The description element is used to provide text describing the parent element. This element occurs not only under the javacard-app element, but also under the elements - dynamically-loaded-classes, shareable-interface-classes and security-role. It has an optional attribute xml:lang to indicate which language is used in the description. The default value of this attribute is English (“en”).
The display-name element contains a short name that is intended to be displayed by tools. The display name need not be unique. This element has an optional attribute xml:lang to specify the language.
The card-holder-authorization element is used by a remotely accessible application to configure the card holder authentication requirements to authorize access for a remote client. A role-name listed here MUST be a role-name listed in the security-role element with a USER category attribute. FIGURE 8-8 shows the structure of the card-holder-authorization element. For more detailed information on authorization of remotely accessible applications see Section 6.4.6, Card Holder Authorization For Remotely Accessible Applications.
FIGURE 8-8 card-holder-authorization Element Structure
The dynamically-loaded-classes element is used to declare the classes that the application loads dynamically using the Class.forName API. All classes within the application distribution unit that are dynamically loaded SHOULD be declared in the name attribute of class sub-elements. An attempt to dynamically load a class from within the application module that is not declared, and which has not already been loaded, MUST result in a SecurityException being thrown. The attribute value MUST be the fully qualified classname of the dynamically loaded class. Classes in extension library packages that are dynamically loaded SHOULD also be declared here. FIGURE 8-9 shows the structure of the dynamically-loaded-classes element.
Note that all Classic SIO synchronization proxies (see Section 4.4.2, SIO Synchronization Proxy Classes) and application defined subclasses of the java.util.ResourceBundle class (see which are dynamically loaded by the Java Card RE on behalf of the application SHOULD also be declared in this element.
FIGURE 8-9 dynamically-loaded-classes Element Structure
The shareable-interface-classes element is used to declare the shareable interface classes of the application. All public shareable interface classes within the application distribution unit that are accessible to applications in other group contexts on the card SHOULD be declared in the name attribute of class sub-elements. The attribute value MUST be the fully qualified class name of the shareable interface class. A shareable interface class not listed here, or not declared with the public class modifier, MUST NOT be loaded by the shareable interface class loader. Note that the same interface may already have been loaded by the shareable interface class loader while loading another application - a name conflict MUST NOT be flagged. FIGURE 8-10 shows the structure of the shareable-interface-classes element.
FIGURE 8-10 shareable-interface-classes Element Structure
The security-role element defines a security role. The sub-element role-name designates the name of the security role. The role-name element has a required attribute category to specify the type of role, either “USER” OR “ON-CARD-CLIENT”. FIGURE 8-11 shows the structure of the security-role element.
FIGURE 8-11 security-role Element Structure
The web application deployment descriptor conveys web application model elements and configuration information of an application between application developers, application assemblers, and deployers. The web application deployment descriptor is a mandatory file named WEB-INF/web.xml which MUST be present for each web application module encapsulated within the distribution format JAR file.
The format and description of the web application deployment descriptor is detailed in the deployment descriptor chapter of Java Servlet Specification, Java Card Platform, Version 3.0.1, Connected Edition.
Section 8.5.2, Common Rules for Processing the XML Descriptors lists some additional rules, beyond those listed in the Java Servlet Specification, Java Card Platform, Version 3.0.1, Connected Edition, that the card management facility MUST implement and that the developer must account for concerning the processing of the web application deployment descriptor of the Java Card application.
The applet application deployment descriptor conveys APDU-based application model elements and configuration information of an application between application developers, application assemblers, and deployers. The applet application deployment descriptor is a mandatory file named APPLET-INF/applet.xml, which MUST be present in the applet application module JAR file.
The applet application deployment descriptor structure, content and semantics are defined in an XML schema document.
The following type of configuration and deployment information MUST be supported in the applet application deployment descriptor:
This section illustrates the elements in an applet application deployment descriptor. The notation convention used here is described in Section 8.5.1, Conventions Used in XML Descriptor Element Diagrams.
The applet-app element is the root element of the applet application deployment descriptor. This element has a required attribute version to specify to which version of the schema the Java Card Platform-specific application descriptor conforms. The attribute value MUST be “3.0”. FIGURE 8-12 shows the structure of the applet-app element. Each sub-element is described in the next sections.
FIGURE 8-12 applet-app Element Structure
The description element is used to provide text describing the parent element. This element occurs not only under the applet-app element, but also under other multiple elements. It has an optional attribute xml:lang to indicate which language is used in the description. The default value of this attribute is English (“en”).
The display-name element contains a short name that is intended to be displayed by tools. The display name need not be unique. This element has an optional attribute xml:lang to specify the language.
The applet element is used to declare the applet classes of the application. All concrete subclasses of javacard.framework.Applet within the application distribution unit that can be instantiated SHOULD be declared in the applet-class element with its corresponding Application Identifier in the applet-AID element. The applet-class element MUST be the fully qualified classname of the applet class. The applet-AID element uses the applet application URI format notation described in Section 2.3.1, Unified Naming Scheme. An applet not listed here MUST NOT be instantiated by the card management facility. FIGURE 8-13 shows the structure of the applet element.
FIGURE 8-13 applet Element Structure
The runtime descriptors convey runtime elements and configuration information of an application between application developers, application assemblers, and deployers.
The runtime descriptor information is not stored as a separate file within the distribution format JAR file structure. Instead, the runtime descriptor information is included in the metadata file, the META-INF/MANIFEST.MF file, at the top level of the directory structure of the application module distribution format.
The runtime descriptor includes information about the distribution format components, and runtime configuration and environment information. The information in the runtime descriptor is provided by the application provider and includes policy attributes relating to security and external access rules for the application.
The runtime descriptor information includes:
This section lists some general rules that the card management facility MUST implement and that the developer must account for concerning the processing of the runtime descriptor within the Java Card application distribution unit.
The runtime descriptor information is transcribed using the name/value pair format for each runtime attribute. The runtime descriptor information for an application module only defines attributes in the main manifest file section.
The syntax used for the runtime descriptor information in the application module is shown below in Section FIGURE 8-14, Runtime Descriptor Structure using a notation similar to that used for regular expressions conforming to the manifest file syntax conventions. The manifest file syntax specifications are applicable to the runtime descriptor information also, such as the use of the SPACE character at the start of a new line to indicate the continuation of the (previous) attribute value and the use of empty lines between manifest file sections. Manifest file attribute names are case-insensitive.
The metadata file(s), META-INF/MANIFEST.MF, may contain additional attributes beyond those described here as runtime descriptor information. These additional attributes declared in the META-INF/MANIFEST.MF file are case-insensitive application properties and may be retrieved by the application at runtime via the API javacardx.framework.JCSystem.getAppProperty() by providing the attribute name as the parameter. JAR file specification rules apply when attributes are duplicated. The application provider may define manifest file attributes to assign values to application properties defined by the application programmer for configuring the application code.
In addition, these standard manifest file attributes MUST be supported by the card manager:
The following attributes in the main section are defined as runtime descriptor information for the application module. Attributes not specified in this list MUST be treated as application defined items. Attributes may appear in any order. Attribute names are case insensitive.
The items shown in boldface above are reserved keyword names representing runtime properties. The : character separates the attribute from its assigned value. The <..> notation is used to describe the contents of the attribute value. The (..),{..} and [..] notation with the quantification suffix uses the standard regular expression notation with ? for 0 or 1, + for 1 or more, and * for 0 or more.
Each runtime descriptor attribute is described in detail in the following sections.
The Runtime-Descriptor-Version attribute MUST be present and marks the syntax described here. The value MUST be 3.0.
The Application-Type attribute MUST be present and its value indicates the type of the application model implemented by the module. The possible values are web, extended-applet or classic-applet.
The Classic-Package-AID attribute SHOULD be present for a classic applet application module. It MUST NOT be present for an extended applet application module or a web application module. The value of this attribute MUST be the classic application package AID URI. The AID URI is prefixed with //aid to denote the AID registry-based name space authority. The actual AID is represented as a string using a series of hexadecimal digits in uppercase, 2 per byte, concatenated together. The RID and PIX fields are separated by a slash. For example, the Java Card Platform RI sample JavaPurse package is represented by the package AID URI //aid/A000000062/03010C02. The Classic-Package-AID attribute uses the applet application URI format notation described in Section 2.3.1, Unified Naming Scheme.
The Web-Context-Path attribute MUST be present for a web application module. It MUST NOT be present for an extended applet application module or a classic applet application module. It contains the default Context path to be used by the web container for this web application. The web application URI is assigned this Context path by default if an alternate is not specified during instantiation.
The Web-Context-Path attribute value uses the application URI naming format as described in Section 2.3.1, Unified Naming Scheme.
This optional Web-Secure-Port-Number attribute MAY be present for a web application module. It MUST NOT be present for an extended applet application module or a classic applet application module. It contains the static port number that the web application module wishes to use during secure HTTP communication. If the static port number is already in use, the instantiation of the web application MUST fail. If this attribute is not specified, a port number is dynamically assigned to the web application module, for use during secure web container managed HTTP communication.
This optional Web-Client-Auth-Required attribute MAY be present for a web application module. It MUST NOT be present for an extended applet application module or a classic applet application module. It contains a boolean value keyword - true or false. If specified as true, the web container MUST perform Client authentication during the SSL/TLS handshake for an HTTPS session to access secure application resources. If this attribute is omitted, or specified as false, the default card setting for HTTPS sessions is used.
This optional Web-Secure-Access-Only attribute MAY be present for a web application module. It MUST NOT be present for an extended applet application module or a classic applet application module. It contains a boolean value keyword - true or false. If specified as true, the web container MUST allow access to the application’s resources only during an HTTPS session. If this attribute is omitted, or specified as false, the web container MUST allow access over plain HTTP to the application’s resources that are not protected by security constraints with transport guarantee requirements as declared in the web application deployment descriptor of the application.
The On-Card-Client-Role-List attribute is used to list all the on-card client roles. An on-card client MAY be mapped to client URIs by using the <Client-Role>-Mapped-To-Client-URI attribute or to a protection domain by using the <Client-Role>-Mapped-To-Domain-Name attribute or to an authentication credential by using the <Client-Role>-Mapped-To-Auth-Credential attribute that follows. An on-card client role MUST not be mapped more than once. A <Client-role> token listed here MUST be the On-Card-Client role name defined in the Java Card Platform-specific application descriptor element security-role/role-name with an ON-CARD-CLIENT category attribute.
Since manifest file attribute names are case-insensitive, on-card client role names which differ in case only cannot be uniquely mapped and MUST therefore result in the application being rejected.
The optional <Client-Role>-Mapped-To-Client-URI attribute allows an application provider to specify the mapping of on-card client security roles to actual client application URIs. The <Client-role> token used here MUST be one of the On-Card-Client roles listed for the On-Card-Client-Role-List attribute above. The attribute name is a concatenation of the <Client-role> token and the reserved keyword Mapped-To-Client-URI. Multiple on-card clients may be designated by using the path-prefix URI pattern notation.
The optional <Client-Role>-Mapped-To-Domain-Name attribute allows an application provider to specify the mapping of on-card client security roles to client applications' protection domain names. The <Client-role> token used here MUST be one of the On-Card-Client roles listed for the On-Card-Client-Role-List attribute above. The attribute name is a concatenation of the <Client-role> token and the reserved keyword -Mapped-To-Domain-Name. The protection domain name value used here MUST be prefixed with the protection domain URI scheme identifier pd and corresponds to the name of a protection domain, for example pd:Classic.
The optional <Client-Role>-Mapped-To-Auth-Credential attribute allows an application provider to specify the mapping of on-card client security roles to the credential alias names to be used for on-card client authentication. The <Client-role> token used here MUST be one of the On-Card-Client roles listed for the On-Card-Client-Role-List attribute above. The attribute name is a concatenation of the <Client-role> token and the reserved keyword -Mapped-To-Auth-Credential. The credential alias names used here reference the peer credential alias names defined in its CredentialManager object(s). If no corresponding peer credential alias name is defined in the CredentialManager object(s), authentication MUST fail.
The optional On-Card-Clients-Credential-Auth-Type attribute indicates the type of the on-card client authentication required by the application for its on-card client applications. The only supported value is client-only. The default value is client-only.
The optional On-Card-Clients-Credential-Auth-Duration attribute indicates the applicable duration of a successful on-card client authentication for its on-card client applications. The possible values are access, card-session or client-lifetime. The default value is card-session.
The optional <Client-Role>-Credential-Auth-Type attributes indicate the type of the on-card client authentication required by the application for this specific <Client-Role>. This attribute overrides any application wide authentication type setting in On-Card-Clients-Credential-Auth-Type attribute. The <Client-Role> name used here MUST correspond to a <Client-Role> mapped to credential alias names for on-card client authentication in the <Client-Role>-Mapped-To-Auth-Credential attribute. The only supported value is client-only.
The optional <Client-Role>-Credential-Auth-Duration attribute indicate the applicable duration of a successful on-card client authentication for this specific <Client-Role>. This attribute overrides any application wide authentication duration setting in the On-Card-Clients-Credential-Auth-Duration attribute. The <Client-Role> name used here MUST correspond to a <Client-Role> mapped to credential alias names for on-card client authentication in the <Client-Role>-Mapped-To-Auth-Credential attribute. The possible values are access, card-session or client-lifetime.
The User-Role-List attribute is used to list all the user roles that are mapped to authenticator URIs in the <User-Role>-Mapped-To-Auth-URI attributes that follow. The <User-role> token listed here MUST be the User role name defined in the web application deployment descriptor element security-role/role-name or the Java Card Platform-specific application descriptor element security-role/role-name with an USER category attribute.
Since manifest file attribute names are case-insensitive, user role names which differ in case only cannot be uniquely mapped and MUST therefore result in the application being rejected.
The optional <User-Role>-Mapped-To-Auth-URI attribute allows an application provider to specify the mapping of user security roles to authenticator URIs. The <User-role> token used here MUST be one of the User roles listed for the User-Client-Role-List attribute above. The attribute name is a concatenation of the <User-role> token and the reserved keyword -Mapped-To-Auth-URI. Multiple authenticators may be designated by using the path-prefix URI pattern notation. Authenticators and their URI naming conventions are described in Section 6.4.1, Scheme-specific Authenticators. User role to authenticator mapping is described in detail in Section 6.3.1.3, Role to User Mapping.
The card manager application and the card management facility cooperate in the loading of application modules on the card. Application modules (Section 8.4.1, Application Module Distribution Format) are deployment units which encapsulate applications.
The card manager application typically performs the following functions during the loading of an application module:
The card management facility is the platform level entity responsible for operating on the application module contents and communicating with the appropriate platform subsystems to perform the deployment of the application module and initialize its security.
Prior to loading the application module, the card management facility MUST ensure that the permission javacardx.spi.cardmgmt.CardManagementPermission with the target name deploymentUnit.load is granted to the card manager application.
The card management facility performs the following functions during the loading of an application module:
The classes in each application module are loaded in a namespace which is isolated from classes in other application modules. Applications may communicate with other applications via classes in the shareable interface class loader, extension library class loader, classic library class loader or the bootstrap class loader namepaces. The card management facility MUST create a new application module class loader within the class loader delegation hierarchy for loading the application module and follow the code isolation rules and class file lookup order requirements described in Section 6.7, Code Isolation.
The application programmer enumerates the exposed shareable interface classes used for inter-communication with other applications in other group contexts via the shareable-interface-classes elements of the Java Card Platform-specific application descriptor. These shareable interface classes MUST be loaded by the shareable interface class loader as described in Section 6.7, Code Isolation. Note that an interface class with an identical class name may already have been loaded by the shareable interface class loader. While loading another application, a name conflict MUST NOT be flagged.
When a shareable interface class is “promoted” from the application module class loader to the shareable interface class loader, all super interfaces of the shareable interface class and pseudo array classes of these classes, loaded (or being loaded) by the application module class loader, MUST also be automatically “promoted” to the shareable interface class loader. Super interfaces of the shareable interface class being loaded, which have been previously loaded by a different class loader MUST NOT be “promoted” to the shareable interface class loader.
Loading and Linking a class into the Runtime Environment of the card requires dependencies on other classes to be resolved. Class dependencies occur when a class directly links with another. A dependent class may be one of the following:
An application module class MUST only depend on class in the application module class loader or a class higher up in the class loader delegation hierarchy.
A shareable interface class loaded by the shareable interface class loader MUST only depend on a a class in the shareable interface class loader or a class higher up in the class loader delegation hierarchy.
A class linking dependency on a class loaded by a class loader lower in the class loader delegation hierarchy MUST result in the rejection of the deployment unit.
The Java Virtual Machine specification describes the process of loading, linking (including verifying, preparing and resolving) and initializing classes. The Java programming language allows an implementation flexibility as to when the loading and linking activities may take place. The Java Card platform requires the loading and linking activities to principally be performed when the card management facility loads the application module for the following reasons:
The process of performing the class loading and linking while loading the application module is called pre-loading. Note that pre-loading MUST NOT include initializing the classes as described in the Java Virtual Machine specification.
The following class pre-loading rules MUST be enforced by the card management facility during the loading of an application module:
The card manager application and the card management facility cooperate in the loading of libraries on the card. Extension libraries (Section 8.4.2, Extension Library Distribution Format) and classic libraries (Section 8.4.3, Classic Library Distribution Format) are deployment units which encapsulate libraries.
The card manager application typically performs the following functions during the loading of a library:
The card management facility is the platform level entity responsible for operating on the library contents and communicating with the appropriate platform subsystems to perform the deployment of the library.
Prior to loading the library, the card management facility MUST ensure that the permission javacardx.spi.cardmgmt.CardManagementPermission with the target name deploymentUnit.load is granted to the card manager application.
The card management facility performs the following functions during the loading of a library:
A class loaded by the extension library class loader MUST only depend on a a class in the extension library class loader or a class higher up in the class loader delegation hierarchy.
A shareable interface class loaded by the shareable interface class loader MUST only depend on a class in the shareable interface class loader or a class higher up in the class loader delegation hierarchy.
The card manager application and the card management facility cooperate to create instances of previously loaded application modules.
| Note - In this section, the term application instance is used to refer to both a web application instance as well as an applet instance. |
The card manager application typically performs the following functions while creating an application instance of a previously loaded application module:
The card management facility is the platform level entity responsible for creating application instances and communicating with the appropriate platform subsystems to manage the instance lifecycle, and their initialization and security requirements.
Prior to creating an application instance, the card management facility MUST ensure that the permission javacardx.spi.cardmgmt.CardManagementPermission with the target name application.create is granted to the card manager application.
The card management facility MUST perform the following validation steps and other functions during the creation of an application instance:
The card manager application and the card management facility cooperate to delete instances of previously instantiated applications/applets.
| Note - In this section, the term application instance is used to refer to both a web application instance, as well as an applet instance. |
The card manager application typically performs the following functions while deleting an instance of a previously instantiated application/applet:
The card management facility is the platform level entity responsible for deleting application instances and communicating with the appropriate platform subsystems to manage the application instance deletion and security requirements. An application instance is successfully deleted when all objects owned by the application instance are inaccessible on the card.
Prior to deleting an application instance, the card management facility MUST ensure that the permission javacardx.spi.cardmgmt.CardManagementPermission with the target name application.delete is granted to the card manager application.
The card management facility MUST perform the following validation steps and other functions during the deletion of an application instance:
The Java Card RE may freeze the other executing threads, including the container managed dispatcher threads on the card during the deletion process to prevent any new dependencies being introduced.
The card manager application and the card management facility MUST also cooperate to support the atomic deletion of multiple instances of previously instantiated applications/applets. The maximum number of application instances that may be deleted atomically is implementation dependent, but the deletion of two application instance MUST be minimally supported.
The process of deleting multiple instances is similar to that described for deleting a single application instance (Section 8.9, Deletion of Application Instance), with each application instance being deleted sequentially, except for the step to perform dependency checks, which are combined for all the application instances. The dependency checks MUST be performed on objects owned by all the application instances being deleted as one unit. The deletion process MUST fail if any object owned by any application instance being deleted is referenced from any other application instance or thread (not being deleted), any application module, any extended library, or any classic library.
The card manager application and the card management facility cooperate to delete previously loaded deployment units on the card. Application modules are deployment units which encapsulate applications. Extended libraries and classic libraries are deployment units which encapsulate libraries.
The card manager application typically performs the following functions during the unloading of a deployment unit:
The card management facility is the platform level entity responsible for unloading previously loaded deployment units and communicating with the appropriate platform subsystems to perform cleanup actions. A deployment unit is successfully deleted when all the classes, resources and descriptors comprising the deployment unit are not accessible on the card.
Prior to unloading a deployment unit, the card management facility MUST ensure that the permission javacardx.spi.cardmgmt.CardManagementPermission with the target name deploymentUnit.unload is granted to the card manager application.
The card management facility MUST perform the following validation steps and other functions during the unloading of a deployment unit:
The Java Card RE may freeze the other executing threads, including the container managed dispatcher threads on the card during the deletion process to prevent any new dependencies being introduced
The card manager application and the card management facility MUST also cooperate to support the atomic unloading of an application module combined with the deletion of all application instances from the application module.
The process to unload the application module and delete all contained instances is a combination of the process described for unloading an application module (Section 8.10, Unloading of Deployment Units) and that for deleting multiple application instances (Section 8.9.1, Multiple Application/Applet Instance Deletion), except for the step to perform dependency checks, which are also combined. The dependency checks MUST be performed on the application module and all objects owned by all the application instances being deleted as one unit. The deletion process MUST fail if the application module or any object owned by any application instance being deleted is referenced from any other application instance or thread (not being deleted), any other application module, or any library.
| Runtime Environment Specification, Java Card Platform, v3.0.1, Connected Edition | 5-30-09 |
|
Copyright © 2009 Sun Microsystems, Inc. All rights reserved.