Java Dynamic Management Kit 5.0 Tutorial

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 Software Development Kit (SDK), and their libraries must be installed separately.

The Java Secure Socket Extension (JSSE) provides a compatible implementation of secure sockets for the Java 2 platform.

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, 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 a management application that relies on the HTTPS connector is no different from that of any other Java dynamic 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 requirements. 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 remote Java applications.

Before performing these steps, run each of your manager and agent applications on a separate host, and ensure that each host has its own installation of the Java SDK (not a shared network installation).

To Establish a Secure HTTPS Connection

Install the 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 values are specific to each host.

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, 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 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

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, edit the security properties file (JAVAhome/lib/security/java.security). 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, call the addProvider method of the java.security.Security class as follows:
```
Security.addProvider( new com.sun.net.ssl.internal.ssl.Provider() );
```

Generate public and private keys.

Repeat this step on all agent and manager hosts.

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 host name.

$ 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

Export a local certificate

Repeat this step on all agent and manager hosts.

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 hosts.

Import all remote certificates

Repeat this step on both the agent and manager hosts for all pairs of agent-managers in your management architecture.

In this step, agent and manager pairs must exchange their certificates. The manager imports the agent's hostCertFile and the agent imports 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 that will affect all applications running on that installation. If you do not want to modify this file, you can 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.

Run your Java dynamic management agent

Start 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

Run your management application

Start 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