| Runtime Environment Specification, Java Card Platform, v3.0.1, Connected Edition |    
|
| C H A P T E R 3 |
|
Web Application Environment |
This chapter describes the interactions and dependencies between the platform, the web container and web applications:
The Java Servlet Specification for the Java Card Platform, v3.0.1, Connected Edition is a subset of the Java Servlet Specification v2.4. In addition to features that have been subset out due to dependencies on APIs or features not supported by the Java Card Virtual Machine or intended for deployment in web containers that are JavaServer Pages
(JSP) technology enabled or part of a Java Platform, Enterprise Edition (Java EE) application server, the following features have been removed or adapted to the Java Card platform:
Web application modules are the logical units of assembly of web applications. All the components of a web application MUST be assembled into a web application module. See Section 8.4.1.1, Web Application Module Distribution Format for details on the structure of web application modules.
When being deployed, a web application will typically go through the following lifecycle:
1. Loading of the web application module, see Section 3.2.1, Application Module Loading.
2. Creation of an instance of the web application, see Section 3.2.2, Application Instance Identification and Section 3.2.3, Application Instance Creation.
3. Execution of the web application instance:
4. Restart upon platform reset, see Section 3.2.6, Restart Upon Platform Reset.
5. Deletion of the web application instance, see Section 3.2.4, Application Instance Deletion.
6. Unloading of the web application module, see Section 3.2.5, Application Module Unloading.
Some web application modules may contain only dynamic contents; others may contain only static content; others may contain both dynamic and static contents. All such configurations of web applications MUST be managed according to the lifecycle described above.
A web application may be instantiated many times, but there MUST NOT be more than one instance of the web application at any time, that is, multi-instantiation of a web application MUST NOT be supported.
When a web application module is being loaded, the following requirements MUST be implemented by the Java Card Platform:
Any error during loading, especially module format errors, descriptor format errors, descriptor and code consistency errors, MUST result in the loading of the application module to fail and the application module to be rejected.
Refer to Section 8.6, Loading Application Modules for the other generic requirements that MUST be implemented by the Java Card Platform when an application module is loaded.
Every web application instance MUST be rooted at a specific path within the web container known as its context path. The context path of a web application instance determines the URL namespace of the contents (both static and dynamic) of the application. All requests whose URL start with that context path MUST be routed to that application instance.
Every web application instance is named with a relative URI - its application URI - that uses the null registry-based authority and whose path component corresponds exactly to its context path. This application URI defines the root of a dedicated namespace within which all its resources, not only web contents but also SIO-based services, events and files, MUST be named.
A legal context path MUST satisfy the following requirements:
See Section 2.3, Unified Naming and Dedicated Application Namespaces for details on the additional constraints on naming web applications.
| Note - To maximize portability, a web application developer should name or refer to a web application’s resources both in code and descriptors using relative URIs. |
When a web application instance is being created, the following requirements MUST be implemented by the Java Card Platform:
1. An instance of the ServletContext interface MUST be created and rooted at a legal context path in the web container’s namespace. The context path MUST correspond to the application’s URI. This instance of the ServletContext MUST serve as the logical root of persistence for the application instance, see Section 3.2.9, Container-managed Object Lifetime and Persistence.
2. The web application’s structured hierarchy of directories MUST be made available to the web container for servicing the application’s static content relatively to the assigned context path. The root of this hierarchy serves as the document root for files that are part of the application:
a. The WEB-INF and META-INF directories are not part of the public document tree of the application. A file contained in the WEB-INF and META-INF directories MUST NOT be served directly to a client by the web container.
b. All the files with the exception of those under the WEB-INF/classes, WEB-INF/lib (if present[2]) and META-INF directories and with the exception of the deployment descriptor WEB-INF/web.xml MUST be made available to the application’s code in the following ways:
i. These files MUST be made available to the application’s code using the ServletContext.getResourceAsStream method.
ii. These files MUST be made available to the application’s code using the ServletContext.getRequestDispatcher and ServletRequest.getRequestDispatcher methods.
iii. The ServletContext.getRealPath method MUST return the real path of these files on the card’s file system (if any is supported). A static resource served for the request URI <context path><resource path> MUST have a real path in the form of <context path><resource path>. If no file system is supported, the ServletContext.getRealPath method MUST return null. The real path of a resource file on the card’s file system may be built into a file URL of the form file://<real path> and used to access the resource file with a GCF file connection. See Chapter 9 for more details on file system support.
| Note - The resource path <resource path> when passed as parameter to the getRealPath method must begin with a "/" and is interpreted as relative to the context root denoted by <context path>. |
c. The class-path resources in the module’s WEB-INF/classes directory MUST be made available to the application’s code using the Class.getResourceAsStream method.
3. The following steps, described in more detail in the “Web Applications” chapter of the Java Servlet Specification for the Java Card Platform, v3.0.1, Connected Edition, MUST be performed before any request can be dispatched to the web application instance:
a. Create an instance of each life cycle event listener described in the web application deployment descriptor. Notify context event listeners of the web context initialization event.
b. Create and initialize an instance of each filter described in the web application deployment descriptor. The container initializes the filter instance by calling its init method.
c. Create and initialize an instance of each load-on-startup servlet described in the web application deployment descriptor in the applicable order. The container initializes the servlet instance by calling its init method.
Any exception during this sequence MUST result in the application creation failing. See Section 3.3.1.2, Handling of Errors and Exceptions Outside of Request Processing.
4. The web container MUST listen and accept connections on an application-dedicated secure port, if required. This is in addition to listening and accepting connections on the default plain and secure ports. See Section 3.5, Secure Hosting of Web Applications.
5. The web container MAY start dispatching requests as per Section 3.2.7, Request Dispatching.
All files in the application’s namespace MUST only be accessible to that application. An implementation MAY store and manage a web application’s resources as live objects bound to that application's group context or MAY store and manage a web application’s resources on a file system with access permissions restricted to that application, see Chapter 9.
Write access to a web application’s structured hierarchy of directories MUST be subject to access control. When a javax.microedition.io.Connector.openXXX method is invoked, a security check MUST ensure that the permission javacardx.io.ConnectorPermission with the target canonicalized file URI and the action write is granted.
Refer to Section 8.8, Creation of Application Instances for the other generic requirements, such as assignment to the proper group context and protection domain, that MUST be implemented by the Java Card Platform when an application instance is created.
When a web application instance is being deleted, the following requirements MUST be implemented by the Java Card Platform:
1. The container MUST stop dispatching requests to the application instance through request dispatchers both from web clients on the default ports and the application-dedicated secure port, as well as from other web applications. Any requests subsequently received on these ports MUST be responded to with an HTTP status code 404 (Not Found). Any attempt to dispatch a request using a request dispatcher MUST fail.
2. The container MUST stop listening and accepting connections on the application-dedicated secure port and MUST close all such already open connections.
3. Once the application instance has finished servicing the requests currently being handled or after some container-defined timeout, the following steps, described in more details in the Java Servlet Specification for the Java Card Platform, v3.0.1, Connected Edition, MUST be performed:
a. All servlet instances MUST be removed from service. The container first calls the destroy method on a servlet to enable the servlet to release any resources and perform other cleanup operations. The destroy method is only called once all threads within the servlet’s service method have exited or after a timeout period has passed.
b. All filter instances MUST be removed from service. The container first calls the destroy method on a filter to enable the filter to release any resources and perform other cleanup operations. The destroy method is only called once all threads within the filter’s doFilter method have exited or after a timeout period has passed.
c. The container MUST invalidate all HTTP sessions the application instance may participate in and session listeners MUST be notified of session invalidations in the applicable order.
d. Context listeners MUST be notified of context destruction in the applicable order.
4. All GCF connections open by the application instance, including network connections as well as file connections, MUST be closed.
5. When no container-managed thread is still executing the application’s code through any of its entry point methods, the web application’s ServletContext instance MUST be destroyed and the context path corresponding to its application URI MUST be released. The web application’s structured hierarchy of directories MUST no longer be accessible to the web container for servicing the former application’s static content.
The URI identifying a web application instance, meaning its context path, becomes unassigned once the application instance has been deleted. The context path MUST only be reassigned once the application instance is considered effectively deleted, Section 8.9, Deletion of Application Instance.
Refer to Section 8.9, Deletion of Application Instance for the other generic requirements that MUST be implemented by the Java Card Platform when an application instance is deleted.
When a web application module is being unloaded, the following requirements MUST be implemented by the Java Card Platform:
Refer to Section 8.10, Unloading of Deployment Units for the other generic requirements that MUST be implemented by the Java Card Platform when an application module is unloaded.
After a platform reset, the Java Card Platform MUST perform the following steps before any request can be dispatched to a web application instance:
1. The web container MUST handle all volatile container-managed objects as described in Section 3.2.9.4, Behavior Upon Platform Reset and MUST perform the following actions in sequence:
i. All active sessions are cleared - volatile HTTP session objects are garbage collected. Listeners registered to receive session destruction events are not notified.
ii. All pending requests and responses are cleared - volatile HTTP request and response objects are garbage collected. Listeners registered to receive request destruction events are not notified.
Refer to Chapter 5 for the other generic requirements that MUST be implemented by the Java Card Platform after a platform reset.
When a web application instance has been created, the following requirements MUST be implemented by the Java Card Platform:
1. The web container MUST accept requests for the web application instance both from web clients on the default ports and the application-dedicated secure port, as applicable, and from other web applications. The web container MUST forward to the web application instance requests whose start of the URL matches the context path of the application instance.
| Note - On the Java Card Platform, application URIs, and therefore context paths, MUST NOT overlap, see Section 2.3, Unified Naming and Dedicated Application Namespaces. Therefore, searching for the web application instance with the longest context path that matches the start of the request URL is always equivalent to searching for the first web application instance with the context path that matches at least the first path component of the request URL. |
2. On requests received from web clients, the web container MUST implement the following requirements:
a. The security constraint whose web resource collection URL pattern and HTTP method match the request’s URI and HTTP method MUST be enforced.
| Note - On the Java Card Platform, web resources to which a security constraint applies MUST only be designated with a URL pattern to which a servlet has been mapped. |
i. The authorization constraints MUST be enforced. An authorization constraint establishes a requirement for authentication and names the authorization roles permitted to perform the constrained requests. See Section 6.4.5, Web Container-managed Authentication and Section 6.3.1, User Role-based Security for more details.
ii. The user data constraints MUST be enforced. A user constraint establishes requirements that the constrained requests be received over a protected transport layer connection. See Section 3.5, Secure Hosting of Web Applications.
b. The filter chain and servlet or static content whose URL pattern match the request’s URI MUST be invoked in the applicable order.
| Note - On the Java Card Platform, web resources to which a filter applies MUST only be designated with a URL pattern to which a servlet has been mapped. |
3. On requests received from other web applications through the request dispatcher, the web container MUST implement the following requirements:
a. The servlet whose URL pattern matches the request’s URI MUST be invoked. See Section 3.2.7.1, Restriction On the Use of Request Dispatchers for details on the restrictions that apply.
| Note - On the Java Card Platform, URL patterns to which servlets are mapped MUST NOT overlap. |
A web application MUST be allowed to retrieve the servlet context of another application in the same group context using the ServletContext.getContext method, by passing the context path of that other application. The web application can then retrieve a request dispatcher from that other application’s servlet context to issue a forward or include call to one of that other application’s resources.
A web application MUST NOT be allowed to retrieve the servlet context of an application in another group context. The ServletContext.getContext method MUST return null in such a situation.
The Java Card Platform does not mandate any Java Card-specific behavior on lifecycle event dispatching.
When a web application is instantiated, the web application container creates an instance of ServletContext (an instance of a Java Card RE defined class that implements the javax.servlet.ServletContext interface) to manage the newly instantiated web application. This instance MUST be promoted to become a persistent object by virtue of being reachable from a persistent web container managed object. This instance of the ServletContext serves as the logical root of persistence for the newly instantiated application. This instance of ServletContext is deleted only when the application is deleted.
When executing a web application, the container MUST instantiate container-managed objects, meaning objects created by the container as per its operating principles (see Java Servlet Specification, Java Card Platform, Version 3.0.1, Connected Edition). Container-managed objects include instances which define the application’s business logic such as servlets (instances of application-defined classes that implement the javax.servlet.Servlet interface), filters (instances of application-defined classes that implement the javax.servlet.Filter interface), and event listeners (instances of application-defined classes that implement the java.util.EventListener interface). Container-managed objects also include instances which are used to encapsulate HTTP sessions and HTTP messages, meaning session objects (instances of a Java Card RE defined class that implement the javax.servlet.http.HttpSession interface), request objects (instances of a Java Card RE defined class that implement the javax.servlet.http.HttpServletRequest interface) and response objects (instances of a Java Card RE defined class that implement the javax.servlet.http.HttpServletResponse interface). In addition, container-managed objects include event objects (instances of Java Card RE defined classes that implement the java.util.EventObject interface), which are created by the container when a particular condition needs to be handled.
All container-managed objects which are instances of classes defined by the application MUST be bound to the owner context of the application itself. All container-managed objects which are instances of classes or interfaces defined in the javax.servlet package and its sub-packages MUST be bound to the owner context of the application itself. All other container-managed objects which are instances of classes defined by the Java Card RE MAY be owned by the Java Card RE.
Specific lifetime and persistence requirements of some container-managed objects are described in the following sections. Any container-managed object which is not called out specifically MAY have implementation assigned lifetime and persistence characteristics.
The following container-managed objects MUST be persistent objects. They are created when the application is instantiated and can be garbage collected only when the application instance is deleted.
The following container-managed objects MAY be volatile objects:
The following container-managed objects MUST be volatile objects unless promoted to become a persistent object by the application:
| Note - Container-managed volatile session objects SHOULD be referenced via reachability disrupting objects from the application’s servlet context object or the container object itself. |
The following container-managed objects MUST be volatile objects unless promoted to become a persistent object by the application:
Upon card reset, all volatile objects MUST be garbage collected. All references to volatile objects in reachability disrupting objects MUST be reset to null.
Servlet, filter and listener lifecycle methods are invoked by the web container. These methods may also get called indirectly by an application itself in the following situations:
Note that as per the recommendation in Section 3.3.4, Multithreading Issues, using request and response objects outside the scope of the request handling thread and the call of the service method is not advisable.
Any uncaught exception thrown from within a servlet, filter or listener lifecycle method is propagated back to the original caller. If the original caller is the web container, these exceptions must be handled specifically depending on the context of the invocation, see Section 3.3.1.1, Handling of Errors and Exceptions During Request Processing and Section 3.3.1.2, Handling of Errors and Exceptions Outside of Request Processing.
When an exception is thrown by a servlet, filter or listener while processing a request, the container MUST take appropriate measures to clean up the request, depending on the error or exception. The type of request includes not only exceptions and errors thrown by the Servlet.service or Filter.doFilter methods, but also by other lifecycle methods that may be invoked to create the component to service a request, such as the Servlet.init method. The subsequent request to a component that generated such an error or exception, also depends on the error or exception:
An error or exception may be thrown by a servlet, filter or listener lifecycle method outside the scope of processing a request by a specific component, such as during initialization at application start-up when creating listeners, filters and load-on-startup servlets, or during handling the notification of a request initialization. This MUST be considered an internal application error:
Shareable interface methods, create methods of SIO-based service factories, notify methods of event listeners and run methods of restartable tasks constitute as many additional entry points into web applications:
See Section 3.3.4, Multithreading Issues.
The use by a web application of the CLEAR_ON_DESELECT flag when calling one of the makeTransient...Array() methods MUST result in a javacard.framework.SystemException with reason code ILLEGAL_TRANSIENT being thrown.
See Section 2.8.2.1, Reachability Disrupting Objects for more details.
A web application’s code may be concurrently executed by multiple threads. These threads can be categorized as follows:
The web application container MAY use multiple threads to concurrently manage the lifecycle of web application components (servlets, filters and listeners) and to service incoming HTTP requests concurrently. In this specification, these threads are referred to as Java Card RE-managed threads or container-managed threads.
Some web application container implementations MAY limit the number of concurrent container-managed threads, thereby limiting the number of HTTP requests which may be handled concurrently. Some web application container implementations MAY rely on a pool of reusable threads to allow for both limiting the number of threads and allowing threads to be reused for several requests.
Web applications may create new threads. A Java Card Platform implementation MAY restrict the creation of such application-managed threads to ensure that other components of the platform are not negatively impacted. Web applications are responsible for managing the lifecycle of threads they create. They must especially account for restarting such threads, if needed, after platform resets.
The servlet container MUST handle concurrent requests to the same servlet by concurrently executing the service method on different threads. The servlet container MUST, nevertheless, ensure that the re-dispatch of the request to another servlet, such as per an include or forward, occurs in the same thread as the original request.
The servlet container MAY not guarantee that the notification of attribute changes to ServletContext and HttpSession objects be synchronized.
The servlet container MAY not guarantee container-managed objects such as request and response objects be thread safe.
These requirements dictate that web application developers handle the related thread safety issues explicitly:
As mentioned above, a web application’s code may be concurrently executed by multiple threads, which may not all be request handling threads. Web application developers must, therefore, explicitly handle thread safety issues on application objects that may be concurrently accessed.
All web container-managed threads MUST be owned by the Java Card RE. This includes all request handling threads and other web application component lifecycle handling threads. See Section 2.7.4, Thread Ownership for more details on the restrictions that apply to Java Card RE-owned threads.
Threads created by a web application MUST be owned by that application.
When the URL of a requested resource cannot be mapped to any of the declared servlets as per the URL path mapping rules described in the Java Servlet Specification, Java Card Platform, Version 3.0.1, Connected Edition, in the section on the use of URL paths, the container MUST attempt to serve content appropriate for the resource requested. If a default servlet is defined for the application, it MUST be used. This allows for serving the static resources of a web applications in response to requests from web clients.
| Note - A servlet may be configured as the default servlet for a web application by being mapped to the “/” URL pattern in its web application deployment descriptor. |
In addition to the standard behavior described in the Java Servlet Specification, Java Card Platform, Version 3.0.1, Connected Edition, the default container behavior when no default servlet is explicitly configured for an application in its web application deployment descriptor MUST be the following:
A container MUST define a default default servlet implementing this default container behavior that is mapped to the ”/” URL pattern. This servlet MUST be implemented by the javacardx.servlet.http.DefaultServlet class.
The Java Card Platform version of the specification does not support security constraints on static web resources serviced by the web container as per its default behavior. It imposes the following restriction on the use of url-pattern for filter mapping and security-constrained web resource collections: the url-pattern value for filter mapping and security-constrained web resource collections MUST exactly correspond to the url-pattern of one of the servlet-mapping elements defined for mapping request URL to servlets in the deployment descriptor.
An application developer who wants to define security constraints or filters for static content served as per the default container behavior must, therefore, explicitly redeclare the mapping to the default servlet as follows:
<servlet>
<description>default servlet</description>
<servlet-name>default</servlet-name>
<servlet-class>javacardx.servlet.http.DefaultServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>default</servlet-name>
<url-pattern><path></url-pattern>
</servlet-mapping>
<path> may be a specific path to an application’s static content or it may be ‘/’ and may, therefore, designate all that application’s static content.
A web application that has requirements for content integrity and confidentiality declares at least one user data security constraint with a transport guarantee value of INTEGRAL or CONFIDENTIAL in its web application deployment descriptor. See the “Security” chapter of the Java Servlet Specification for the Java Card Platform, v3.0.1, Connected Edition for more details on specifying security constraints.
On the Java Card Platform, the web container MUST implement an application’s requirements for content integrity and confidentiality by only accepting requests for that application to which these constraints apply, over HTTPS connections set up accordingly.
Additionally, a web application may define in its runtime descriptor a specific requirement for secure port allocation, see Web-Secure-Port-Number Attribute in Chapter 8. A web application may also define in its runtime descriptor a requirement for exclusive secure access of all its content, see Web-Secure-Access-Only Attribute in Chapter 8.
The Java Card Platform MUST host on an application-dedicated HTTPS port each web application that has requirements for transport guarantee or that has a requirement for secure port allocation, see Section 3.5.1, Port-based Virtual Hosting. The security characteristics of connections from web clients on that application-dedicated HTTPS port MUST be negotiated using the credentials retrieved from the javacardx.security.CredentialManager instances set for the web application instance, see Section 3.5.3, Retrieving a Web Application Instance’s Security Requirements and Credentials.
The Java Card Platform MUST host each web application instance according to the transport guarantee requirements expressed in its web application descriptor and according to the secure port allocation requirement expressed in its runtime descriptor. A web application instance MUST be hosted as follows:
TABLE 3-1 summarizes how a web application instance MUST be hosted depending on its overall transport guarantee requirements and its secure port allocation requirement.
| Note - A Java Card Platform implementation is not required to support a default secure port because this requires card-wide credentials. |
The web container MUST determine the secure port on which to host a web application instance’s content as follows:
A statically or dynamically allocated secure port MUST be dedicated to a single web application instance. The web container MUST implement the following step to host a web application instance on the secure port allocated to a web application instance:
The default plain port is not dedicated to a single web application instance; several web application instances MAY be hosted fully or partially on the default plain port. The web container MUST implement the following step to host a web application instance or only its unprotected content on the default plain port:
FIGURE 3-1 depicts the secure hosting of web applications and the redirection of requests to their secure ports.
FIGURE 3-1 Request Dispatching and Redirection to Web Applications’ Secure Ports
A web container implementation MAY use the default secure port 443 to host web application instances instead of hosting these applications on the plain default port. Using the default secure port requires that the credentials to be used to establish secure connections with web clients be managed at the web container level, that is, not on a per-application basis. Such a configuration may be specific to an operating environment where cards may be issued with card credentials.
When performing an HTTP redirection the web container MUST construct an HTTP response with the following characteristics:
The hosting of a web application on an application-dedicated secure HTTPS port relies on security requirements and credentials, private to the application, to be retrieved from the application itself or its group context during the SSL/TLS protocol handshakes. The SSL/TLS protocol handler MUST retrieve the security requirements and the required credentials from the javacardx.security.CredentialManager.SecurityRequirements and javacardx.security.CredentialManager instances set for the web application instance, either by the card manager application or by the application itself. The SecurityRequirements and CredentialManager instances to be used MUST be the ones that are set for CredentialManager.MODE_WEB_SERVER mode of operation.
The SecurityRequirements instances are used to determine if client authentication, integrity and confidentiality of the data transmitted are required for connections from any web client on the application-dedicated secure port.
The CredentialManager instances are used to retrieve the key and trust material of the web application instances and to make trust decisions, that is, deciding to trust or not a particular web client attempting to connect on the application-dedicated secure port.
A SecurityRequirements or CredentialManager instance may be set in the group context of a web application instance by the card manager and may, therefore, apply to all application instances in that group context, or it may be set by a specific web application instance for itself and may, therefore, apply to that application instance only. When a SecurityRequirements or CredentialManager instance has been set for a mode of communication by a web application, it is retrieved in priority to the default instance set in the group context by the card manager application when establishing a secure communication in that mode for that web application.
The SSL/TLS protocol handler MUST invoke methods of the SecurityRequirements and CredentialManager instances set for CredentialManager.MODE_WEB_SERVER mode of operation with at least the following mandatory parameters:
See Section 6.6, Security Requirements and Credential Management of Secure Communications for more details on the use of credential managers.
The web container MUST negotiate the security characteristics of HTTPS connections using the SecurityRequirements instance applicable for the web connection being established:
If no applicable SecurityRequirements instance can be determined for the web application instance, the requirements MUST default to the requirement for client authentication and the overall requirements for content integrity and confidentiality of the web application, as declared in its runtime descriptor and deployment descriptor, respectively.
The default implementation of the isConfidentialityRequired, isIntegrityRequired and isClientAuthRequired methods of the base SecurityRequirements class MUST indicate - for the CredentialManager.MODE_WEB_SERVER mode of operation - the requirements of a web application for content confidentiality, content integrity and client authentication, respectively, as declared in the deployment descriptor and runtime descriptor of that web application:
An application-defined credential manager may use this information to never request for a security level that would be lower than what the web application’s deployment and runtime descriptors are requiring; this, in order to avoid requests to certain of its resources - those that require stronger transport guarantees - to be rejected by the web container.
The web container MUST provide the following means for a web application to retrieve the security characteristics of the connection over which a request was received:
See the “The Request” chapter of the Java Servlet Specification for the Java Card Platform, v3.0.1, Connected Edition for more details on the SSL connection attributes associated with a request.
| Runtime Environment Specification, Java Card Platform, v3.0.1, Connected Edition | 5-30-09 |
|
Copyright © 2009 Sun Microsystems, Inc. All rights reserved.