Digital certificates for the Application Server have already been generated and can be found in the directory domain-dir/config/. These digital certificates are self-signed and are intended for use in a development environment; they are not intended for production purposes. For production purposes, generate your own certificates and have them signed by a CA.
The instructions in this section apply to the developer and cluster profiles of the Application Server. In the enterprise profile, the certutil utility is used to create digital certificates. For more information, see the Sun Java System Application Server 9.1 Administration Guide.
To use SSL, an application or web server must have an associated certificate for each external interface, or IP address, that accepts secure connections. The theory behind this design is that a server should provide some kind of reasonable assurance that its owner is who you think it is, particularly before receiving any sensitive information. It may be useful to think of a certificate as a “digital driver’s license” for an Internet address. It states with which company the site is associated, along with some basic contact information about the site owner or administrator.
The digital certificate is cryptographically signed by its owner and is difficult for anyone else to forge. For sites involved in e-commerce or in any other business transaction in which authentication of identity is important, a certificate can be purchased from a well-known certificate authority (CA) such as VeriSign or Thawte. If your server certificate is self-signed, you must install it in the Application Server keystore file (keystore.jks). If your client certificate is self-signed, you should install it in the Application Server truststore file (cacerts.jks).
Sometimes authentication is not really a concern. For example, an administrator might simply want to ensure that data being transmitted and received by the server is private and cannot be snooped by anyone eavesdropping on the connection. In such cases, you can save the time and expense involved in obtaining a CA certificate and simply use a self-signed certificate.
SSL uses public key cryptography, which is based on key pairs. Key pairs contain one public key and one private key. If data is encrypted with one key, it can be decrypted only with the other key of the pair. This property is fundamental to establishing trust and privacy in transactions. For example, using SSL, the server computes a value and encrypts the value using its private key. The encrypted value is called a digital signature. The client decrypts the encrypted value using the server’s public key and compares the value to its own computed value. If the two values match, the client can trust that the signature is authentic, because only the private key could have been used to produce such a signature.
Digital certificates are used with the HTTPS protocol to authenticate web clients. The HTTPS service of most web servers will not run unless a digital certificate has been installed. Use the procedure outlined in the next section, Creating a Server Certificate, to set up a digital certificate that can be used by your application or web server to enable SSL.
One tool that can be used to set up a digital certificate is keytool, a key and certificate management utility that ships with the Java SE SDK. It enables users to administer their own public/private key pairs and associated certificates for use in self-authentication (where the user authenticates himself or herself to other users or services) or data integrity and authentication services, using digital signatures. It also allows users to cache the public keys (in the form of certificates) of their communicating peers. For a better understanding of keytool and public key cryptography, read the keytool documentation at http://java.sun.com/javase/6/docs/technotes/tools/solaris/keytool.html.
A server certificate has already been created for the Application Server. The certificate can be found in the domain-dir/config/ directory. The server certificate is in keystore.jks. The cacerts.jks file contains all the trusted certificates, including client certificates.
If necessary, you can use keytool to generate certificates. The keytool utility stores the keys and certificates in a file termed a keystore, a repository of certificates used for identifying a client or a server. Typically, a keystore is a file that contains one client or one server’s identity. It protects private keys by using a password.
If you don’t specify a directory when specifying the keystore file name, the keystores are created in the directory from which the keytool command is run. This can be the directory where the application resides, or it can be a directory common to many applications.
To create a server certificate, follow these steps:
Create the keystore.
Export the certificate from the keystore.
Sign the certificate.
Import the certificate into a truststore: a repository of certificates used for verifying the certificates. A truststore typically contains more than one certificate.
Run keytool to generate the server keystore, keystore.jks. This step uses the alias server-alias to generate a new public/private key pair and wrap the public key into a self-signed certificate inside keystore.jks. The key pair is generated using an algorithm of type RSA, with a default password of changeit. For more information on keytool options, see its online help at http://java.sun.com/javase/6/docs/technotes/tools/solaris/keytool.html.
RSA is public-key encryption technology developed by RSA Data Security, Inc. The acronym stands for Rivest, Shamir, and Adelman, the inventors of the technology.
From the directory in which you want to create the keystore, run keytool with the following parameters.
Generate the server certificate. (Type the keytool command all on one line.)
java-home\bin\keytool -genkey -alias server-alias-keyalg RSA -keypass changeit -storepass changeit -keystore keystore.jks
When you press Enter, keytool prompts you to enter the server name, organizational unit, organization, locality, state, and country code.
You must enter the server name in response to keytool’s first prompt, in which it asks for first and last names. For testing purposes, this can be localhost.
When you run the example applications, the host specified in the keystore must match the host identified in the javaee.server.name property specified in the file tut-install/javaeetutorial5/examples/bp-project/build.properties.
Export the generated server certificate in keystore.jks into the file server.cer. (Type the keytool all on one line.)
java-home\bin\keytool -export -alias server-alias -storepass changeit -file server.cer -keystore keystore.jks
If you want to have the certificate signed by a CA, read Signing Digital Certificates for more information.
To create the truststore file cacerts.jks and add the server certificate to the truststore, run keytool from the directory where you created the keystore and server certificate. Use the following parameters:
java-home\bin\keytool -import -v -trustcacerts -alias server-alias -file server.cer -keystore cacerts.jks -keypass changeit -storepass changeit
Information on the certificate, such as that shown next, will display.
% keytool -import -v -trustcacerts -alias server-alias -file server.cer -keystore cacerts.jks -keypass changeit -storepass changeit Owner: CN=localhost, OU=Sun Micro, O=Docs, L=Santa Clara, ST=CA, C=USIssuer: CN=localhost, OU=Sun Micro, O=Docs, L=Santa Clara, ST=CA, C=USSerial number: 3e932169Valid from: Tue Apr 08Certificate fingerprints:MD5: 52:9F:49:68:ED:78:6F:39:87:F3:98:B3:6A:6B:0F:90 SHA1: EE:2E:2A:A6:9E:03:9A:3A:1C:17:4A:28:5E:97:20:78:3F: Trust this certificate? [no]:
Enter yes, and then press the Enter or Return key. The following information displays:
Certificate was added to keystore[Saving cacerts.jks]
After you’ve created a digital certificate, you will want to have it signed by its owner. After the digital certificate has been cryptographically signed by its owner, it is difficult for anyone else to forge. For sites involved in e-commerce or any other business transaction in which authentication of identity is important, a certificate can be purchased from a well-known certificate authority such as VeriSign or Thawte.
As mentioned earlier, if authentication is not really a concern, you can save the time and expense involved in obtaining a CA certificate and simply use the self-signed certificate.
This example assumes that the keystore is named keystore.jks, the certificate file is server.cer, and the CA file is cacerts.jks. To get your certificate digitally signed by a CA:
keytool -certreq -alias server-alias -keyalg RSA -file csr-filename -keystore cacerts.jks
Send the contents of the csr-filename for signing.
If you are using Verisign CA, go to http://digitalid.verisign.com/. Verisign will send the signed certificate in email. Store this certificate in a file.
Follow the steps in Creating a Server Certificate, to create your own server certificate, have it signed by a CA, and import the certificate into keystore.jks.
Make sure that when you create the certificate, you follow these rules:
When you create the server certificate, keytool prompts you to enter your first and last name. In response to this prompt, you must enter the name of your server. For testing purposes, this can be localhost.
The server/host specified in the keystore must match the host identified in the javaee.server.name property specified in the tut-install/javaeetutorial5/examples/bp-project/build.properties file for running the example applications.
Your key/certificate password in keystore.jks should match the password of your keystore, keystore.jks. This is a bug. If there is a mismatch, the Java SDK cannot read the certificate and you get a “tampered” message.
If you want to replace the existing keystore.jks, you must either change your keystore’s password to the default password (changeit) or change the default password to your keystore’s password.
To specify that the Application Server should use the new keystore for authentication and authorization decisions, you must set the JVM options for the Application Server so that they recognize the new keystore. To use a different keystore than the one provided for development purposes, follow these steps.
Start the Application Server if you haven’t already done so. Information on starting the Application Server can be found in Starting and Stopping the Application Server.
Start the Admin Console. Information on starting the Admin Console can be found in Starting the Admin Console.
Select Application Server in the Admin Console tree.
Select the JVM Settings tab.
Select the JVM Options tab.
Change the following JVM options so that they point to the location and name of the new keystore. There current settings are shown below:
If you’ve changed the keystore password from its default value, you need to add the password option as well:
Log out of the Admin Console and restart the Application Server.
To check the contents of a keystore that contains a certificate with an alias server-alias, use this command:
keytool -list -keystore keystore.jks -alias server-alias -v
To check the contents of the cacerts file, use this command:
keytool -list -keystore cacerts.jks