Discuss this help topic in SecureBlackbox Forum

Validate certificate

Validating an X.509 certificate is a tougher task than it might appear at first. A typical validation process involves the following steps:

1. Validating integrity of all certificates forming the certifcate chain by checking their digital signatures, from the certificate being validated down to the chain's root certificate.
2. Ensuring that none of the certificates in the chain is revoked. This is done by contacting revocation information sources such as CRL and OCSP responders.
3. Ensuring that every certificate in the chain is fit for purpose (e.g., checking that a certificate that acts as an intermediate CA was actually given this right).
4. Ensuring that the main chain or subchain and all secondary chains (those of the CRLs and OCSP signatories) end with a trusted entry.

For web and mail certificates some additional checks (establishing that the certificate is valid for use at this particular web address, etc.) are also performed.

With SecureBlackbox you normally perform certificate validation using the TElX509CertificateValidator component. This powerful component can performs all the above activities. What you need to do is create the component (note that you may create a single instance of the validator component and re-use it from different parts of your code), set it up and call one of its Validate() methods. The following settings are available:

• AddTrustedCertificates(TElCustomCertStorage storage) adds a list of trusted certificates to the validator's internal list. All certificates contained in storage become 'trust anchors' for the validator, hence all chains or subchains ending with one of these certificates will be considered trusted. If you maintain a list of trusted root CA certificates somewhere, AddTrustedCertificates is a good place to get the validator familiar with them.
• AddBlockedCertificates(TElCustomCertStorage storage) adds a list of blocked (non-trusted) certificates. Any chain or subchain ending with a blocked certificate is considered not trusted.
• AddKnownCertificates(TElCustomCertStorage storage) adds a list of known certificates to the validator. While not having a trust entry assigned to them, known certificates are used by the validator to build chains. A list of intermediate CA certificates might go there.
• AddKnownCRLs(), AddKnownOCSPResponses() add the lists of known CRLs or known OCSP responses, respectively.
• IgnoreSystemTrust: if enabled, this option tells Validator to disregard trust of the certificates stored in the system-wide Trusted Root Certification Authorities store.
• UseSystemStorages specifies whether the validator should use system certificate stores.
• CheckCRL and CheckOCSP specify whether CRL and OCSP validation mechanisms should be used at all.
• CheckValidityPeriodForTrusted property specifies whether the validity period should be checked for conformance of the explicitly trusted certificates.
• IgnoreCAKeyUsage, IgnoreRevocationKeyUsage, IgnoreSSLKeyUsage, IgnoreBadOCSPChains, IgnoreCABasicConstraints, IgnoreCANameConstraints: allow to relax certain standard-enforced requirements for better compatibility with buggy software.
• MandatoryCRLCheck, MandatoryOCSPCheck specify whether CRL and OCSP channels must be checked if they are provided for a certificate (if any of them can not be checked, validation fails).
• MandatoryRevocationCheck enabled forces entire validation to fail in the absence of any (CRL or OCSP) revocation check.
• ForceCompleteChainValidationForTrusted forces a complete chain validation for trusted certificates.
• ForceRevocationCheckForRoot forces a revocation check for root certificates.
• Switch on OfflineMode to perform validation without contacting any online revocation sources. All revocation elements and certificates are expected to be fed to the validator via AddKnownXXX() methods for this mode to work.
• RevocationMomentGracePeriod specifies the period of time allowed between OCSP response or CRL expiration time and the validation moment.
• Please, do not switch the ImplicitlyTrustSelfSignedCertificates property on unless for debug purposes. It makes the validator trust all self-signed certificates, which is extremely dangerous.
• RevocationCheckPreference sets the order of revocation checks.

For your convenience, the following Validate() methods are provided:

• void Validate(TElX509Certificate certificate, TElCustomCertStorage additionalCertificates, bool completeChainValidation, bool validationMoment, ref TSBCertificateValidity validity, ref TSBCertificateValidityReason reason);
• void Validate(TElX509Certificate certificate, TSBCertificateValidity validity, ref TSBCertificateValidityReason reason);
• void ValidateForSMIME(TElX509Certificate certificate, string eMailAddress, TElCustomCertStorage additionalCertificates, bool completeChainValidation, bool validationMoment, ref TSBCertificateValidity validity, ref TSBCertificateValidityReason reason);
• void ValidateForSSL(TElX509Certificate certificate, string domainName, string ipAddress, TSBHostRole hostRole, TElCustomCertStorage additionalCertificates, bool completeChainValidation, bool validationMoment, ref TSBCertificateValidity validity, ref TSBCertificateValidityReason reason);
• void ValidateForTimestamping(TElX509Certificate certificate, TElCustomCertStorage additionalCertificates, bool completeChainValidation, bool validationMoment, ref TSBCertificateValidity validity, ref TSBCertificateValidityReason reason);

The set of parameters is essentially the same, yet for SSL and S/MIME modes some additional protocol-related parameters are required. The meaning of these parameters is best explained by the following code snippet:

validator.ValidateForSSL(cert,
"www.secureblackbox.com",	     // TLS server address
"192.192.192.192",	// TLS server IP address
TSBHostRole.hrServer,	// TLS endpoint role (server)
chain,	// additional certificates = chain provided by the server
true,	// yes, we need to validate the whole chain
DateTime.UtcNow,	// and the validation moment is current time
ref validity,
ref reason
);

Validate() methods return the validation result via two by-reference parameters, validity and reason. The validity parameter indicates general certificate status (cvOk, cvSelfSigned, cvInvalid, cvStorageError, cvChainUnvalidated). The reason parameter provides more details about the reason for validation failure (vrBadData, vrRevoked, vrNotYetValid, vrExpired, vrInvalidSignature, vrUnknownCA, vrCAUnauthorized, vrCRLNotVerified, vrOCSPNotVerified, vrIdentityMismatch, vrNoKeyUsage, vrBlocked).

Validation process is complicated and depends on a number of external parties. Sometimes finding out the reason of a particular validation failure might be rather challenging. For convenience, TElX509CertificateValidator keeps a detailed textual of its operations. The log can be accessed via the TElX509CertificateValidator.InternalLogger.Log.Text property.

How To articles about TElX509CertificateValidator

Discuss this help topic in SecureBlackbox Forum