The HTTPS Connector

The HTTPS connector provides data encryption and certificate-based security through a Secure Socket Layer (SSL). An implementation of secure sockets is only available for the Java 2 platform. However, secure sockets are not part of the Java 2 SDK (Software Development Kit), and their libraries must be installed separately.

The Java Secure Socket Extension (JSSE) 1.0 provides a compatible implementation of secure sockets for the Java 2 platform. For optimal performance of the HTTPS connector, it is recommended that you use the Java 2 SDK, Standard Edition, v1.2.2, and the JSSE 1.01.

The web site for the JSSE is http://java.sun.com/products/jsse. This site provides links for downloading the software and the documentation. For further information and details regarding the use of the secure sockets, please refer to the JSSE documentation.

The HTTPS connector exposes the same interfaces as all other connectors and has exactly the same behavior. The development of management application which relies on the HTTPS connector is no different from that of any other Java Dynamic Management manager. See "Connector Clients" for details about programming with the RemoteMBeanServer API.

Where the HTTPS connector differs is that it relies on the security mechanisms built into the Java language and extended by JSSE. In order to use these libraries and communicate securely, you must configure your application environment to meet all security requirement. The cost of security is establishing all of the structures that guarantee the trust between two communicating parties.

This section covers the steps that are required to establish a secure connection between your agent and manager applications. These instructions do not guarantee total security, they just explain the programmatic steps needed to ensure data security between two distant Java applications.

These steps assume that each of your manager and agent applications runs on a separate machine, and that each machine has its own installation of the Java SDK (not a shared network installation).

1. Install All Software

You should install both the Java 2 SDK, Standard Edition, v1.2.2, and the JSSE 1.01 products on all hosts that will use the HTTPS connector client or connector server components.

In this procedure, the directories where you have installed these products are named JAVAhome and JSSEhome, respectively. These names are used on all hosts where the products are installed, even though their value is specific to each host.

2. Extend Your Java Runtime Libraries

For each of your SDK/JSSE installations, copy the three jar files (jsse.jar, jcert.jar, and jnet.jar) of the JSSE reference implementation into the extensions directory of your Java runtime environment.

For example, on the Solaris platform you would type:

$ cp JSSEhome/lib/jsse.jar JAVAhome/jre/lib/ext/
$ cp JSSEhome/lib/jcert.jar JAVAhome/jre/lib/ext/
$ cp JSSEhome/lib/jnet.jar JAVAhome/jre/lib/ext/

Or you could add these jar files to your environment's classpath, as follows (for the Korn shell):

$ export CLASSPATH=${CLASSPATH}:JSSEhome/lib/jsse.jar:\ 
JSSEhome/lib/jcert.jar:JSSEhome/lib/jnet.jar

3. Designate your Security Provider

The JSSE follows the same "provider" architecture found in the Java Cryptography Architecture (JCA) which is provided in the Java 2 platform as the Java Cryptography Extension (JCE). In order to use JSSE you must install this provider either statically or dynamically. Again, you must do this for all of your SDK/JSSE installations.

To install the provider statically you must edit the security properties file (JAVAhome/lib/security/java.security). Edit this file as follows, the boldface text is the part you must add:

security.provider.1=sun.security.provider.Sun

security.provider.2=com.sun.net.ssl.internal.ssl.Provider

The first line of this file depends upon your SDK platform and should not be changed.

To install the provider dynamically in your Java application, you should call the addProvider method of the java.security.Security class. The line in your source code would look like this:

Security.addProvider( new com.sun.net.ssl.internal.ssl.Provider() );

4. Generate Public and Private Keys

This step must be repeated on all agent and manager host machines.

Generate a key pair (a public key and associated private key). Wrap the public key into an X.509 v1 self-signed certificate, which is stored as a single-element certificate chain. This certificate chain and the private key are stored in a new keystore entry identified by alias.

In the following command, the -dname parameters designates the X.500 Distinguished Name for the host where you are generating the certificates. The commonName field must be the machine's hostname.

$ keytool -genkey -alias alias -keyalg RSA -keysize 1024 -sigalg MD5withRSA
          -dname "CN=commonName, OU=orgUnit, O=org, L=location, S=state, C=country"
          -keypass passPhrase -storetype jks -keystore yourHome/.keystore
          -storepass passPhrase

5. Export a Local Certificate

This step must be repeated on all agent and manager host machines.

Read the certificate that is associated with your alias from the keystore, and store it in a hostCertFile:

$ keytool -export -alias alias -file hostCertFile -storetype jks
          -keystore yourHome/.keystore -storepass passPhrase -rfc

When you are done with this step you will have a certificate for each of your host machines.

6. Import all Remote Certificates

This step must be repeated on both the agent and manager host machines, for all pairs of agent-managers in your management architecture.

In this step, agent and manager pairs must exchange their certificates. The manager should import the agent's hostCertFile and the agent should import the manager's hostCertFile. If a manager has two agents, it will import two certificates, and each agent will import a copy of the manager's certificate.

Import the certificate into the file containing the trusted Certificate Authorities (CA) certificates. This will add our self-signed certificate as a trusted CA certificate to the cacerts file so that the server and the client will be able to authenticate each other.

$ keytool -import -alias alias -file hostCertFile -noprompt -trustcacerts
          -storetype jks -keystore JAVAhome/jre/lib/security/cacerts
          -storepass changeit

This command modifies the JAVAhome/jre/lib/security/cacerts which will affect all applications running on that installation. If you do not want to modify this file, you could create a file named jssecacerts and use it instead. The default location of this file is either JAVAhome/lib/security/jssecacerts or if that does not exist, then JAVAhome/lib/security/cacerts.

7. Run Your Java Dynamic Management Agent

Launch your agent applications with the following properties:

$ java -Djavax.net.ssl.keyStore=yourHome/.keystore
       -Djavax.net.ssl.keyStoreType=jks
       -Djavax.net.ssl.keyStorePassword=passPhrase
       AgentClass

If you are using the notification push mechanism, add the following property definition to the above command line:

-Djava.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol

8. Run Your Management Application

Launch your management applications with the following properties:

$ java -Djavax.net.ssl.keyStore=yourHome/.keystore
       -Djavax.net.ssl.keyStoreType=jks
       -Djavax.net.ssl.keyStorePassword=passPhrase
       -Djava.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol
       ManagerClass