SecureBlackbox 2020 Node.js Edition

Questions / Feedback?

Validating TLS certificates

Certificate validation in TLS-able components

All TLS-capable components in version 2020 are configured to automatically validate server certificate chains against the local trust settings. This setup is different to that in versions 16 and ealier, where the users were ultimately responsible for implementing and integrating the entire validation part.

The main reason behind that change was the observation that many SecureBlackbox users implemented the validation piece improperly, or were not performing the validation altogether. The outcomes of incorrectly implemented validation routine were false sense of security and strong potential for compromise of the entire secure communication channel.

This default setup comes with two major implications:

First, any TLS endpoint you are connecting to has to be trusted in the local system for the connection to be successful. This means that the TLS certificate of the server endpoint has to chain up to a trusted root anchor. If the component fails to build that chain - for example due to the root certificate not being found or not being trusted - the following error will be returned:

TLS certificate validation failed: error 75788; the connection will be terminated

Please see the Troubleshooting section below to learn how to deal with TLS chain validation issues.

Second, the chain validation outcomes may differ when run on different systems - even if you are connecting to the same endpoint. Older or isolated systems may not have up-to-date information on trusted certificates, which will ultimately lead to chain validation failures.

One important remark that has to be made in this context concerns Linux. While Windows and Mac both have concepts of system-wide trust settings - for example, Windows does that through the extensive mechanism of system certificate stores - Linux doesn't operate a system-wide trust. Instead, every application that wants to validate TLS chains on Linux has to deploy its own set of trust anchors, and use it for building and validating third-party certificate chains.

SecureBlackbox partially addresses that matter by downloading missing root certificates on-demand from Windows Update. While this approach does its job in enabling connectivity with most public web sites across most connected plaforms, it may be unsuitable in certain scenarios. Please see the Tuning Up Chain Validation section below to learn about fine-tuning the validation routine in the client-side TLS endpoints.

Troubleshooting

Read along if you are concerned about chain validation issues due to the above or similar errors.

The first step when you come across a chain validation problem is about establishing the root cause. The chain validation is a complex, multi-step routine that involves validation of up to a dozen digital signatures and retrieval of up-to-date certificate status information from numerous CRL and OCSP responders. While certain failures in that chain of checks may be tolerated, the others may be fatal for the validation routine.

The most popular reason for the chain validation to fail, especially in development/debug environments, is the use of locally untrusted certificates. Any certificates that you generate for yourself, by using SecureBlackbox or third-party tools, are likely to be untrusted as they do not chain up to a trust anchor. Any attempt to use the component to connect to TLS services that use such certificates will lead to the certificate validation error (which really is manifestation of the component guarding your security, effectively rejecting connections to an untrusted endpoint), and you need to take steps to make such connections possible.

A good place to start with the investigation is the chain validation log. This is a very detailed step-by-step record of actions the component took to establish the validity of the server's certificate, with their respective outcomes. In any version 2020 component the log can be accessed via <component>.ConnectionInfo.ValidationLog property. The log is available for both successful and unsuccessful connection attempts, and can be checked as soon as OnCertificateValidate event fires. If using a version 16-style component, subscribe to its OnCertValidatorFinished event and read the log from the CertValidator.InternalLogger.Log.Text property.

The log should give you the idea of the root cause for the validation error. Search for the first entry that reports the validity as INVALID. The accompanying comment will provide the details. Note that there might be more than one reason for the same validation to fail, and you must deal with all of them.

Good to know. If you come across the SELF-SIGNED validity for any of the chain elements, this is a good indicator that the validation has failed due to the corresponding root certificate being untrusted in the system. You might be able to fix the validation by registering the certificate as trusted - see the Tuning Up Chain Validation section below.

Among the most typical reasons for chain validation failures are:

  • Untrusted root certificates - mostly observable in test/development environments
  • Missing root certificates (often happens on older/isolated systems)
  • Unavailability of revocation sources due to e.g. network restrictions
  • Certificate not suitable for use with the network endpoint (endpoint address or certificate key usage mismatch)
Looking through the validation log should give you the idea what kind of issue you are dealing with.

Good to know. You can temporarily disable certificate chain validation for debug purposes. This is a good option if your development/testing environment relies on untrusted certificates, and that fact slows down or inconveniences your development activities. You can disable the validation by setting <Component>.TLSSettings.AutoValidateCertificates to false (<Component>.AutoValidateCertificates in v16-style components), subscribing to OnCertificateValidate event, and returning Accept=true from the event handler.

Note that you should only disable the validation for testing and development purposes. Doing so in a production application undermines its security, and may lead to breaches and loss or disclosure of sensitive data.

Tuning Up Chain Validation

SecureBlackbox certificate chain validation module is highly-customisable and can suit any imaginable requirements. Among the configurable validation aspects are:

  • Revocation checking: prioritize one method over the other (OCSP in favour of CRL) or disable revocation checks entirely.
  • Provide your own sets of trusted and known certificates - handy on Linux and other environments with no built-in trust settings.
  • Offline mode: one-switch cutout of any online validation activity.
  • Easy certificate pinning.

Customizing revocation checks

Use <Component>.TLSSettings.RevocationCheck property to configure revocation checking. The property allows you to choose and prioritize between different combinations of OCSP and CRL mechanisms. Generally OCSP is better suited for TLS connections due to speed, making crcAnyOCSPOrCRL the recommended option.

You can fully disable revocation checks by setting this property to crcNone, in which case only the validity of the chain will be checked, but not the current status of the certificate.

Providing additional certificates

Use <Component>.TrustedCertificate and KnownCertificates properties to provide the certificates to complement to the default lists offered by the system. This may be particularly handy in environments that don't have their own system-wide certificate trust lists. On Linux, for example, you can borrow the root and CA certificates that are included with Firefox or Chrome distributions, and make them available to SecureBlackbox by adding them to these collections.

Certificate pinning

Certificate pinning is effectively telling the TLS component that a particular certificate is explicitly trusted - even though it doesn't chain up to a trust anchor and has no reference in the revocation sources. Certificate pinning is often used in intranet environments which don't rely on global trust offered by public CAs.

Pinning a certificate is as simple as adding it to the component's TrustedCertificates collection.

Bespoke validation

In some cases you may need even more fine-grained control over the validation. In this case you may consider switching off the internal mechanism used by SecureBlackbox by default, and implementing the validation routine manually. Certificatevalidator component may come handy in doing that.

The internal routine can be switched off by setting <Component>.TLSSettings.AutoValidateCertificates to false, and subscribing to OnCertificateValidate event (OnTLSCertValidate in some components). Inside the event handler you need to perform the validation in accordance with your bespoke requirements. The server certificate object and any accompanying chain can be accessed via the <Component>.ServerChain collection. The server's certificate itself always comes first in this collection, and the rest of the chain follows.

Having completed the bespoke validation routine, adjust the event's Accept parameter in accordance with the validation result.

CertificateValidator component may be very helpful in implementing the bespoke validation routine. It allows to tune up the validation process to the minute detail, and provides such features as offline validation, cache control, and timeout setup.

Summary

Certificate validation is a crucial component of the overal security provided by the TLS connection. Please set it up responsibly to make sure your secure channel is really secure - and SecureBlackbox will take care of the rest.

Copyright (c) 2022 /n software inc. - All rights reserved.
SecureBlackbox 2020 Node.js Edition - Version 20.0 [Build 8165]