PageBox |
Rationale | Presentation | News | Faq | Authors | Dev site | Mailing list |
Application server version
TABLE OF CONTENT
1 Foreword *
2 Parameters *
2.1 cachePath *
2.2 toTrace *
2.3 toStat *
2.4 ID *
2.5 logfile *
2.6 remoteLocations *
2.7 Publishers *
2.8 expiration *
2.9 allPermissionPolicy *
2.10 defaultPolicy *
2.11 keystore *
2.12 keystorePassword *
2.13 CAURL *
2.14 CRLURL *
2.15 CALDAPuser *
2.16 CALDAPpasswd *
2.17 CRLLDAPuser *
2.18 CRLLDAPpasswd *
2.19 CRLperiod *
3 Statistics and troubleshooting *
4 Notes on implementation *
4.1 Dynamic update *
4.2 ServletUpdate *
4.3 Non classes URL handling *
5 Special cases *
5.1 RequestDispatcher *
5.2 Use of SSL *
5.2.1 cacert analysis *
5.2.2 cacerts *
6 Tests *
6.1 Load test *
6.1.1 Performances *
6.1.2 Loitering *
6.2 Functional tests *
6.2.1 Update *
6.2.2 Security *
6.2.3 Misc *
7 Limitations *
8 Miscellaneous *
8.1 License *
8.2 Deliveries *
TABLE OF FIGURES
Figure 1: Statistics using ServletStat *
Figure 2: log using ServletLog *
Figure 3: JSPupdate *
Figure 4: ServletUpdate 1 *
Figure 5: ServletUpdate 2 *
JSPservletPkg is a complete implementation for servlets and JSP handling from a remote repository and with dynamic update.
JSPservletPkg is designed to be deployed in .war files.
There is no limitation to the number of war files, which can be configured, in a given Application Server.
Example:
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 1.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
<web-app>
<servlet>
<servlet-name>JSPservlet</servlet-name>
<servlet-class>JSPservletPkg.JSPservlet</servlet-class>
<init-param>
<param-name>cachePath</param-name>
<param-value>C:/temp/cachePath</param-value>
<description>local cache</description>
</init-param>
<init-param>
<param-name>toTrace</param-name>
<param-value>TRUE</param-value>
<description>trace activation</description>
</init-param>
<init-param>
<param-name>toStat</param-name>
<param-value>TRUE</param-value>
<description>stat activation</description>
</init-param>
<init-param>
<param-name>ID</param-name>
<param-value>1</param-value>
<description>unique identifier (PageBoxAPI)</description>
</init-param>
<init-param>
<param-name>logfile</param-name>
<param-value>C:/temp/cachePath/log.txt</param-value>
<description>trace location</description>
</init-param>
<init-param>
<param-name>remoteLocations</param-name>
<param-value>C:/temp/cachePath/jdj2.properties</param-value>
<description>jar remote location</description>
</init-param>
<init-param>
<param-name>Publishers</param-name>
<param-value>C:/temp/cachePath/jdj2-publisher.properties</param-value>
<description>publisher location per archive</description>
</init-param>
<init-param>
<param-name>expiration</param-name>
<param-value>30</param-value>
<description>resource expiration time</description>
</init-param>
<init-param>
<param-name>allPermissionPolicy</param-name>
<param-value>C:/temp/Resin/allPermission.policy</param-value>
<description>policy file granting all rights</description>
</init-param>
<init-param>
<param-name>defaultPolicy</param-name>
<param-value>C:/temp/Resin/default.policy</param-value>
<description>policy file for archives without explicit policy</description>
</init-param>
<init-param>
<param-name>keystore</param-name>
<param-value>keystore</param-value>
<description>keystore location + download policy</description>
</init-param>
<init-param>
<param-name>keystorePassword</param-name>
<param-value>keystorePswd</param-value>
<description>keystore password</description>
</init-param>
<init-param>
<param-name>CAURL</param-name>
<param-value>ldap://localhost/?</param-value>
<description>CA Certificate LDAP URL</description>
</init-param>
<init-param>
<param-name>CRLURL</param-name>
<param-value>ldap://localhost/?</param-value>
<description>Certificate Revocation List LDAP URL</description>
</init-param>
<init-param>
<param-name>CRLLDAPuser</param-name>
<param-value>?</param-value>
<description>CRL LDAP user</description>
</init-param>
<init-param>
<param-name>CRLLDAPpasswd</param-name>
<param-value>?</param-value>
<description>CRL LDAP password</description>
</init-param>
<init-param>
<param-name>CALDAPuser</param-name>
<param-value>?</param-value>
<description>CA certificate LDAP user</description>
</init-param>
<init-param>
<param-name>CALDAPpasswd</param-name>
<param-value>?</param-value>
<description> CA certificate LDAP password</description>
</init-param>
<init-param>
<param-name>CRLperiod</param-name>
<param-value>30</param-value>
<description>Certificate Revocation List scan period</description>
</init-param>
</servlet>
<servlet>
<servlet-name>ServletLog</servlet-name>
<servlet-class>JSPservletPkg.ServletLog</servlet-class>
</servlet>
<servlet>
<servlet-name>ServletStat</servlet-name>
<servlet-class>JSPservletPkg.ServletStat</servlet-class>
</servlet>
<servlet>
<servlet-name>ServletUpdate</servlet-name>
<servlet-class>JSPservletPkg.ServletUpdate</servlet-class>
</servlet>
<servlet>
<servlet-name>JSPupdate</servlet-name>
<servlet-class>JSPupdate</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>ServletUpdate</servlet-name>
<url-pattern>/ServletUpdate</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>ServletLog</servlet-name>
<url-pattern>/ServletLog</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>ServletStat</servlet-name>
<url-pattern>/ServletStat</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>JSPupdate</servlet-name>
<url-pattern>/JSPupdate</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>JSPservlet</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
</web-app>
It includes five servlet definitions, ServletUpdate, ServletLog, ServletStat, JSPservlet and JSPupdate.
JSPupdate is a compiled JSP stored outside the JSPservlet package. It must be configured with an url-pattern /JSPupdate.
ServletUpdate is a more advanced administration tool with the ability to display installed, loaded archives and
to set trace mode. It must be configured with an url-pattern /ServletUpdate.
ServletLog allows browsing remotely the log and to clear it.
ServletStat allows displaying statistics about servlets invocations
The package must contain:
WEB-INF
Web.xml // as the file above
classes
JSPupdate.class
JSPservletPkg
CRLchecker.class
JSPhandler$ClassEntry$ServletInfo.class
JSPhandler$ClassEntry$Stat.class
JSPhandler$ClassEntry.class
JSPhandler$Log.class
JSPhandler$Scanner.class
JSPhandler.class
JSPloader$ClassInfo.class
JSPloader$ProtectionDomainInfo.class
JSPloader$ResourceEntry.class
JSPloader.class
JSPloader$1.class
JSPloaderException.class
ResourcePrivilegedAction.class
JSPservlet$IncludeWriter.class
JSPservlet.class
JSPservlet$1.class
PageBoxAPI.class
ServletLog.class
ServletStat.class
ServletUpdate.class
SoapUpdate.class (Tomcat version only)
cachePath is the location where jars are locally stored after been retrieved from remote location.
Default value: C:/temp.
Tells if the tool must write diagnostic messages.
Default value: false.
Tells if the tool must record statistics.
Default value: false.
If true, statistics are recorded per archive in a file cachePath/archive.stat, which is a property file, for instance:
#Sun Nov 19 23:20:32 CET 2000
TestServlet/FileAccess=3
helloImg=8
TestServlet/OtherServlet=2
SnoopJSP=3
TestServlet/ForwardingServlet=4
SnoopServlet=2
Allows the deployer to specify a unique identifier.
PageBoxAPI allows retrieving this ID.
Application: deployment of a large number of instances.
No default value.
Tells where the tool must write diagnostic messages.
Default value: $CachePath/log.txt.
Location of a property file containing jar names and associated URLs.
Default value: $CachePath/$ContextPath.properties where ContextPath indicated the name the war file is deployed with.
JSPupdate, ServletUpdate and publication update this file. Though we don't recommend it, you can modify it manually but don’t expect to retrieve your comments.
Location of a property file containing for each archive the URL of the publisher that published it.
Default value: $CachePath/$ContextPath-publisher.properties where ContextPath indicated the name the war file is deployed with.
You can set this parameter to minimize the round trip number between the browser and the server.
JSPservlet sets the Expire header field of static content (content with an extension different of class). It computes the Expire as current_time + expiration.
expiration unit is second.
Default value: 5 seconds.
If it is set, allPermissionPolicy is the path to a policy file with syntax conforming to the Java 2 security specification. If defaultPolicy is also set it means:
The following no-brainer allPermissionPolicy will work in all cases:
grant {
permission java.security.AllPermission;
};
Note that you should never grant permissions in cachePath/archive policy as these files are downloaded from the archive location.
Default: the parameter has no default value.
If it is set, defaultPolicy is the path to a policy file with syntax conforming to the Java 2 security specification. If allPermissionPolicy is also set it means:
If no policy applies to the archive, then defaultPolicy is used
Default: the parameter has no default value.
If keystore is set to true, when JSPservletPkg downloads an archive, it tries:
The archive user has no longer to administrate security. It is appropriate for trusted providers.
Default: the parameter has no default value.
Password JSPservletPkg uses to access the keystore.
Default: the parameter has no default value.
When JSPservletPkg implements sandboxes, it processes signed archives and retrieve classes certificate chain. If CAURL is set, it connects to this URL and expects to retrieve a Certificate Authority certificate used in the classes certificate chain.
If it fails to connect to the CA or if what it retrieves is not a certificate, it logs an ERROR entry with "directory access failure". If the certificate is valid but not present in a class certificate chain, it invalidates the class just as if one of its certificates was revoked.
Note that JSPservletPkg doesn’t load the class and therefore doesn’t raise a security but a class not found exception.
If you set this parameter, you MUST add JNDI to your Java Server CLASSPATH in JDK 1.2. In JDK 1.3, you don’t have to, as JNDI is included in JDK.
Default: the parameter has no default value.
When JSPservletPkg implements sandboxes, it processes signed archives and retrieve classes certificates.
If CRLURL is set, it connects to this URL and expects to retrieve a Certificate Revocation List (CRL) used to check if a class certificate is revoked.
If it fails to connect to the CA or if what it retrieves is not a CRL, it logs an ERROR entry with "directory access failure". If the CRL is valid and it finds one of the class certificates in it, it invalidates the class.
Note JSPservletPkg doesn’t load the class and therefore doesn’t raise a security but a class not found exception.
If you set this parameter, you MUST add JNDI to your Java Server CLASSPATH in JDK 1.2. In JDK 1.3, you don’t have to, as JNDI is included in JDK.
Default: the parameter has no default value.
Principal used to connect to the Directory server to retrieve CAURL.
Default: the parameter has no default value. If it is not set, the tool connects to the Directory server without credential and password (LDAPpasswd).
Password used to connect to the Directory server to retrieve CAURL.
Default: the parameter has no default value.
Principal used to connect to the Directory server to retrieve CAURL.
Default: the parameter has no default value. If it is not set, the tool connects to the Directory server without credential and password (LDAPpasswd).
Password used to connect to the Directory server to retrieve CAURL.
Default: the parameter has no default value.
Defines how often the tool will connect to check for CRL updates in seconds.
Default: 7 * 24 * 3600 (1 week).
Figure 1: Statistics using ServletStat
Figure 2: log using ServletLog
Dynamic update of jar file is supported though JSPupdate.
You must fill the JAR Name field without extension. If you don’t fill the remote location the current location is reused. It is the JAR file URL minus the file name.
Assuming you specified a jar name myjar and a remote location http://www.mydownloadsite.com, JSPserletPkg will download http://www.mydownloadsite.com/myjar.jar and persist your action in RemoteLocations with a property myjar=http://www.mydownloadsite.com.
Note the URL of JSPupdate http://localhost:6080/jdj/JSPupdate. jdj is the Context Path (name the JSPservlet war file is deployed with). If you deploy different JSPservlet packages, you must select the appropriate JSPservlet to require an update. When you updates, the local cache is removed and the jar is always loaded from the remote location. You can also use JSPupdate to add a jar.
Then, you will able to request a servlet with a path servletPath in myjar.jar with
http://www.mysite.com/jdj/myjar/servletPath.
Let’s look at the JSPupdate code:
int index = jarName.lastIndexOf('.');If JSPupdate is invoked before the corresponding JSPservletPkg first use, JSPupdate invokes JSPservlet in order to initialize JSPhandler properly. It uses RequestDispatcher.include to achieve this result.
JSPservlet looks if it has been called on behalf of JSPupdate. It is the reason it has to be /JSPupdate.
ServletUpdate is a superset of the aforementioned JSPupdate.
Its display is split in two sections:
As JSPupdate, ServletUpdate uses GET mode. It is a servlet defined in the JSPservlet package.
It supports a trace checkbox and five buttons:
A fifth button is displayed if the application is not yet instantiated:
In this case ServletUpdate acts as JSPupdate.
Note that you can safely require an update when pages are accessed. Pending requests will hang up to the end of update for all archives controlled by a given JSPservletPkg Web Archive.
We chose a coarse grained synchronization to deliver the fastest response time in normal cases:
It is implemented in JSPhandler.get and JSPhandler.update.
Typical case of that is image handling.
Suppose a JSP whose URL is http://www.mysite.com/jdj/myjar/myJSP references an image with a relative path images/myimage.gif. The Application Server looks for http://www.mysite.com/jdj/myjar/images/myimage.gif and therefore invokes JSPservlet.
In this case, JSPservlet looks first for images/myimage.gif in the archive. If it doesn’t find it, it retrieves the download location in the myjar’s RemoteLocations property. If it finds its remote location is www.mydownloadsite.com, it tries downloading the image from www.mydownloadsite.com/images/myimage.gif. If it fails it relies on the Application Server to retrieve the image locally.
The only case where you must modify your code is when you need using a RequestDispatcher either to include or forward a request. You can use JSPservlet.getJAR() helper function.
RequestDispatcher rd = getServletContext().getRequestDispatcher(JSPservlet.getJAR(request) + OtherServlet);
The reason is as a servlet developer you should not hardcode neither the Web Application name as the standard enforces it, neither the jar name where your servlet will be deployed.
Its use is however optional:
JSPservlet allows using SSL to download archives using the Sun Java Secure Socket Extension (JSSE).
You can download it from http://java.sun.com/products/jsse. The 1.0.2 version is exportable with strong encryption.
The explanation below is not JSPservlet related but it still can help you to configure the thing. As it can fail at your first attempt, we recommend you reading the JSSE API user guide. It explains you how to trace the SSL connection with javax.net.debug=all and gives you a lot of information.
You need first to SSL enable the Web Server where you download the archive from. It implies generating a key pair. The server keeps the private key internally and asks you to submit a certificate request to the Certificate Authority of your choice.
During the SSL handshaking, jsse will check it knows the certificate chain the Web Server presents it using
<java-home>/lib/security/jssecacerts or <java-home>/lib/security/cacerts if jssecacerts doesn’t exist.
If your CA authority certificate is in the embedded list you have nothing to do.
cacerts format is jks, which means you can use keytool to display or update its content.
To check if it is enlisted, list <jsse-home>/samples/samplecacerts.
It contains the same data as cacert but with a known password changeit with the command:
keytool -list -keystore keystorepath -storepass changeit.
You only get a summary:
thawtepersonalfreemailca, Fri Feb 12 21:12:16 CET 1999, trustedCertEntry, Certificate fingerprint (MD5): 1E:74:C3:86:3C:0C:35:C5:3E:C2:7F:EF:3C:AA:3C:D9 thawtepersonalbasicca, Fri Feb 12 21:11:01 CET 1999, trustedCertEntry, Certificate fingerprint (MD5): E6:0B:D2:C9:CA:2D:88:DB:1A:71:0E:4B:78:EB:02:41 verisignclass3ca, Mon Jun 29 19:05:51 CEST 1998, trustedCertEntry, Certificate fingerprint (MD5): 78:2A:02:DF:DB:2E:14:D5:A7:5F:0A:DF:B6:8E:9C:5D thawtepersonalpremiumca, Fri Feb 12 21:13:21 CET 1999, trustedCertEntry, Certificate fingerprint (MD5): 3A:B2:DE:22:9A:20:93:49:F9:ED:C8:D2:8A:E7:68:0D thawteserverca, Fri Feb 12 21:14:33 CET 1999, trustedCertEntry, Certificate fingerprint (MD5): C5:70:C4:A2:ED:53:78:0C:C8:10:53:81:64:CB:D0:1D verisignclass4ca, Mon Jun 29 19:06:57 CEST 1998, trustedCertEntry, Certificate fingerprint (MD5): 1B:D1:AD:17:8B:7F:22:13:24:F5:26:E2:5D:4E:B9:10 duke, Thu Apr 27 01:36:49 CEST 2000, trustedCertEntry, Certificate fingerprint (MD5): 4C:CF:5E:5C:CE:69:5B:52:67:53:B7:8A:79:D3:A2:5B verisignserverca, Mon Jun 29 19:07:34 CEST 1998, trustedCertEntry, Certificate fingerprint (MD5): 74:7B:82:03:43:F0:00:9E:6B:B3:EC:47:BF:85:A5:93 verisignclass1ca, Mon Jun 29 19:06:17 CEST 1998, trustedCertEntry, Certificate fingerprint (MD5): 51:86:E8:1F:BC:B1:C3:71:B5:18:10:DB:5F:DC:F6:20 thawtepremiumserverca, Fri Feb 12 21:15:26 CET 1999, trustedCertEntry, Certificate fingerprint (MD5): 06:9F:69:79:16:66:90:02:1B:8C:8C:A2:C3:07:6F:3A verisignclass2ca, Mon Jun 29 19:06:39 CEST 1998, trustedCertEntry, Certificate fingerprint (MD5): EC:40:7D:2B:76:52:67:05:2C:EA:F2:3A:4F:65:F0:D8
If you want to know more on a given certificate you need to export it with:
keytool -export -file C:\TEMP\certfile.cer -alias verisignserverca -keystore keystorepath -storepass changeit
Then you can list it with:
keytool -printcert -file C:\TEMP\ certfile.cer
If the server Certificate Authority certificate is not in the list, you have to add it.
Retrieving it depends on the browser and on the Certificate Authority. You can ask for a DER encoded or for a base 64 format.
You also need to copy <jsse-home>/samples/samplecacerts into
<java-home>/lib/security/jssecacerts.
Then you can add your server certificate with:
keytool -import -file C:\TEMP \serverCA.cer -alias myCA keystore
<java-home>/lib/security/jssecacerts -storepass changeit
Tested environments:
With up to 6000 servlets and JSP in a single jar file.
The performance impact of tracing is below 10%.
The sandbox performance impact is not measurable.
No memory increase found between 6000 and 18000 invocations
among 6000 different JSPs.
Test performed with and without sandbox, with signed or not archives.
JSPupdate
ServletUpdate
Multiple archives, multiple web applications
Invalid archive name/location
Note:
servletUpdate can or not display multiple Web Application depending on the JSPhandler class loader.
If the same class loader instance is used for all JSPhandler - which is the case if you put the package on the CLASSPATH, then you display all Web applications.
Otherwise generally you are displayed only the Web application, servletUpdate belongs to.
Non-signed archive
Signed archive with and without sandbox. With sandbox:
1 policy file per web application or 1 per archive.
No permission granted to a signed archive.
Policy/certificate download
We checked that the tool supports:
Generally speaking, it requires no change of servlets/JSP code and compilation.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; version 2.1 of the License.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
Package name: JSPLoaderPkg.
Source files:
CRLchecker.java | JNDI/LDAP code |
JSPloader.java | class loader |
ResourcePrivilegedAction.java | resource handling designed to be invoked by AccessController.doPrivileged (implements PrivilegedAction) |
JSPloaderException.java | package exception |
JSPhandler.java | Web application handler |
JSPservlet.java | service servlet |
PageBoxAPI.java | API to get the PageBox ID and log user messages |
ServletLog.java | servlet to clear and display log |
ServletStat.java | servlet to display stats |
ServletUpdate.java | update servlet |
SoapUpdate.java | update class designed to be invoked by SOAP (tested with Apache SOAP version 2) |
JSPupdate.jsp | update JSP |
Documentation:
Rationale
Presentation News
Faq Dev site
Mailing lists Home
Installation Versions Constellations
Demo Publisher Mapper
Cocoon/SOAP Configurator
J2EE version Embedded version
Diskless version
Contact:support@pagebox.net
©2001 Alexis Grandemange
Last modified