TLS in Etch

The purpose of this document is to provide a step by step description on how to enable SSL in etch

Certificate Management

Certificates are required to enable encryption of data, maintaining its integrity and optionally providing authentication.

Certificate Management for Java Server and Java Client

Creating Server Certificate using KeyTool (Java)

(Before running keytool make sure java is installed on your machine and is defined in PATH enviorment variable)

This certificate will be used on the machine where the listener is running.

keytool -genkey -alias myalias -validity 365 -keystore keys/my.keystore

Enter keystore password: abc123
What is your first and last name?
Unknown: Etch
What is the name of your organizational unit?
Unknown: CUAE
What is the name of your organization?
Unknown: Cisco
What is the name of your City or Locality?
Unknown: Austin
What is the name of your State or Province?
Unknown: TX
What is the two-letter country code for this unit?
Unknown: US
Is CN=Etch, OU=CUAE, O=Cisco, L=Austin, ST=TX, C=US correct?
y

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

It is preferable that you type in the same password for myalias as you did for keystore.
-keystore option allows you to specify the keystore you want to use. In the above example my.keystore is created in the (current directory)/keys

Importing the Certificate into a Client Machine (Java)

This section is only required if you want to authenticate the server. If authenticate is not required, please skip this section

In the last section we created a certificate for the machine running the listener. Now the certificate has to be imported into the client machine

First export the certificate created in previous section to a file

keytool -export -keystore keys/my.keystore -alias myalias -file server.cer

Now copy this certificate to your client machine and import it to a truststore

keytool -import -keystore jssecacerts -alias myalias -file server.cer

-keystore in this context is the truststore

Certificate Management for C# Server and C# Client

Creating a server certificate using makecert (C#)

This certificate will be used on the machine where the listener is running.

*makecert -pe -n "CN=Test And Dev Root Authority" -ss my -sr LocalMachine -a sha1 -sky signature -r "Test And Dev Root Authority.cer"*

Handy Hint
You are not required to install Visual Studio on to the CUAE server to get the makecert executable. You should be able to copy the file from a client that has Visual Studio installed and place it on the CUAE server to run the command above. The file can be found in the folloowing directory for a Visual Studio install:
C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin\makecert

The above command creates a Root certificate. All your personal certificates will extend from this root certificate. So lets create a personal certificate now.
makecert -pe -n "CN=gsandhir-wxp02" -ss my -sr LocalMachine -a sha1 -sky exchange -in "Test And Dev Root Authority" -is my -ir LocalMachine -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 gsandhir-wxp02.cer

If you run up a Certificates MMC at this point, you will be able to see this. However, by default, the Certificates snap-in isn't available as a short cut. Hence, use the following steps:

  • start/run/mmc
  • File/Add-Remove Snap-In
  • Click Add
  • Select Certificates and click Add
  • Select Computer Account and hit Next
  • Select Local Computer
  • Click Finish
  • Click Close
  • Click OK

If you expand the console out to Personal/Certificates, you will see your newly created certificates.

In the certificates snap-in, right-click the "Test and Dev Root Authority" certificate and copy it to the "Trusted Root Certification Authorities" node. Once done, if you expand this node, and then select certificates your newly created root cert should be present.

Importing the Certificate created using makecert into a Client Machine (C#)

This section is only required if you want to authenticate the server. If authentication is not required, please skip this section

First thing we need to do is export the certificate made in the previous step into a file

Run MMC

  • Add the Certificate snap-in as described in the previous section
  • Expand Trusted Root Certification Authorities\Certificates and select the Test And Dev Root Authority we created in the last section
  • Right click on the certificate and select All Tasks->Export
  • Certificate Export wizard will be launched. Click next
  • Make sure you select "No, do not export the private key".
  • Keep the default for the Export File Format (DER encoded binary X509)
  • Type in any file name and click finish

Now we will copy this file into the client machine and then import it into that machine's certificate store

  • Run MMC
  • Add the Certificate snap-in as described in the previous section
  • Select Certificates under Trusted Root Certification Authorities and right click on it and chose All Tasks->Import
  • Specify the file name as the certificate we copied from server.
  • Chose all the default options and click finish

Certificate Management for C# Server and Java Client

Creating a server certificate using makecert (C#)

This certificate will be used on the machine where the listener is running.

*makecert -pe -n "CN=TestRoot" -ss my -sr LocalMachine -a sha1 -sky signature -r "TestRoot.cer"*

Handy Hint
You are not required to install Visual Studio on to the CUAE server to get the makecert executable. You should be able to copy the file from a client that has Visual Studio installed and place it on the CUAE server to run the command above. The file can be found in the folloowing directory for a Visual Studio install:
C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin\makecert

The above command creates a Root certificate. All your personal certificates will extend from this root certificate. So lets create a personal certificate now.
makecert -pe -n "CN=Test" -ss my -sr LocalMachine -a sha1 -sky exchange -in "TestRoot" -is my -ir LocalMachine -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 Test.cer

If you run up a Certificates MMC at this point, you will be able to see this. However, by default, the Certificates snap-in isn't available as a short cut. Hence, use the following steps:

  • start/run/mmc
  • File/Add-Remove Snap-In
  • Click Add
  • Select Certificates and click Add
  • Select Computer Account and hit Next
  • Select Local Computer
  • Click Finish
  • Click Close
  • Click OK

If you expand the console out to Personal/Certificates, you will see your newly created certificates.

In the certificates snap-in, right-click the "TestRoot" certificate and copy it to the "Trusted Root Certification Authorities" node. Once done, if you expand this node, and then select certificates your newly created root cert should be present.

Importing the certificate to Java Client

This section is only required if you want to authenticate the server. If authentication is not required, please skip this section

First thing we need to do is export the certificate made in the previous step into a file

Run MMC

  • Add the Certificate snap-in as described in the previous section
  • Expand Trusted Root Certification Authorities\Certificates and select the TestRoot certificate we created in the last section
  • Right click on the certificate and select All Tasks->Export
  • Certificate Export wizard will be launched. Click next
  • Make sure you select "No, do not export the private key".
  • Keep the default for the Export File Format (DER encoded binary X509)
  • Type in any file name and click finish (for example server.cer)

Now copy this certificate to your client machine and import it to a truststore

keytool -import -keystore jssecacerts -alias myalias -file server.cer

-keystore in this context is the truststore

Changes to the Listener

Java Listener

VM Arguments

Before we run the listener we need to specify the keystore, keystore password through the VM arguments

For example

-Djavax.net.ssl.keyStore=C:\MyKeyTools\keys\my.keystore
-Djavax.net.ssl.keyStorePassword=abc123
-Djavax.net.ssl.keyPairPassword=xyz123 ( optional )

-Djavax.net.ssl.keyStore corresponds to the keystore created while using "keytools -genkey" command (see Creating Server Certificate using KeyTool section)
-Djavax.net.ssl.keyStorePassword=abc123 corresponds to the keystore password used
-Djavax.net.ssl.keyPairPassword=xyz123 is only REQUIRED if the keypair password is different than the keystore password

Changes to Code

The only change is to use tls as the protocol instead of tcp.

Hence instead on specifying uri as

String uri = "tcp://0.0.0.0:4001";

we will now specify it as

String uri = "tls://0.0.0.0:4001";

C# Listener

The only change is in the URI

Before

string uri = "tcp://0.0.0.0:4001";

After TLS

string uri = "tls://localhost:4001?TlsConnection.certName=gsandhir-wxp02";

Please remember in order to run in secure mode the certificate name has to be specified on the uri. The name of the certificate corresponds to the CN argument we specified in makecert (see section "Creating a server certificate using makecert (C#)". The example in that section created a certificate with -n "CN=gsandhir-wxp02", hence in the uri we pass in the certName as gsandhir-wxp02.

Changes to Client

Java Client

The client can chose whether it wants to authenticate the server or not

Changes when authentication is required

Before we run the client we need to pass in the location of the truststore as a VM argument

-Djavax.net.ssl.trustStore=C:\MyKeyTools\deftruststore

-Djavax.net.ssl.trustStore - Corresponds to the keystore location where server certificate was imported (see section "Importing the Certificate into a Client Machine (Java)")

Change the uri in the code to String uri = "tls://localhost:4001";

Changes when authentication is not required

In this case we do not need to specify the truststore location.

However in the uri we must specify explicitly that authentication should be switched off

String uri = "tls://localhost:4001?TlsConnection.authReqd=false";

C# Client

Similar to Java, client can chose whether it wants to authenticate the server or not

Changes when authentication is required

The uri in the client code will appear as following

string uri = "tls://localhost:4001?TlsConnection.certName=gsandhir-wxp02";

As mentioned in the listener C# section, the certificate name must correspond to the CN name specified when creating a certificate.

Changes when authentication is not required

The uri in the client code will appear as following

String uri = "tls://localhost:4001?TlsConnection.authReqd=false";