Troubleshooting TLS/SSL Errors

This section describes some common issues with TLS configuration on Cloudera Data Science Workbench. Common errors include.

  • Cloudera Data Science Workbench initialisation fails with an error such as:
    Error preparing server: tls: failed to parse private key 
  • Your browser reports that the Cloudera Data Science Workbench web application is not secure even though you have enabled TLS settings as per Enabling TLS/SSL for Cloudera Data Science Workbench.
  • You have properly installed CDSW, but when trying to start a session, see "Cannot connect to livelog" or "websocket error".
  • You have installed the TLS certificate, but when visiting the URL, the browser complains that the site is not secure
  • When trying to open a _Terminal in a running session, you get a 500 error

Possible Causes and Solutions

  • Certificate does not include the wildcard domain - Confirm that the TLS certificate issued by your CA lists both, the Cloudera Data Science Workbench domain, as well as a wildcard for all first-level subdomains. For example, if your Cloudera Data Science Workbench domain is cdsw.company.com, then the TLS certificate must include both cdsw.company.com and *.cdsw.company.com.
  • Path to the private key and/or certificate is incorrect - Confirm that the path to the private key file is correct by comparing the path and file name to the values for TLS_KEY and/or TLS_CERT in cdsw.conf or Cloudera Manager. For example:
    TLS_CERT="/path/to/cert.pem"
    TLS_KEY="/path/to/private.key"
  • Private key file does not have the right permissions - The private key file must have read-only permissions. Set it as follows:
    chmod 444 private.key
  • Private key is encrypted - Cloudera Data Science Workbench does not support encrypted private keys. Check to see if your private key is encrypted:
    cat private.key
    -----BEGIN RSA PRIVATE KEY-----
    Proc-Type: 4,ENCRYPTED
    DEK-Info: DES-EDE3-CBC,11556F53E4A2824A
    If the private key is encrypted as shown above, use the following steps to decrypt it:
    1. Make a backup of the private key file.
      mv private.key private.key.encrypted
    2. Decrypt the backup private key and save the file to private.key. You will be asked to enter the private key password.
      openssl rsa -in private.key.encrypted -out private.key
  • SAN entries incorrect - Review the SAN entries in the certificate and ensure they are correct - pay special attention to hidden characters, for instance, this is correct:DNS:mycdsw.company.com while this, with a leading space, will cause issues: DNS: mycdsw.company.com
  • Root certificate not trusted by client - The client machine that is accessing CDSW must trust the root certificate used to sign the TLS certificate. In some cases, this root certificate must be imported into the host machine, such as the Keychain Access on Mac or the Certificates Store on Windows. Often there are corporate security policies that can automatically add these certificates, but not always.
  • Private key and certificate are not related - Check to see if the private key matches the public key in the certificate.
    1. Print a hash of the private key modulus.
      openssl rsa -in private.key -noout -modulus | openssl md5
      (stdin)= 7a8d72ed61bb4be3c1f59e4f0161c023
    2. Print a hash of the public key modulus.
      openssl x509 -in cert.pem -noout -modulus | openssl md5
      (stdin)= 7a8d72ed61bb4be3c1f59e4f0161c023
      If the md5 hash output of both keys is different, they are not related to each other, and will not work. You must revoke the old certificate, regenerate a new private key and Certificate Signing Request (CSR), and then apply for a new certificate.
    TLS certificate contains spaces or other newline characters - When working with TLS certificates across different operating systems, sometimes newline characters can be inserted into the certificate. When copy and pasting the certificate into the Site Administration Security Root CA configuration , use a text editor to ensure that you are using Unix style line endings.