9.6.3 Using SSL for Communication through HTTP Connector

9.6.3.1 SSL- An Overview

9.6.3.2 Enabling SSL

9.6.3.3 Server Authentication

9.6.3.4 Client Authentication

9.6.3.1 SSL- An Overview

SSL (Secure Sockets Layer) protocol is being used universally for authenticated and encrypted communication between clients and servers. In general, SSL is used when:

1. You need to prove to others who you are

2. You need to make sure that other people are legitimate

SSL allows the SSL-enabled server to authenticate itself to an SSL-enabled client. This also allows the client to authenticate itself to the server. However, this step is optional. Next it enables both machines to establish an encrypted connection. The steps involved in achieving secure communication between server and client using SSL are:

1. Server Authentication: Client can check the server's authenticity using public key cryptography technique, i.e., check if the server's certificate and public key are valid and have been issued by a Certificate Authority (CA) listed in the client's list of trusted CAs.

2. Client Authentication: This is optional. Here, the server confirms the client's identity by checking the validity of the client's certificate and private key and whether they were issued by a certificate authority listed in the server's list of trusted CAs.

3. Establishing encrypted SSL connection: After the server and client authenticate each other, they negotiate a cipher suite which specifies the algorithm to be used for encrypting the data. Now, an encrypted connection is established between both and all data are encrypted when being sent and decrypted when received on the other side.

This whole process is referred to as the SSL Handshake. An SSL session always begins with this SSL handshake.

9.6.3.2 Enabling SSL Support

When you require a secure (authenticated and encrypted) connection between the server and the client, you can opt for SSL. AdventNet HTTP Connector supports SSL.  Secure Sockets Layer has been implemented on both the server and the client side of the HTTP Connector. Therefore, an HTTPS connection can be established between the server and the client.

SSL can be enabled for the HTTP Connector either from the JMX Compiler user interface while generating the agent or by directly adding the required code to the agent main file.

9.6.3.2.1 From UI

Follow the steps given below to enable SSL support from the JMX Compiler UI: 

1. Select Project->Settings menu option. Settings dialog appears.

2. Select Adaptors->HTTP->SSL option from the tree in the right frame of the Settings dialog.

3. Enable the SSL Support option.

On generating code for the agent, code is generated to have SSL support for the HTTP connector. The httpconnector.xml  file (present in the <Agent Toolkit Home>/jmxprojects/<projectname>/agent/bin/connector/conf  directory) contains the default  configuration parameters. 

For SSL support, the corresponding packages related to SSL can be downloaded from Sun Microsystems Inc,

