J2EE Blueprints

Java TM Pet Store Demo

 security
   configuring https
 

The Java Pet Store application uses the HTTP protocol by default. This document describes how to enable a secure communication channel by enabling HTTPS. The tasks comprising these steps are:

  1. Stop the server, if it's running.

  2. Edit the Web Application Resource (WAR) file "web.xml" to reconfigure connection security.

  3. Rebuild the Enterprise Application Resource (EAR) file "petstore.ear" to reflect the new WAR configuration.

  4. Generate a security key for HTTPS.

  5. Restart the database and J2EE server.

  6. Deploy the new EAR file.

  7. Disable browser security warnings.

This procedure assumes there is already have a working copy of the Java Pet Store installed. If not, please refer to the main installation documentation, and install and test the Java Pet Store sample application before continuing with the following steps. The main installation instruction file is JPS_HOME/index.html.

In the following procedure, substitute the string <JPS_HOME> with the name of the base directory where the Java Pet Store is installed, and substitute <J2EE_HOME> with the name of the base directory where J2EE is installed.


Steps to Enable HTTPS

Follow these steps to enable HTTPS:

Stop the Server

1. Stop the J2EE server with command:

<J2EE_HOME>/bin/j2ee -stop

Edit the Web Application Resource (WAR) File

2. Change directory to:

<JPS_HOME>/src/petstore/src/docroot/WEB-INF

In a text editor, open the file (in that directory):

web.xml



3. Lines 49, 67, 85, 103 of this file should be:

<transport-guarantee>NONE</transport-guarantee>

Change them both to:

<transport-guarantee>CONFIDENTIAL</transport-guarantee>



4. Immediately after line 105 (after the final <security-constraint> tag, and before the first <login-config> tag), add the following security constraint:

<security-constraint>
      <web-resource-collection>
        <web-resource-name>MakeItSecure</web-resource-name>
        <description>no description</description>
        <url-pattern>/control/main</url-pattern>
        <http-method>POST</http-method>
        <http-method>GET</http-method>
      </web-resource-collection>
      <user-data-constraint>
        <description>no description</description>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
      </user-data-constraint>
    </security-constraint>

Build the New Enterprise Application Resource (EAR) File

5. Build a new Java Pet Store ear file with these changes with the command:

<JPS_HOME>/src/petstore/src

sh build.sh

The above command will build a new petstore.ear file at:

<JPS_HOME>/src/petstore/build/petstore.ear

If the build fails with error BUILD FATAL ERROR: Error exec, then give execute permission for the following file and then build again.

<JPS_HOME>/src/lib/ant/bin/antRun

Generate a Security Key

6. Create a private key for use in secure transactions with the following command:

<J2EE_HOME>/bin/keytool -genkey -keyalg RSA -alias jpsCert
Enter keystore password: changeit

The program will prompt you for a password (as shown above). Enter the default password "changeit" (without the quotes.) The program will then ask you a series of questions. Your answers to these questions will be used to generate a new key, which will take a few minutes. If the keytool complains that a key is already available, ignore the error and proceed with key generation.

Once it has finished generating the key, the program will ask:

Enter key password for <jpsCert>
(RETURN if same as keystore password):

Just hit RETURN (or ENTER).

Restart Database and Server

7. Start the cloudscape database and J2EE server with the commands

cloudscape -start
j2ee -verbose

Deploy New EAR File

8. Deploy the petstore.ear file created in step number 5, which is installed at

<JPS_HOME>/src/petstore/build/petstore.ear

To deploy this file, run the program

<J2EE_HOME>/bin/deploytool

In the deploytool's menu bar, open the new application file by clicking the menu item File, then click Open Application... Choose the file <J2EE_HOME>/build/lib/petstore.ear, and click the button labeled Open Application.

Then, to redeploy the application,click the menu item Tools, then click Update and Redeploy Application. The deploytool will redeploy the estore application.

Disable Browser Security Warnings

9. After completing deployment, visit the following URL in your browser:

http://localhost:8000/estore/index.html

If your browser is running on a machine other than the server, replace the host name local host above with the name of the server. For example, if the server is called potato, visit the URL:

http://potato:8000/estore/index.html

Click on the link labeled Enter the main store.

10. The browser will now attempt to connect to the server over the secure channel. The browser will display several warnings, because the new security key you created in step number 6 is not signed by a well-known certificate authority. These warnings will always be displayed the first time this key is used with this browser.

The following steps will disable these warnings:



If you are using a Netscape browser:

  • The first warning screen informs you that the data you accessed comes from a protected site and that its certificate is unrecognizable.

Click on the "Next>" button

  • The second warning screen displays the "Certificate Details"

Click on the "Next>" button

  • The next screen asks the acceptance duration of the certificate

Choose third option (accept the certificate forever) and click on the "Next>" button

  • The next screen displays some security information

Click on the "Next>" button

  • The next screen provides a summary

Click on the "Finish>" button

  • The next screen does a Certificate name check

Click on the "Continue" button



If you are using a Windows Explorer browser:

  • The first alert warns you that the data is from an untrusted site.

Click on the "Yes" button




Following step #10, all further interaction with the Java Pet Store sample application will be through the secure channel using the HTTPS protocol.

Note: To use a certificate signed by a certificate authority, please refer to the topic Setting Up a Server Certificate in Chapter 8 of the J2EE Developer's Guide. If your J2EE documentation directory is installed in your J2EE_HOME directory, this section appears at

<J2EE_HOME>/doc/guides/ejb/html/Security7.html

Otherwise, you can read the document online at http://java.sun.com/j2ee/j2sdkee/techdocs/guides/ejb/html/Security7.html.