Home

HTTPS, TLS, and Certificates issues

This section provides information to troubleshoot issues regarding network connectivity to Unravel and other services (HDFS, LDAP, etc).

Investigate connectivity with a simple connection test using curl (Only for HTTP/HTTPS)

If curl is available on the server, you can run the following curl commands to do some basic investigation.

  • HTTP connection

    curl http://<ADDRESS>:<PORT>
  • HTTPS connection

    curl https://<ADDRESS>:<PORT>
  • cacert option. Pass the root certificate to verify the trust chain while connecting.

    curl --cacert <CERTIFICATE FILE> https://<ADDRESS>:<PORT>
  • Test the HTTPS connection without verifying the certificate chain.

    curl –insecure https://<ADDRESS>:<PORT>
Typical curl errors
  • curl: (51) Unable to communicate securely with peer: requested domain name does not match the server's certificate.

    The server certificate does not match the server name that you have used to connect. Verify that the certificate you have used is for the correct server.

  • curl: (52) Empty reply from server

    This error indicates that you have connected but did not get any content from the server. This occurs if you are connecting over HTTP protocol whereas the server is HTTPS protocol. However, this error can occur due to other network-related issues also.

  • curl: (60) Peer's Certificate issuer is not recognized.

    This error indicates that the certificate trust chain could not be verified. Either you are missing an intermediate certificate or the root certificate is not trusted.

    For Unravel services, the intermediate certificate should be configured with config tls set, see Configuring HTTPS for Unravel and the root must be trusted with config tls trust add. Refer to Truststore certificates.

    For other services, if they are not serving the trust chain, you must trust any missing intermediate or root certificates. Refer to Truststore certificates.

Verifying connectivity with manager command (Any protocol)

If unravel is installed, the manager command can be used to investigate connectivity issues. This command reports on DNS resolution errors, connection errors, and TLS errors.

Using the following manager command you can connect to the address and port and try both plain and TLS connections. If the server supports TLS, it will validate the chain and report the certificates that it could not find to trust the chain. It will also report the expiration dates for certificates in the chain.

manager verify connect <ADDRESS> <PORT>

For Unravel services, the intermediate certificate should be configured with config tls set , see Enable TLS for Unravel and roots should be trusted with config tls trust add, see Truststore certificates.

For other services, which are not serving the trust chain, you must trust any missing intermediate and the root certificate, see Truststore certificates.

Inspecting server response and certificates (Any protocol)

If the following commands are available on the server, you can deeply investigate the TLS issues. This is similar to the verification done with manager verify connect command and inspecting certificate content.

  • Attempt to connect to a server

    openssl s_client -connect <ADDRESS>:<PORT> <<< ""

    This will connect to the server using TLS and report connection information.

    <<< "" is optional. This sends an empty string over the connection causing the connection to close. Else, the command hangs until you provide some input (Example: press ENTER).

    The following is displayed in the output:

    ---
    Certificate chain
     0 s:/C=US/ST=California/..snip../CN=my-server.domain
       i:/C=US/ST=California/..snip.../CN=TEST-INTERMEDIATE-CA
     1 s:/C=US/ST=California/...snip.../CN=TEST-INTERMEDIATE-CA
       i:/C=US/ST=California/...snip.../CN=TEST-ROOT-CA
    ---
    
    • Certificate (0) is the server certificate for my-server.domain which is signed by TEST-INTERMEDIATE-CA.

    • Certificate (1) is the TEST-INTERMEDIATE-CA certificate which is signed by TEST-ROOT-CA. If you trust TEST-ROOT-CA, then you can validate the chain.

    • If you are missing certificates or the root cannot be trusted, the following message at the end of the command:

      Verify return code: 20 (unable to get local issuer certificate)at the end of the command.

  • Inspect the content of a certificate

    Run the following to view the content of the certificate.

    openssl x509 -text -in /path/to/certificate.pem

    Check the following items in the output:

    • Which server is the certificate intended for?

      Subject: C=US, ...snip..., CN=my-server.domain

      And

      X509v3 extensions:
         X509v3 Subject Alternative Name: 
            DNS:my-server.domain
      
    • Who issues (signs) the certificate:

      Issuer: C=US, …snip…, CN=TEST-INTERMEDIATE-CA

    Also, see: