Etch Bridge Transport Layer Security#

With TLS enabled on the Etch Bridge, Etch applications and plugins must connect to Etch Bridge using TLS. By default, encryption is ON but authentication is OFF.

Overview#

Certificates are used to enable encryption of data, maintaining its integrity and optionally providing authentication. By default, the Platform Services installer creates the TLS certificate used for most encryption and authentication. However, for some plugin authentication you will need to create an additional certificate manually.

Tip: For applications and plugins to run properly, developers must complete the additional steps described in this section.

Enable TLS in Applications//#

Enable Client Applications to Use TLS Encryption#

For your applications to communicate properly with the Etch Bridge when TLS is enabled, follow these procedures:

1. In the code where you register your application with the server, you must modify the connection URI. In the examples in this wiki, this is typically done in the Main<ProjectName>Client file in each application /src directory.

2. Locate the string uri parameter. This is the value by default:

// TODO Change to correct URI

String uri = "tcp://appserver_ipaddress:9000";}}}

3. Modify the URI to support TLS. The following sample shows the correct parameter to support encryption, but not authentication.

// TODO Change to correct URI

String uri = "tls://appserver_ipaddress:9000?TlsConnection.authReqd=false";}}}

Note: The connection URI parameter can contain many parameters and filters. For more information, see Etch Connection URI.

Enable Authentication#

Follow the instructions based on the language you used to build your application.

Java Applications//#

1. Copy the certificate created by the Platform Services to your client machine. The Platform Services installer saves it here: C:\Program Files\Cisco Systems\Unified Application Environment\AppServer\Rootet.cer.

2. Use keytool to import the rootet.cer to a truststore for the client.

keytool -import -keystore <keystore name> -file rootet.cer

• keystore in this context is the truststore.
• Replace <keystore name> and <alias name> in the command above with any name.

3. The keytool prompts you for a keystore password. The password must be 6 or more characters in length.

4. In the code where you register your application with the server, you must modify the connection URI. In the examples in this wiki, this is typically done in the Main<ProjectName>Client file in each application /src directory.

5.Locate the string uri parameter. This is the value by default:

// TODO Change to correct URI

String uri = "tcp://appserver_ipaddress:9000";}}}

6. Modify the URI to support TLS. The following sample shows the correct parameter to support encryption, but not authentication.

// TODO Change to correct URI

String uri = "tls://<appserver_ipaddress>:9000";}}}

Note: The connection URI parameter can contain many parameters and filters. For more information, see Etch Connection URI.

7. When you run the application, you must first pass in the location of the truststore as a VM argument. To do so in Eclipse:

a. Click Run > Open Run Dialog.

b. Right-click your application and click New.

c. In the New Configuration, click the Arguments tab.

d. Type the following line in the VM arguments section.

-Djavax.net.ssl.trustStore=<keystore location>

e. Replace <keystore location> with the path to the location where you imported the keystore.

C# Applications//#

1. Copy the certificate created by the Platform Services installer to your client machine. The Platform Services installer saves it here: C:\Program Files\Cisco Systems\Unified Application Environment\AppServer\Rootet.cer.

2. Run MMC (to import it into the client machine's certificate store)

3. Add the Certificate snap-in:

• Click File>Add-Remove Snap-In.
• Click Add.
• Select Certificates and click Add.
• Select Computer Account and click Next.
• Select Local Computer.
• Click Finish.
• Click Close.
• Click OK.

4. Expand Certificates.

5. Right-click Trusted Root Certification Authorities and select All Tasks>Import.

6. In the Certificate Import Wizard, click Next.

7. In the File to Import page, browse to the certificate you copied from the Application Server.

8. Click Next and accept all defaults until you complete the wizard.

9. In the code where you register your application with the server, you must modify the connection URI. In the examples in this wiki, this is typically done in the Main<ProjectName>Client file in each application /src directory.

10. Locate the string uri parameter. This is the value by default:

// TODO Change to correct URI

string uri = "tcp://appserver_ipaddress:9000";}}}

11. Modify the URI to support TLS and authentication.

string uri = "tls://localhost:4001?TlsConnection.certName=Etch";

Note: The connection URI parameter can contain many parameters and filters. For more information, see Etch Connection URI.

Enable TLS in Plugins//#

Enabling TLS in plugins is more complex than it is for applications, because technically, a plugin acts as both a server and client of the Etch Bridge.

Note: Before attempting to set TLS for plugins, watch the http://developer.cisco.com/web/cuae/devconf2008 presentation from the 2008 Cisco Unified Application Environment Developer's conference if you are not already familiar with building etch-based plugins.

