Managing Key Trustee Server Certificates

Transport Layer Security (TLS) certificates are used to secure communication with Key Trustee Server. By default, Key Trustee Server generates self-signed certificates when it is first initialized. Cloudera strongly recommends using certificates signed by a trusted Certificate Authority (CA).

Generating a New Certificate

  1. Generate a new certificate signing request (CSR): 
    openssl req -new -key keytrustee_private_key.pem -out new.csr

    Replace keytrustee_private_key.pem with the filename of the private key. You can reuse the existing private key or generate a new private key in accordance with your company policies. For existing auto-generated self-signed certificates, the private key file is located at /var/lib/keytrustee/.keytrustee/.ssl/ssl-cert-keytrustee-pk.pem.

  2. Generate a new certificate from the CSR:
    • For a CA-signed certificate, submit the CSR to the CA, and they will provide a signed certificate.
    • To generate a new self-signed certificate, run the following command: 
      $ openssl x509 -req -days 365 -in new.csr -signkey keytrustee_private_key.pem \
-out new_keytrustee_certificate.pem

Replacing Key Trustee Server Certificates

Use the following procedure if you need to replace an existing certificate for the Key Trustee Server. For example, you can use this procedure to replace the auto-generated self-signed certificate with a CA-signed certificate, or to replace an expired certificate.

  1. After Generating a New Certificate, back up the original certificate and key files: 
    sudo cp -r /var/lib/keytrustee/.keytrustee/.ssl /var/lib/keytrustee/.keytrustee/.ssl.bak
  2. (CA-Signed Certificates Only) Provide either the root or intermediate CA certificate: 
    sudo mv /path/to/rootca.pem /var/lib/keytrustee/.keytrustee/.ssl/ssl-cert-keytrustee-ca.pem
  3. Make sure that the certificate and key files are owned by the keytrustee user and group, with file permissions set to 600: 
    sudo chown keytrustee:keytrustee /path/to/new/certificate.pem /path/to/new/private_key.pem
sudo chmod 600 /path/to/new/certificate.pem /path/to/new/private_key.pem
  4. Update the Key Trustee Server configuration with the location of the new certificate and key files:
    • Using Cloudera Manager:
      1. Go to the Key Trustee Server service.
      2. Click the Configuration tab.
      3. Select Category > Security.
      4. Edit the following properties to specify the location of the new certificate and key files. If the private keys are not password protected, leave the password fields empty.
        • Active Key Trustee Server TLS/SSL Server Private Key File (PEM Format)
        • Active Key Trustee Server TLS/SSL Server Certificate File (PEM Format)
        • Active Key Trustee Server TLS/SSL Private Key Password
        • Passive Key Trustee Server TLS/SSL Server Private Key File (PEM Format)
        • Passive Key Trustee Server TLS/SSL Server Certificate File (PEM Format)
        • Passive Key Trustee Server TLS/SSL Private Key Password
      5. Enter a Reason for change, and then click Save Changes to commit the changes.
    • Using the command line:
      1. Edit /var/lib/keytrustee/.keytrustee/keytrustee.conf on the active and passive Key Trustee Server hosts and modify the SSL_CERTIFICATE and SSL_PRIVATE_KEY parameters as follows: 
            "SSL_CERTIFICATE": "/path/to/new/certificate.pem",
    "SSL_PRIVATE_KEY": "/path/to/new/private_key.pem"
        If the private key is password protected, add the following entry: 
            "SSL_PRIVATE_KEY_PASSWORD_SCRIPT": "/path/to/password_script [arguments]"

        Replace /path/to/password_script [arguments] with the path to a script (and any necessary command arguments) that returns the password for the private key file. If you do not want to create a script, you can use a simple command, such as echo -n password. For example:

            "SSL_PRIVATE_KEY_PASSWORD_SCRIPT": "/bin/echo -n password"

        Keep in mind that this method can expose the private key password in plain text to anyone who can view the /var/lib/keytrustee/.keytrustee/keytrustee.conf file.

  5. Restart Key Trustee Server:
    • Using Cloudera Manager: Restart the Key Trustee Server service (Key Trustee Server service > Actions > Restart).
    • Using the Command Line: Restart the Key Trustee Server daemon:
      • RHEL 6-compatible: $ sudo service keytrusteed restart
      • RHEL 7-compatible: $ sudo systemctl restart keytrusteed
  6. If you are using the Key Trustee KMS service in Cloudera Manager for HDFS Transparent Encryption, update the Java KeyStore (JKS) used on the Key Trustee KMS host:
    1. Download the new certificate to the Key Trustee KMS host: 
      $ echo -n | openssl s_client -connect keytrustee01.example.com:11371 \
| sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/keytrustee_certificate.pem
    2. Delete the existing keystore entry for keytrustee01.example.com: 
      keytool -delete -alias key_trustee_alias_name -keystore /path/to/truststore -v
    3. Add the new keystore entry for keytrustee01.example.com: 
      $ keytool -import -trustcacerts -alias keytrustee01.example.com \
-file /tmp/keytrustee_certificate.pem -keystore /path/to/truststore
    4. Restart the Key Trustee KMS service in Cloudera Manager.
  7. If you are using Key HSM, update the Key Trustee Server and Key HSM configuration:
    1. Run the keyhsm trust command, using the path to the new certificate: 
      sudo keyhsm trust /path/to/new/key_trustee_server/cert
    2. Run the ktadmin keyhsm command, using the --client-certfile and --client-keyfile options to specify the location of the new certificate file and private key: 
      sudo ktadmin keyhsm --server https://keyhsm01.example.com:9090 --client-certfile /path/to/new/key_trustee_server/cert --client-keyfile /path/to/new/key_trustee_server/private_key