The majority of Forum Sentry use cases include securing web service APIs and web sites with TLS/SSL. This is for a very good reason and one of several important security measures to apply with Forum Sentry. Security via TLS/SSL is enabled on the Sentry network listener policies. Whether the listener policies are HTTPS, FTPS, or one of the many JMS protocols supported, this will require an SSL Termination policy.
When the TLS/SSL connection into the Sentry listener policy fails, it is not always apparent where the issue lays. Depending on when the failure occurs, there may not be useful information in the Sentry log file. This article will discuss common causes of TLS/SSL Termination issues in Sentry and remediation steps for each.
I. Forum Sentry SSL Termination Glossary
CA – Certificate Authority, responsible for issuing digital certificates that are used with TLS/SSL among other things. CAs may be public (Verisign, Entrust, Thawte, DigiCert, etc…) or private. Typically a Sentry admin will generate a key in Sentry, creating either a self-signed certificate or a certificate signing request (CSR), which is then provide to the CA to be signed. Sentry can also act as a CA.
Cipher Suites – A cipher suite is a named combination of authentication, encryption, and message authentication code (MAC) algorithms used to negotiate the security settings for a network connection using the TLS/SSL protocol. In Sentry there are many cipher suite options, and admins can choose to enable/disable specific cipher suites, including null ciphers.
Key Pair – In Sentry, a Key Pair is a full private key with the corresponding public certificate.
Self-Signed Certificate – A self-signed certificate is an identity certificate that is signed by the same entity whose identity it certifies. All Root CA Certificates are self-signed certificates. To determine if a certificate is self-signed, check to see if the issuer=subject. Sentry can generate self-signed certificates.
Signer Groups – In Sentry a Signer Group contains the intermediate and root CA certificates that are used with the path validation of an end user certificate. Other options within a Signer Group are certificate revocation (CRL Policies) and an option to send the client a “hint” or list of the CA certificates in the Signer Group during the SSL handshake (Send Accepted Issuers). Signer Groups are used with SSL policies, signature verification policies, and encryption policies in Sentry.
SSL Client Authentication – With an SSL Termination policy in Sentry, SSL client authentication is enabled with the “Authenticate the Client” option. When this option is enabled, Sentry will perform the X.509 Certificate Path Validation for the client certificate provided.
TLS/SSL Handshake – This term refers to the process by which a client and server establish a secure TLS/SSL tunnel that data will then be transmitted over. For more details and the specific steps of the handshake see: http://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_handshake
X.509 Certificate Path Validation – Path validation in Sentry involves processing public key certificates and their issuer certificates in a hierarchical fashion until the certification path terminates at a trusted, self-signed certificate (the root CA certificate) where the subject=issuer. If there is a problem with one of the certificates in the path, or if Sentry cannot find a certificate in the trust chain, the certification path is considered a non-trusted certification path and Sentry will fail the SSL handshake. A typical certification path includes a root certificate and one or more intermediate certificates. Sentry will use the end user certificate and any intermediate certificates provided during the SSL handshake to build the trust chain; however, the root CA certificate has to exist in a Sentry signer group. The Forum Sentry X509 Path validation has been certified by the US Department of Defense per compliance to RFC 3280 “Internet X.509 Public Key Infrastructure”.
II. Examples of SSL Termination Problems and Solutions
SSL Client Authentication Failure – Sentry fails to validate the client certificate provided.
Solution 1. Ensure that the appropriate intermediate and root CA certificates are included in the Signer Group associated to the SSL Termination Policy.
Solution 2. Ensure that the client is configured with a full key pair (private and public certificate) as this is required for a valid SSL handshake with mutual authentication. A private key is required on the client side when the client is required to provide a specific client certificate to Sentry.
Solution 3. If the “Associate subject DN to a user” option is enabled, ensure the client certificate is associated to a user in the selected ACL policy. If the user is in LDAP, you may need to enable the “Use user attribute only” option.
Solution 4. Check the Sentry log to determine if the failure is due to the client certificate failing the certificate revocation check (CRL).
SSL Server Authentication Failure – the client fails to validate the Sentry server certificate.
Solution 1. Ensure the client (browser, mobile app, b2b app, etc…) is configured with the appropriate CA certificates necessary to validate the server certificate provided by Sentry.
Popular web browsers already include many public CA certificates (intermediate and roots) and server certificate validation is typically enabled by default. Therefore, if the Sentry server certificate was signed by a commonly used public CA (Verisign, Entrust, DigiCert, etc.) a browser will likely be able to verify the Sentry server certificate without issue. If the browser can’t validate the Sentry certificate, usually an SSL warning is displayed or the connection may fail – depending on the browser settings.
If the necessary CA certs are not installed in the browser, or if a different type of client application is used, the client will need to be configured with the appropriate CA certificates that are used to validate the Sentry server certificate provided during the SSL handshake.
Solution 2. Some clients may require that Sentry (the server) provide the intermediate CA and root CA certificates, associated to the server certificate, during the SSL handshake. This is possible only when the intermediate and CA certificates are stored in the Sentry keystore within the same key pair that is associated to the SSL Termination policy.
In other words, if the key pair only shows an end user certificate when you view it (and not the full chain) this may be a problem. The solution is to combine the end user public certificate, any intermediate CA certificates, and the root CA certificate together into a pkcs7 file and then import that on top of the key pair. This can be done with the OpenSSL command line tool.
III. Troubleshooting Recommendations
Troubleshooting Mutual Authentication Issues:
Disable the client authentication option in the SSL Termination policy and test again. If the connection now succeeds, the issue is likely with Sentry validating the client certificate against the Signer Group. If the connection still fails, it is likely the client failing to validate the Sentry server certificate.
If possible, disable the server certificate validation on the client application. Test again to see if the connection succeeds. If it does, it points to server certificate validation as the problem. This should be a testing step only, to identify the problem. Ensure the correct CA certs are installed on the client or provided by Sentry so that the client can successfully validate the server certificate.
If the issue is related to client authentication, test the connection with your own client application using a test key pair. This key pair can be imported into both the client application and Sentry and be used as both the client and server key. This will help identify if the problem is related to the specific keys used. Contact Forum Systems Support for a sample test key pair with a full certificate chain.
Protocol or Cipher Suite Issues:
If the issue is not related to mutual authentication, it could be that the client does not support, or is incorrectly using, one of the TLS/SLS protocols enabled on the SSL Termination policy in Sentry. In the SSL Termination policy, try changing which TLS/SSL protocols are enabled.
It could be that the client does not support an enabled cipher suite in the SSL Termination policy, or that it does not correctly implement the cipher suite that was chosen during the SSL handshake. Try disabling / enabling different ciphers suites. For instance, enable the weaker CBC ciphers which are disabled in Sentry by default. It is recommended that you require the client to support the most secure cipher suites.
Try using null ciphers with the SSL Termination policy. The use of null ciphers is never recommended for production traffic and should only be used for testing. In order to see the null ciphers option on the SSL Termination policy, first enable this option on the System>>Settings>>Preferences page.
Sentry Diagnostics:
Check the Sentry system log at DEBUG level for any specific errors related to the SSL connection. Depending on when the failure occurs, there may only be a single log message indicate an SSL connection was made. If this is the case, a packet capture will be required to troubleshoot further.
If the failure occurs while mapping the certificate to a user, this should be shown in the log at DEBUG level.
If the failure occurs due to certificate revocation, this should be shown in the log at DEBUG level.
Packet captures may be necessary to diagnose the reason for the failed SSL handshake. A packet capture may show which certificates are provided by each side and where in the handshake the failure occurs. It is best to take a capture on both the client side and the Sentry side at the same time. With the Sentry appliances, there is a packet capture utility under the Diagnostics menu. With Sentry software instances, the packet capture will need to be taken via another tool such as Wireshark or TCP dump. Regardless of how the capture is taken, the file can usually be reviewed with Wireshark.
To learn more visit our tutorials on API Security