Enabling Encryption Only (Java and C#)#

Modify the connection URI in the three places:

1. Locate the string URI parameter. This is the value by default:

// TODO Change to correct URI

String uri = "tcp://appserver_ipaddress:9000";}}} 2. Modify the URI to support TLS and authentication.

• Use the following URI as the plugin's startup listening URI:

String uri = "tls://<plugin-host-or-IP>:<plugin-port>?TlsConnection.authReqd=false"

• When calling Etch Bridge registerPlugin API:

String uri = "tls://<plugin-host-or-IP>:<plugin-port>?TlsConnection.authReqd=false"

• In your plug-in while connecting to etch bridge, use the following Etch Bridge URI:

String uri = "tls://<appserver-ipaddress>:9000?TlsConnection.authReqd=false"

Note: The connection URI parameter can contain other parameters and filters. For more information, see Etch Connection URI.

Enabling Authentication for Java Plugins#

By default, the Platform Services installer creates the TLS certificate used for encryption and authentication on the application server. For plugin authentication you will need to create an additional certificate manually on the machine where your plugin will run.

Create a Certificate on your Plug-in Machine//#

1. Before running keytool make sure java is installed on your machine and is defined in PATH environment variable.

2. Run keytool to generate the certificate:

keytool -genkey -alias myalias -validity 365 -keystore <keystore path>

Enter keystore password: abc123 What is your first and last name? Unknown: Plugin 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.

3. Export the certificate created in previous section to a file:

keytool -export -keystore <keystore path> -alias myalias -file server.cer

Importing the Certificate to the Cisco Unified Application Server//#

In the last section you created a certificate for the machine running the plugin listener. Now you must import it into the certificate store on the Cisco Unified Application Server.

1. Copy the server.cer file to the machine running Cisco Unified Application Server.

2. On that machine, run MMC.

3. Add the Certificate snap-in:

• Click File>Add-Remove Snap-In.
• Click Add.
• Select Certificates and click Add.
• Select Computer Account and click Next.
• Select Local Computer.
• Click Finish.
• Click Close.
• Click OK.

4. Expand Certificates.

5. Right-click Trusted Root Certification Authorities and select All Tasks>Import.

6. In the Certificate Import Wizard, click Next.

7. In the File to Import page, browse to the server.cer certificate you copied.

8. Click Next and accept all defaults until you complete the wizard.

Modify the Connection URIs to Support TLS and Authentication//#

1. In your code, use the following URI as the plugin's startup listening URI:

"tls://<plugin-host-or-IP>:<plugin-port>"

2. When connecting to Etch Bridge, set the string URI as:

"tls://<app-server>:9000"

3. When calling the Etch Bridge registerPlugin API, pass in the following URI:

"tls://<plugin-host-or-IP>:<plugin-port>?TlsConnection.certName=<yourCreatedcertificateName>"

Where "<yourCreatedcertificateName>" should be the "CN" field value in your exported certificate. In this example, the certificate name is Plugin.

Note: The connection URI parameter can contain many parameters and filters. For more information, see Etch Connection URI.

4. When running your plug-in program, pass in the following VM arguments:

• -Djavax.net.ssl.keyStore=<FullPathOfTheKeystoreFile>
• -Djavax.net.ssl.keyStorePassword=<keystorePassword>
• -Djavax.net.ssl.keyPairPassword=<keypairPassword> (optional)

Copy the Etch Bridge Certificate//#

1. Copy the certificate created by the Platform Services to your client machine. The Platform Services installer saves it here: C:\Program Files\Cisco Systems\Unified Application Environment\AppServer\Rootet.cer.

2. Use keytool to import the rootet.cer to a truststore for the client.

*keytool -import -keystore <keystore name> -file rootet.cer*

• keystore in this context is the truststore.
• Replace <keystore name> in the command above with any name.

3. The keytool prompts you for a keystore password. The password must be 6 or more characters in length.

4. In the code where you register your application with the server, you must modify the connection URI. In the examples in this wiki, this is typically done in the Main<ProjectName>Client file in each application /src directory.

5. Locate the string uri parameter. This is the value by default:

// TODO Change to correct URI

String uri = "tcp://appserver_ipaddress:9000";}}}

6. Modify the URI to support TLS. The following sample shows the correct parameter to support encryption, but not authentication.

// TODO Change to correct URI

String uri = "tls://<appserver_ipaddress>:9000";}}}

7. When you run the application, you must pass in the location of the truststore as a VM argument. To do so in Eclipse:

a. Click Run > Open Run Dialog.

b. Right-click your application and click New.

c. In the New Configuration, click the Arguments tab.

d. Type the following line in the VM arguments section.

-Djavax.net.ssl.trustStore=<keystore location>

e. Replace <keystore location> with the path to the location where you imported the keystore.

Enabling Authentication for C# Plugins#

By default, the Platform Services installer creates the TLS certificate used for encryption and authentication on the application server. For plugin authentication you must create an additional certificate manually on the machine where your plugin will run.

Create a Certificate on your Plug-in Machine//#

1. Create a certificate on your plug-in machine using the makecert tool.

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

The above command creates a Root certificate. Your personal certificates extend from this root certificate. To create a personal certificate:

makecert -pe -n "CN=PluginEt" -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 PluginEt

2. Run MMC

3. Add the Certificate snap-in:

• Click File>Add-Remove Snap-In.
• Click Add.
• Select Certificates and click Add.
• Select Computer Account and click Next.
• Select Local Computer.
• Click Finish.
• Click Close.
• Click OK.

4. Expand Certificates > Personal. You should see your newly created certificates.

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

6. Expand Trusted Root Certification Authorities\Certificates.

7. Right-click the certificate you just created and select All Tasks->Export.

8. In the Certificate Export wizard, click Next.

9. Select No, do not export the private key.

10. Keep the default for the Export File Format (DER encoded binary X509)

11. Type in any file name and click finish (for example server.cer).

Importing the Certificate to the Cisco Unified Application Server//#

In the last section you created a certificate for the machine running the plugin listener. Now you must import it into the certificate store on the Cisco Unified Application Server.

1. Copy the server.cer file to the machine running Cisco Unified Application Server machine, run MMC.

2. On that machine, run MMC

3. Add the Certificate snap-in:

• Click File>Add-Remove Snap-In.
• Click Add.
• Select Certificates and click Add.
• Select Computer Account and click Next.
• Select Local Computer.
• Click Finish.
• Click Close.
• Click OK.

4. Expand Certificates.

5. Right-click Trusted Root Certification Authorities and select All Tasks>Import.

6. In the Certificate Import Wizard, click Next.

7. In the File to Import page, browse to the server.cer certificate you copied.

8. Click Next and accept all defaults until you complete the wizard.

Modify the URI to support TLS and authentication.//#

• Use the following URI as the plugin's startup listening URI:

"tls://localhost:<plugin-port>?TlsConnection.certName=PluginEt>"

• When calling bridge's "registerPlugin" API, pass in the following URI if you want to turn on TLS authentication:

"tls://<plugin-host-or-IP>:<plugin-port>?TlsConnection.certName=PluginEt"

Copy the Etch Bridge Certificate to the Plugin Machine//#

If you are implementing a C# plug-in, you must copy the Etch Bridge certificate to enable TLS authentication for the bridge listener connection.

1. Copy the certificate created by the Platform Services installer to your client machine. The Platform Services installer saves it here: C:\Program Files\Cisco Systems\Unified Application Environment\AppServer\Rootet.cer.

2. Run MMC (to import it into the client machine's certificate store)

3. Add the Certificate snap-in:

• Click File>Add-Remove Snap-In.
• Click Add.
• Select Certificates and click Add.
• Select Computer Account and click Next.
• Select Local Computer.
• Click Finish.
• Click Close.
• Click OK.

4. Expand Certificates.

5. Right-click Trusted Root Certification Authorities and select All Tasks>Import.

6. In the Certificate Import Wizard, click Next.

7. In the File to Import page, browse to the certificate you copied from the Application Server.

8. Click Next and accept all defaults until you complete the wizard.

9. In the code where you register your application with the server, you must modify the connection URI. In the examples in this wiki, this is typically done in the Main<ProjectName>Client file in each application /src directory.

10. Locate the string uri parameter. This is the value by default:

// TODO Change to correct URI

String uri = "tcp://appserver_ipaddress:9000";}}}

11. Modify the URI to support TLS and authentication.

string uri = "tls://localhost:4001?TlsConnection.certName=Etch.cer";

The certificate name must correspond to the certificate name of the Cisco Unified Application Server certificate.

Note: The connection URI parameter can contain many parameters and filters. For more information, see Etch Connection URI.

To Disable TLS on Etch Bridge#

If you do not want to use TLS for encryption or authentication, follow these procedures:

1. Open C:\Program Files\Cisco Systems\Unified Application Environment\AppServer\AppServerService.exe.config.

2. Set the EtchBridgeCertificate value to "".

3. Restart the Cisco Unified Application Server.