Enabling SSL/TLS Encryption

Yellowbrick supports SSL/TLS encryption, using TLS protocol v1.2, for client communications and passwords, including remote connections to the SMC and connections via client tools such as ybload.

SSL-Only Mode

If you want to automatically enforce SSL mode for all client connections, you can set the appliance to SSL-only mode. When the appliance is running in this mode, all client connections from all tools, including connections to the SMC, the front-end PostgreSQL database, and ybtools, must connect via HTTPS. All HTTP connections are rejected.

Encryption Settings for ybtools

The following client tools support Transport Layer Security (TLS) encryption:
  • ybload
  • ybunload
  • ybbackup, ybrestore
These tools provide the following security options:
  • --secured: enable secured mode
  • --cacert: supply a custom certificate for trusting the appliance
  • --disable-trust: disable trust checking (not for use on production systems)
When --secured is set, SSL/TLS encryption is used to secure all communication. The default setting is not secured; no encryption is used.
Note: When SSL-only mode is enabled, you do not need to use the --secured option in ybtools commands. However, the behavior described here for the --cacert and --disable-trust options still applies.

See Opening Network Ports for Clients for a list of the port numbers that the client tools use for data control and data transfer. The ybtools data transfer ports will remain unencrypted if the --secured option is not set or SSL-only mode is not enabled.

Trust and Trust Customization

Trust for SSL/TLS communication is enabled by default. To use SSL/TLS encryption, you may need to change the self-signed certificate for your appliance to a certificate signed by a well-known trust authority (CA).

Alternatively, you can use the --cacert option to specify a custom trusted certificate for use with the default self-signed appliance certificate. This option accepts a PEM-encoded file or a Java KeyStore (JKS).

You can disable trust by using the --disable-trust (or -k) option in combination with the --secured option.
Important: This option is not supported for use on production systems and is only recommended for testing purposes. It may be useful to disable trust during testing, then enable it when a formal signed certificate is installed on the appliance.

Import Certificates

The initial SSL certificate for a Yellowbrick database is established with a self-signed, untrusted SSL certificate. Your organization may choose to change this database certificate to align with its internal policies by importing a certificate signed with a private signing authority/CA or by using an external signing authority. Without a Certificate Authority (CA)-signed certificate, you may get errors such as:
There is a problem with this website's security certificate.

The Import Certificate button in the SMC allows customers to import a new SSL certificate for the database. The same certificate is used for establishing trust to both the HTTPS listener and the Postgres TLS listener. The import must be done with a PEM-encoded certificate issued by a third-party CA or a custom CA trusted by the organization's standard browser.

Enabling SSL Settings

Follow these steps to import a new certificate and/or enable SSL-only mode:
  1. Log into the SMC as the yellowbrick user.
  2. Go to Configure > Settings > SSL.
  3. To import a new certificate, click Import Certificate and import the public key and the private key. You must specify the password for the private key. Be prepared to provide all three values: both keys and the private key password.
    Although the format of the files being imported is text, it is encoded as follows:
    -- BEGIN PRIVATE KEY -- <data> -- END PRIVATE KEY
    ...
    -- BEGIN CERTIFICATE -- <data> -- END CERTIFICATE KEY --
  4. Select the Enable SSL-only communications checkbox. (Skip this step if you only want to import a new certificate.)
  5. If required by your certificate, enter a fully-qualified hostname for the SMC in the Automatic Redirect field. Redirection is commonly used to match the Common Name (CN) or Subject Alternative Name (SAN) in an SSL certificate to the URL a user visits in order to establish trust. If browsers attempt to log into the SMC via an HTTP URL, those connections will be redirected to the hostname you entered, using HTTPS.
    For example:
    http://yb100
    will be redirected to:
    https://yb100.redirectme.com

    assuming you entered yb100.redirectme.com in the Automatic Redirect field.

  6. Click Save Settings in the top-right corner of the Configuration Settings screen.
  7. Restart the database as prompted, using ybcli:
    $ ybcli -y database stop
    ...
    $ybcli database start