1.4. Encrypted Communication

Warning

This document is not complete.

Thrift documentation on SSL

It is possible to use an encrypted connection when interacting with the Xpert Client through its API.

Note

Usage of encryption must be set in the System Manager. See Enabling API in OpenScape Xpert Management Portal

1.4.1. Certificate deployment

1.4.1.1. Diagnosis Tool

OpenScape Xpert Diagnosis Tool has a feature built in for certificate deployment. For more information: Service Manual: 6.11 - Mass deployment of HTEMS certificates for OSX Devices.

Note

It talks about HTEMS certificate replacement but that also replaces the certificates used by the API.

1.4.1.2. Manual deployment

If you only want to deploy certificates for the API - for now - you have to do it manually. For that you will need the following files:

  • <platform dir>/api_tls/trusted-cert.pem: the trusted CA certificate (chain)

  • <platform dir>/api_tls/server-cert.pem: the public key

  • <platform dir>/api_tls/.key/server-key.pem: the private key

Where <platform dir> is /etc/cert for a Linux Turret, and C:/Program Files (x86)/Trading_E/Tb/ for Windows soft-client.

On Linux Turret the file permissions, owners and groups are the following:

api_tls/:
-rw-rw-r-- 1 ttadmin certificate 4.6K Jan 22 04:39 server-cert.pem
-rw-rw-r-- 1 ttadmin certificate 4.3K Jan 22 04:39 trusted-cert.pem

api_tls/.key/:
-r---w---- 1 turret certificate 1.7K Nov 30 08:28 server-key.pem

You can set these with the following commands:

# chown ttadmin:certificate /etc/cert/api_tls/*
# chmod 664 /etc/cert/api_tls/*

# chown turret:certificate /etc/cert/api_tls/.key/*
# chmod 420 /etc/cert/api_tls/.key/*

1.4.2. Generating certificates for development purposes

For the two-way authentication to work, both parties will need to trust each other. Instead of copying self-signed certificates both ways, setting up our own root CA and signing the certificates with it should be easier and expandable.

rectangle "Certificate Authority" { file "Root CA" as ca } 'rectangle "Turret" { file "Turret Certificate" as sc file "Turret Key" as sk '} file "Client Certificate" as cc file "Client Key" as ck ca <<-- sc : signed by ca <<-- cc : signed by sc -- sk cc -- ck

Overview of the certificate chain

1.4.2.1. Creating a private key

Using OpenSSL, generating a private key can be as simple as:

$ openssl genrsa -out <filename> 2048

Note

The genrsa command can be supplied with different arguments for example a cipher for encrypting the key. More info in the OpenSSL documentation for genrsa.

1.4.2.2. Create CA certificate

First we need a private key for the certificate authority, for example trusted.key. (See Creating a private key)

Armed with that key we can now become a Certificate Authority:

$ openssl req -x509 -new -nodes -key trusted.key -days 3650 -out trusted-cert.pem

This prompts for some information but neither of them really matter for our purposes.

More info on openssl req.

1.4.2.3. Creating a signed certificate for the Turret

Since the Turret API uses the DefaultClientAccessManager for client validation, creating a certificate for the turret will need some more information.

From the official Thrift site regarding Access Managers we can see that our certificate will need at least one of the following fields:

  • IP subjectAltName

  • DNS subjectAltName

  • common name

With that information in mind first we need a private key eg. server-key.pem and armed with that we can create a certificate signing request:

$ openssl req -new -key server-key.pem -out server.csr

Prompting you to enter similar information as before. On the Common Name prompt you may enter the server IP address/DNS name optionally and skip adding the subject alternative name.

Subject Alternative Name is an extension, so to add that to the certificate we will need a configuration file.

turret-altnames.conf
 [ san_ext ]
 subjectAltName = @alt_names

 [alt_names]
 DNS = <DNS name>
 IP  = <IP address>

Now that we have a Certificate Signing Request and the configuration file we can turn to the CA (also us) to sign the public key for the turret.

$ openssl x509 -req -days 365 \
>   -CA trusted-cert.pem -CAkey trusted.key -CAcreateserial \
>   -in server.csr -out server-cert.pem \
>   -extensions san_ext -extfile turret-altnames.conf

And now we have all three files we need to deploy to the Turret.

More info on openssl x509.

Creating a signed certificate for our application can be done in a similar fashion.

1.4.3. Using certificate in 3rd party app

See Encryption Example