Troubleshooting Secure Configuration (SSL/TLS)
Verifying and Troubleshooting certificate files
OpenSSL can be used for verifying the certificate chain. Depending on how the certificate was issued, there are two main ways to do this. OpenSSL for Windows can be downloaded from https://wiki.openssl.org/index.php/Binaries.
Verifying a certificate signed by a trusted CA
To verify a certificate signed by a trusted CA, use the following command:
openssl verify seeq-cert.pem
The output of the command should be something like "seeq-cert.pem: OK". If it's not, there might be an issue with the certificate or the certificate chain, so you'll need to inspect the certificate to dig further (see below).
Verifying a certificate signed by an internal (non-official) CA or a self-signed certificate
When using a certificate signed by an internal (non-official) CA or a self-signed certificate, the seeq-cert.pem file should contain the entire chain of certificates starting with the server certificate, then any intermediate certificate and finally the CA certificate. To verify such a certificate, each certificate block in the seeq-cert.pem file needs to be saved in its own file, for example seeq-cert1.pem for the server certificate, seeq-cert2.pem for the intermediate certificate and seeq-cert3.pem for the CA certificate (the numbers correspond to the order which the certificate blocks appear in seeq-cert.pem). Note that the file numbering is only for verifying the certificate using OpenSSL, Seeq does not use the individual files, so after the verification is successful, the numbered files can be deleted. The command to run to verify the entire certificate chain is as follows:
openssl verify -CAfile seeq-cert3.pem -untrusted seeq-cert2.pem seeq-cert1.pem
The output of the command should be something like "seeq-cert.pem: OK". If it's not, there might be an issue with the certificate or the certificate chain, so you'll need to inspect the certificate to dig further (see below).
Certificate verification messages
The following is a list of known certificate verification messages and resolutions.
Message | Resolution |
---|---|
OK | None; Certificate verification successful, it's ready for Seeq! |
unable to get issuer certificate | The ordering of the certificates (server, intermediate and CA) in seeq-cert.pem are probably incorrect or a certificate is missing from the file (certificate path is broken). |
certificate is not yet valid | The certificate is not yet valid. Generate a new Certificate Signing Request (CSR) to request a new certificate or wait until certificate becomes valid. |
certificate has expired | The certificate has expired. Renew certificate or generate a new Certificate Signing Request (CSR) to request a new certificate. |
self signed certificate | The certificate is self-signed (no official CA trust). Use the -CAfile option to specify CA certificate to verify the certificate. |
invalid CA certificate | The CA certificate is invalid; Either it's not a CA certificate or it's not valid for the supplied purpose (SSL/web server usage). |
unsupported certificate purpose | The certificate is not valid for the supplied purpose (SSL/web server usage). |
Most of the OpenSSL error messages will also output a depth, for example "error 2 at 1 depth lookup:unable to get issuer certificate". Depth indicates the certificate number (starting a 0).
Inspecting a certificate
In case of a certificate verification failure, each individual certificate file (seeq-cert1.pem, seeq-cert2.pem and seeq-cert3.pem from above) can be inspected using the following OpenSSL command:
openssl x509 -in seeq-certX.pem -text -noout
There could be several different problems with the certificates, but make sure the expiration dates aren't passed and take a look at the lines containing "Subject" (what the certificate is for) and "Issuer" (who issued the certificate) to make sure they're in the correct order in seeq-cert.pem. The correct order is server certificate, then intermediate certificate (if such exists), then CA certificate. Also make sure the server certificate is issued for the correct server name (CN part of the Subject line).
Verifying that a private key matches a certificate
If the certificate and key file are not a matching pair, the server will generate an error at startup. If you suspect that this is the case, you can verify that using openssl. See the Apache SSL/TLS FAQ for a description.
openssl x509 -noout -modulus -in server-cert.pem | openssl md5
openssl rsa -noout -modulus -in server-key.pem | openssl md5
Each of these commands should generate a sequence of numbers and letters (a hash). In a correct pair, those sequences should be the same. If those two sequences are different, then the certificate and key files were not generated from the same certificate request and cannot be used to secure Seeq.
Troubleshooting certificate connection issues
Inspecting certificate details
OpenSSL can also be used to verify the certificate after it's installed, which can sometimes be difficult with a web browser as it only provides some some basic (user friendly) information. Use the following command to connect to the Seeq Server and have OpenSSL verify the validity of the certificate:
openssl s_client -host <SEEQ-SERVER-HOSTNAME> -port <SEEQ-SERVER-SECURE-PORT>
OpenSSL will output a lot of information about the certificates served by the Seeq Server and a status message about the validity. Reading all the output is hard to describe in detail, but if there are connection issues that need investigation, this output will help Seeq with the investigation.
One common issue is that a Certificate Proxy server exists between a Seeq server in an internal corporate network and a public Seeq server outside of that network (in the cloud, for instance). In such cases, when running this command, you will observe that the certificate chain will start with the target server's DNS name (or wildcard) but will proceed to Certificate Authorities that are internal to the company's network instead of those in the actual seeq-cert.pem file used in the keys folder (usually commonly used public certificates. You can view the certificate chain on the seeq-cert.pem file by running this command:
openssl x509 -in certificate.crt -text -noout
Missing required fields
Browsers have specific requirements for what fields must be present in order for them to declare a certificate to be valid. A common field that is missing from a certificate is the Subject Alternate Name field. Google Chrome (and possibly others) will display a certificate error if this field is missing. The only resolution to this problem is to generate a new certificate signing request (CSR) with that field specified.
Mismatched Hostname/IP
The hostname or IP address that the user enters to navigate to Seeq must be listed as a name in the certificate. For example, the certificate may include the fully-qualified name (FQN) such as "https://seeq.customer.com". But if users accessed the Seeq server using only "https://seeq", the browser would reject the certificate and cause the connection to fail. Resolution to this problem is to generate a new certificate signing request (CSR) with the Subject Alternative Name (SAN) field populated with all possible hostnames or IP addresses that users might use to access the server.