Skip to main content

Home

Configuring HTTPS for Unravel (Transport Layer Security, TLS)

You must do the following to configure HTTPS for Unravel:

  1. Check and fulfill the prerequisites.

  2. Enable Transport Layer Security (TLS) for Unravel

Important

Before you configure HTTPS for Unravel, ensure that you have the server certificate, key, and any intermediate certificate that is needed to validate the trust chain.

If the root certificate is not from a known certificate authority, it will have to be manually trusted.

See Truststore certificates.

Prerequisites

  • You must have the following handy. Ensure that these files are available on Unravel server.

    • Server certificate

    • Key for the server certificate and its password, if it is encrypted.

    • Any intermediate certificate that is required to complete the trust chain.

    The following certificate formats are supported:

    • PEM (.pem)

    • JKS (.jks)

    • PKCS12 (pkcs12, .p12, .pfx)

Enable TLS for Unravel

  1. Stop Unravel.

    <unravel_installation_directory>/unravel/manager stop

  2. Configure the key and certificate.

    <unravel_installation_directory>/unravel/manager config tls set /path/to/key.pem /path/to/certificate.pem /path/to/intermediate.pem  --key-password <password>

    Note

    The command accepts the following file formats and relies on the extension to identify the format:

    • PEM (.pem)

    • JKS (.jks)

    • PKCS12 (pkcs12, .p12, .pfx)

    If you are using a different file extension, you must specify the file as follows:

    • --pem <filename>

    • --jks <filename>

    • --pkcs12 <filename>

  3. Enable TLS.

    <unravel_installation_directory>/unravel/manager config tls enable

  4. Apply the configuration.

    <unravel_installation_directory>/unravel/manager config apply

  5. Verify the TLS configuration:

    <unravel_installation_directory>/unravel/manager verify tls

    Following are some error messages that you can get when you run verify tls command:

    • Error shown for missing intermediate certificate

      Errors:
- [20, 0, 'unable to get local issuer certificate']
Can't find issuer: /C=US/ST=California/O=Unravel/OU=Engineering/CN=TEST-INTERMEDIATE-CA

    • Error shown for unknown root certificate that needs to be trusted:

      Errors:
- [19, 2, 'self signed certificate in certificate chain']
Untrusted root certificate: /C=US/ST=California/O=Unravel/OU=Engineering/L=San Francisco/CN=TEST-ROOT-CA

    • Any errors related to the key and server certificate validity should be resolved with the config tls set command.

    • Any errors related to finding the issuer of a certificate:

      • You can resolve the error for an intermediate certificate by passing the needed certificate to config tls set.

      • You can resolve the error for a root certificate by trusting the root certificate. See Truststore certificates.

  6. Start Unravel.

    <unravel_installation_directory>/unravel/manager start
Example:

You must have the following files handy. Ensure that these files are available on Unravel server.

  • SERVER.pem: The server certificate

  • KEY.pem: The key for the server certificate

  • INTERMEDIATE.pem: Optionally, the trust chain for the server certificate (You can merge this with the server certificate).

/opt/unravel/manager stop
/opt/unravel/manager config tls set /path/to/KEY.pem /path/to/SERVER.pem /path/to/INTERMEDIATE.pem –key-password the-password
/opt/unravel/manager config tls enable
/opt/unravel/manager config apply
/opt/manager verify tls
/opt/unravel/manager start
Disable TLS for Unravel

  1. Stop Unravel.

    <unravel_installation_directory>/unravel/manager stop

  2. Disable TLS.

    <unravel_installation_directory>/unravel/manager config tls disable

  3. Apply the configuration.

    <unravel_installation_directory>/unravel/manager config apply

  4. Start Unravel.

    <unravel_installation_directory>/unravel/manager start

Also, see:

In this section: