Secure the connection with the agent

This topic describes establishing security on the connection between the connected product and the agent. This is applicable when the connected product uses the Lumberjack protocol and not QLT. If your product uses QLT as the connection protocol with the agent, see the user documentation for the product for configuration details.

Authentication and SSL

The agent uses certificate-based mutual authentication for event ingestion over Lumberjack. Sample certificates are included in the agent image file you downloaded when completing Deploy the agent. These are intended for testing, but you should replace them with your own. See Manage certificates to do so.

To configure the server for Secure Sockets Layer (SSL) authentication, you must obtain server certificates and:

  • Copy the truststore to the agent's capture_truststore shared file
  • Copy the keystore to the agent's capture_keystore shared file
  • In the agent's service_configuration shared file, update:
Property Value
com.systar.mercury.keystorePassword <keystore_password>

To configure the Lumberjack client for SSL authentication, obtain the client certificates and add them to your client of choice.

Manage certificates

The agent uses certificate-based mutual authentication for data reception via the Lumberjack protocol. This following is what you need.

We recommend using KeyStore Manager to manage certificates. The commands documented in this topic assume that you do, but you can use your own commands to generate certificates without KeyStore Manager.

Certificate authority 

A trusted certificate authority (CA) is needed to generate certificates. You can use a commercial CA or create your own for self-signed certificates.

Create a CA for self-signed certificates

Execute the following command to generate the CA and generate a private key for it:

$ ksm createCA <ca_name> -password <ca password>

The generated CA keystore is created under <keystore manager installation directory>/var/data/<ca_name>.p12

Set up an external CA for certificate generation with KeyStore Manager

To import a CA for use with KeyStore Manager:

  • PKCS #12:
    • Copy CA under <keystore manager installation directory>/var/data/<ca_name>.p12 
  • Java KeyStore (JKS):
    • Update the keystore type for CA files in KeyStore Manager configuration to JKS, following its documentation 
    • Copy CA under <keystore manager installation directory>/var/data/<ca_name>.jks 

Server certificates

You need the following:

  • A JKS truststore containing the CA.
  • A JKS keystore containing the host, on which the container is deployed, private key and signed by the CA.

Generate server certificates

  1. Create a new host key in the CA keystore by doman-name system (DNS) or Internet protocol (IP):

    • By DNS

      $ ksm createHostKey <host_key_name> -ca <ca_name> -password <ca password> -dns <host dns entry>
    • By IP

      $ ksm createHostKey <host_key_name> -ca <ca_name> -password <ca password> -ip <host ip>
  2. Export the host key and certificate in JKS format:

    $ ksm exportHostKey <host_key_name> -ca <ca_name> -password <ca password> -format JKS -exportpassword <key password>

    The generated files are created on disk:

    • The trust store that contains the CA certificate:
       <keystore manager installation directory>/var/work/<ca_name>/<host_key_name>/jks/<ca_name>_truststore.jks
    • The trust store that contains the host private key and its certificate signed by the CA:  
       <keystore manager installation directory>/var/work/<ca_name>/<host_key_name>/jks/<host_key_name>_keystore.jks

Client certificates

You need the following:

  • An OpenSSL CA corresponding to the CA used for server certificate signing
  • An OpenSSL private key with:
    • Alias tenant_1
    • dname CN=tenant_1
  • An OpenSSL certificate signed with the CA for the key

Generate client certificates

  1. Create a host key in the CA keystore.

    $ ksm createHostKey tenant_1 -ca <ca_name> -password <ca password> -dns unchecked

    Note that the DNS is purposely invalid. It does not matter since it is not validated by either side in the SSL communication.

  2. Export the key and certificates in OpenSSL format.

    $ ksm exportHostKey tenant_1 -ca <ca_name> -password <ca password> -format openssl -exportpassword <client key password>

    The following generated files are create on disk:

    • The OpenSSL CA:
       <keystore manager installation directory>/var/work/<ca_name>/tenant_1/openssl/<ca_name>.crt
    • The OpenSSL private key:  
       <keystore manager installation directory>/var/work/<ca_name>/tenant_1/openssl/tenant_1.key
    • The OpenSSL key certificate:  
       <keystore manager installation directory>/var/work/<ca_name>/tenant_1/openssl/tenant_1.crt

Related Links