Discuss this help topic in SecureBlackbox Forum

Validate the certificate using TElX509CertificateValidator

This how-to describes a simple approach of certificate validation which is normally sufficient for all applications. Those developers who need fine-grained validation with flexible tune-up of validation parameters are addressed to the how-to article. Basic information on certificate validation can be found in the mini-FAQ.

The following steps are needed to validate a certificate:

1. Check the integrity and validity of the certificate. The integrity means that the certificate data have not been altered in any way; moreover, each certificate is only valid for a limited period of time.
2. Check the certificate integrity with the Certificate Authority (CA) certificate.
3. Check certificate revocation status in Certificate Revocation Lists (CRLs) and using Online Certificate Status Protocol (OCSP). As CRLs and OCSP responses are signed using certificates, they also need to be validated, giving us extra certificate chains.

Eventually, validation of a single certificate means validation of a whole certificate tree. TElX509CertificateValidator class encapsulates all functionality necessary to perform this operation in one call. At the same time, the component is very flexible, and provides full control over the validation process.

Initialization

Before any certificate validation is performed, TElX509CertificateValidator object needs to be properly initialized. At this stage the specific information regarding the certificate(s) to be validated such as, e.g., trusted certificates, known CRLs and OCSP responses, should be loaded into memory. This is performed by the corresponding Clear* and Add* methods of TElX509CertificateValidator. On Windows, the system certificate stores are easily initialized with a single call to InitializeWinStorages, and are accessible via the corresponding WinStorage* properties. To use these stores, UseSystemStorages property should be set to True.
In addition, TElX509CertificateValidator allows to specify various validation options via its boolean properties, such as CheckValidityPeriodForTrusted, ImplicitlyTrustSelfSignedCertificates, etc.

Checking CRLs and OCSP responses

TElX509CertificateValidator internally uses SecureBlackbox CRL retriever and OCSP client classes to request CRLs and send OCSP requests. To use these classes, you have to explicitly reference/include the corresponding namespace/unit in your code depending on the edition, as described in the corresponding topic. These classes utilize TElHTTPSClient component of SecureBlackbox to fetch the necessary information, consequently, you need to have a license for a package that covers TElHTTPSClient. In some cases the CRL or OCSP response is available before validation, e.g., they are included in the signature of *AdES documents. Such CRLs and OCSP responses could be passed to TElX509CertificateValidator using AddKnownCRLs and AddKnownOCSPResponses methods. When you do not need to check the certificate revocation information, and hence there is no need in using HTTP transport, set OfflineMode property to True. To explicitly specify how the revocation information should be checked, use CheckCRL, CheckOCSP, MandatoryCRLCheck, and MandatoryOCSPCheck properties.

Validation

TElX509CertificateValidator offers a bunch of methods to validate different certificates depending on your needs.

• Validate is a general method to validate any X509 certificate.
• ValidateForSMIME is a specific method to validate S/MIME message signatures.
• ValidateForSSL allows to validate the certificates received during SSL/TLS communication.
• ValidateForTimestamping is used to check the validity of the certificates received during time-stamping protocol (TSP) communication.

All these methods return certificate's validity and validity reason that contains additional validation information. Note, that if validation fails (cvInvalid is returned), this is not something to report to our technical support, because TElX509CertificateValidator is supposed to return validation result even if the certificate is invalid.

Validation failure

Most common reasons for certificate invalidity are listed below.

1. Lack of certificates to build the chain (CA or Root certificates are not available).
2. Not trusted root certificate. Note, that by default self-signed certificates are not trusted, which is controlled by ImplicitlyTrustSelfSignedCertificates property.
3. Impossibility to retrieve the CRL or send OCSP request (includes network failures and the absence of license for HTTPS client).
4. Failure to use CRL or OCSP response (includes malformed responses and failure in validation of signature of the CRL or OCSP response).

Use OnAfterCertificateValidation, OnCRLError, and OnOCSPError events to handle the corresponding validation errors.
Additional information on certificate validation may be found in the mini-FAQ.

Certificate-related How To articles

Discuss this help topic in SecureBlackbox Forum