( http://java.sun.com/products/jsse/ ). After downloading the packages, the jars (jsse.jar, jnet.jar, jcert.jar) from the packages must be set in the classpath of the agent and setenv.bat. The setenv.bat will be available under the <Agent Toolkit Home>/bin directory and this will be used by MBean Browser for setting the tools classpath.

Warning: If  keystore is not present in the corresponding directory , a file not found exception will be thrown while starting the agent.

9.6.3.3 Server Authentication

For communicating through SSL, server authentication is mandatory. Here, the client tries to confirm the identity of the server based on the server's certificate, i.e., the server gets authenticated by the client.  

To accomplish this, on receiving a request from the client, the server sends its certificate to the client. This certificate contains information such as: server's public key, certificate's serial number, certificate's validity period, server's distinguished  name, issuer's distinguished  name, and issuer's digital signature (a message signed using the issuer's private key).  

The client, on receiving this certificate, authenticates the server through the following steps:

• Checks if the current date and time are within the certificate's validity period.

• Checks if the CA (certificate authority/ issuer) is present in the client's list of trusted CAs.

• Validates the issuer's digital signature, present in the certificate, using the public key of the CA.

• Checks if the Server's distinguished name is same as the distinguished name specified in the certificate.

For performing the above authentication, the server must have a Public Certificate and Keystore containing the key and the client must have a list of trusted CAs.

9.6.3.3.1 Configuring Server Authentication Parameters

As server authentication is mandatory for communication through SSL, server authentication will occur if SSL is enabled. The previous section explains the different methods of enabling SSL Support for the HTTP Connector. SSL support was enabled with the

default parameters present in the httpconnector.xml file.

This file contains the following information corresponding to server authentication:

• Keystore: A keystore is a database of key material. It contains the Public-Private key pair. This Key material is used for a variety of purposes including authentication and ensuring data integrity. A sample keystore adventnetkey has been bundled with the product. It is available in <Agent Toolkit Home>/etc directory.

• Password: This is the password for the keystore.  The password for the keystore "adventnetkey" is "adventnet".

You can generate your own keystore and use it instead of the default keystore (adventnetkey). Then, the default parameters have to be changed while enabling SSL support. This can be done either from the JMX Compiler user interface or by directly editing the

httpconnector.xml file.  

9.6.3.3.1.1 From UI

Follow the steps given below to configure the parameters for server authentication using the JMX Compiler user interface: 

• Select Project->Settings menu option. Settings dialog appears.

• Select Adaptors->HTTP->SSL option from the tree in the left frame of Settings dialog.

• Ensure SSL Support is enabled.

• Select the SSL tab and enter the Keystore(In case you are using a keystore other than the sample adventnetkey, use the Browse button to specify the location of the keystore).

• Enter the Password corresponding to the keystore specified. 

When code is generated, the httpconnector.xml  file is created with the values specified.

9.6.3.3.1.2 Editing the httpconnector.xml file

These parameters can also be changed directly by editing the configuration file, httpconnector.xml. This file contains the following details:

<Parameter name="keystore" value="etc/adventnetkey" />

  <Parameter name="keypass" value="adventnet" />

This file is read when the agent is started. Therefore, the changes made in this file are reflected only when the agent is restarted.

This file also contains the details regarding Client Authentication. By default, Client Authentication is set "false".  Configuring the details corresponding to client authentication is dealt in the next section, "Enabling Client Authentication".

9.6.3.3.2 Generating Your Own Keystore

You can generate your own keystore and use it instead of the sample keystore (adventnetkey) bundled with the Toolkit. This can be done using the keytool present in the bin directory of Java Development Kit (use jdk1.2.2 or a higher version).  

Follow the steps given below to generate your own keystore:  

1. Set PATH to jdk's bin directory.

2. Use the command: (general syntax is given below)

keytool -genkey [-v] [-alias <alias>] [-keyalg <keyalg>] [-keysize <keysize>] [-sigalg

<sigalg>] [-dname <dname>] [-validity <valDays>] [-keypass <keypass>] [-keystore

<keystore>] [-storepass <storepass>] [-storetype <storetype>] [-provider <provider_class_name>]

where,

The default keystore (adventnetkey) bundled with this toolkit was created using the following command:  keytool -genkey -v -alias localhost -keyalg RSA -sigalg MD5withRSA -keystore adventnetkey -keypass adventnet -storepass adventnet  -storetype JKS -validity 180

Executing this command prompts you to answer the following questions:

What is your first and last name? 

[Unknown]:  localhost 

What is the name of your organizational unit? 

[Unknown]:  agent 

What is the name of your organization? 

[Unknown]:  AdventNet 

What is the name of your City or Locality? 

[Unknown]:  Chennai 

What is the name of your State or Province? 

[Unknown]:  TamilNadu 

What is the two-letter country code for this unit? 

[Unknown]:  in 

Is <CN=localhost, OU=agent, O=AdventNet, L=Chennai, ST=TamilNadu, C=in> correct? 

[no]:  y 

The first five questions shown above will not be prompted if the corresponding values are mentioned using the -dname (distinguished name) tag. The question "What is your first name and last name?" requires to be answered with the machine name where the

agent will be deployed or "localhost". If this question is not answered, the key becomes invalid.

Once you enter all the values and confirm the values entered, the key is generated. The key can also be executed with the least number options as:  

keytool -genkey -alias <alias name> -keyalg RSA -keystore <keystore name>

If you use this command, you will be prompted to enter the store password and the keypassword.

Once the keystore is generated, it has to be placed in the <projectdir>/agent/bin/etc directory. For the agent to use this keystore, its details must be added to the HtmlAdaptorSSLConf.xml file as explained in the previous section: Configuring Server Authentication Parameters.

9.6.3.3.3 Generating a Public Certificate for Your Keystore

The keystore basically contains a private key and a certificate chain. When a new keystore is created, keystore has a self-signed certificate containing the corresponding public-key. Later, after a Certificate Signing Request (CSR) has been generated and sent to a Certification Authority (CA), the response from the CA is a chain of certificates.

This response has to be imported into the keystore, where the self-signed certificate is replaced by the chain of certificates. The certificate (reply) issued by the CA after authenticating your public key is at the bottom of the chain. The next certificate in the chain is one that authenticates the CA's public key.

Importing the chain of certificates into the keystore is similar to importing a public certificate into the trusted CA list and is done using the -import tag. For more information on the -import tag, please refer to the next section  Importing Client's Certificate into Your Trusted CA List.

The next step involves generating the public certificate for the key entry and adding it to the trusted CA list of the client. Follow the steps given to generate a public certificate for the keystore you have generated:

1. Set PATH to jdk's bin directory. (use jdk1.2.2 and above). 

2. Use the command -export (general syntax is given below):
   
   keytool -export [-v] [-rfc] [-alias <alias>] [-file <cert_file>] [-keystore <keystore>]
   [-storepass <storepass>] [-storetype <storetype>] [-provider <provider_class_name>]

The export command basically exports the certificate at the bottom of the certificate chain to a file. In the above command,

Upon successful execution of the command, the following message is displayed:  Certificate stored in file <your cert file name>.

The certificate adventnetcert bundled with the Agent Toolkit (present in the <Agent Toolkit Home>/etc directory) was created using the command:

keytool -export -alias localhost -file adventnetcert -keystore adventnetkey -storepass adventnet -storetype JKS

9.6.3.4 Client Authentication

Client Authentication is not mandatory, but the server can be configured to require client authentication. Here, the client presents the server with the following information:

• A certificate containing the client's public key.

• A digitally signed random data. The random data is generated during the handshake and is known only to the server and the client. The client encrypts this data using its private key (digitally signs the data) and this can be decrypted only using the client's public key.

The server on receiving this information, performs the following checks:

• Is the user's digital signature validated by the user's public key?

• Is the current date and time within the validity period of the certificate?

• Is the CA (certificate authority/ issuer) present in the client's list of trusted CAs?

• Is the issuer's digital signature, present in the certificate, validated using the public key of the CA?

For performing client authentication, the server must be configured to require client authentication. In addition to this, the CA who issued the client's certificate must be included in the trusted CA list (trust store) of the server.

9.6.3.4.1 Enabling Client Authentication

Client authentication can be enabled either from the JMX Compiler user interface while generating code for the agent or by directly editing the HtmlAdaptorSSLConf.xml file. This file contains the following information pertaining to client authentication:

• Client Authentication: A boolean flag that indicates if client authentication is enabled for the agent. By default this value is false.

• Truststore: It is the list of trusted CAs. It is also a keystore, containing the certificates of the trusted CAs. A sample trust store cacerts is bundled with Agent Toolkit. It is present in the <Agent Toolkit Home>/etc directory and will be copied to the <projectdir>/agent/bin/etc directory (if SSL is enabled) while generating code for the agent.

• Password: This is the password for accessing the trust store. The password for the truststore cacerts is "changeit".

• Type: There are various types of  trust stores available including "PKCS12" and Sun's "JKS." The sample trust store cacerts is of type JKS.

• Provider: Providers are essentially packages that implement cryptographic algorithms. In case you are unable to find a cryptographic provider that implements the algorithms you want to use, it is possible to write your own provider. The provider for the sample keystore adventnetkey is SunJSSE.

• Manager Algorithm: This indicates the algorithm of the keystore manager. The manager algorithm of the sample trust store cacerts is SunX509.

In case you want to use a trusted CA list other than the sample cacerts provided, the corresponding parameters must be specified in this configuration file.

9.6.3.4.1.1 From UI

Client authentication can be enabled from the JMX compiler user interface by following the steps given below: 

1. Select Project->Settings menu option. Settings dialog appears.

2. Select Adaptors->HTTP->SSL option from the tree in the left frame of Settings dialog.

3. Ensure SSL Support is enabled.

4. Enter the details for SSL tab.

5. Select the Trusted Clients tab and enable Client Authentication.

Now, on generating code for the agent, the httpconnector.xml file is created with the specified values.

9.6.3.4.1.2 Editing the httpconnector.xml  file

Client authentication can also be enabled directly by editing the configuration file. In addition to the details required for server authentication, the configuration file also contains the following details pertaining to client authentication:

<Parameter name="clientAuth" value="false" />

By default, the property clientAuth is set "false". To enable client authentication from the file, this has to be changed to "True". Here, the other parameters are specified based on the sample trust store cacerts. In case you want to use some other trusted CA list, its details have to be specified in this file.

This file is read when the agent is started. Therefore, if  changes made are in this file they are reflected only when the agent is restarted.

9.6.3.4.2 Importing Client's Certificate into Your Trusted CA List

For the client to be authenticated by the server (HTTP Connector of Multi-Protocol agent), the client's certificate must by issued by a CA (certificate authority) included in the server's list of trusted CAs.

If the client's certificate is not present in the server's trusted CA list, then Client Authentication fails and the SSL connection is not established. Therefore, it is imperative that the client's certificate be added to the trusted CA list.  

By default,  jdk gives a trusted CA list (cacerts) which is similar to a key store and contains a list of trusted public certificates.  Now the client's public certificate can also be added (imported) to this list. This is done using the -import tag of Keytool.  Follow the steps given below to import the client's public certificate:

• Copy the cacerts under jdkx.x/jre/lib/security directory to the working directory. 

• Set PATH to jdk's bin directory. (use jdk1.2.2 and above). 

• Use the command -import (general syntax is given below):
  keytool -import [-v] [-noprompt] [-trustcacerts] [-alias <alias>] [-file <cert_file>] [-keypass <keypass>] [-keystore <keystore>] [-storepass <storepass>] [-storetype <storetype>] [-provider <provider_class_name>]

where,

On executing the command, you are prompted to confirm the inputs given (only if -noprompt is not used). Once the inputs are confirmed, the following message is displayed:

Certificate was added to keystore

[Saving cacerts]

Note: The import command is also used to import the Certificate (given by the CA in response to your CRS) into the keystore.