TElX509CertificateValidator.ValidateForSSL method

Discuss this help topic in SecureBlackbox Forum

TElX509CertificateValidator.ValidateForSSL

TElX509CertificateValidator See also

Filter: C# VB.NET Pascal C++ PHP Java

Use this method to check validity of the certificates received from the remote party in SSL/TLS communication.

Declaration

[C#]
void ValidateForSSL(TElX509Certificate Certificate, string DomainName, string IPAddress, TSBHostRole HostRole, TElCustomCertStorage AdditionalCertificates, bool CompleteChainValidation, DateTime ValidityMoment, ref TSBCertificateValidity Validity, ref TSBCertificateValidityReason Reason);
void ValidateForSSL(TElX509Certificate Certificate, string DomainName, string IPAddress, TSBHostRole HostRole, TElCustomCertStorage AdditionalCertificates, bool CompleteChainValidation, DateTime ValidityMoment, bool InternalValidation, ref TSBCertificateValidity Validity, ref TSBCertificateValidityReason Reason);

[VB.NET]
Sub ValidateForSSL(ByVal Certificate As TElX509Certificate, ByVal DomainName As String, ByVal IPAddress As String, ByVal HostRole As TSBHostRole, ByVal AdditionalCertificates As TElCustomCertStorage, ByVal CompleteChainValidation As Boolean, ByVal ValidityMoment As DateTime, ByRef Validity As TSBCertificateValidity, ByRef Reason As TSBCertificateValidityReason)
Sub ValidateForSSL(ByVal Certificate As TElX509Certificate, ByVal DomainName As String, ByVal IPAddress As String, ByVal HostRole As TSBHostRole, ByVal AdditionalCertificates As TElCustomCertStorage, ByVal CompleteChainValidation As Boolean, ByVal ValidityMoment As DateTime, ByVal InternalValidation As Boolean, ByRef Validity As TSBCertificateValidity, ByRef Reason As TSBCertificateValidityReason)

[Pascal]
procedure ValidateForSSL(Certificate : TElX509Certificate; DomainName : string; IPAddress : string; HostRole : TSBHostRole; AdditionalCertificates : TElCustomCertStorage; CompleteChainValidation : boolean; ValidityMoment : TDateTime; var Validity : TSBCertificateValidity; var Reason : TSBCertificateValidityReason);
procedure ValidateForSSL(Certificate : TElX509Certificate; DomainName : string; IPAddress : string; HostRole : TSBHostRole; AdditionalCertificates : TElCustomCertStorage; CompleteChainValidation : boolean; ValidityMoment : TDateTime; InternalValidation : boolean; var Validity : TSBCertificateValidity; var Reason : TSBCertificateValidityReason);

[C++]
    void ValidateForSSL(TElX509Certificate &Certificate, const std::string &DomainName, const std::string &IPAddress, TSBHostRole HostRole, TElCustomCertStorage &AdditionalCertificates, bool CompleteChainValidation, int64_t ValidityMoment, TSBCertificateValidity &Validity, TSBCertificateValidityReason &Reason);
    void ValidateForSSL(TElX509Certificate *Certificate, const std::string &DomainName, const std::string &IPAddress, TSBHostRole HostRole, TElCustomCertStorage *AdditionalCertificates, bool CompleteChainValidation, int64_t ValidityMoment, TSBCertificateValidity &Validity, TSBCertificateValidityReason &Reason);
    void ValidateForSSL(TElX509Certificate &Certificate, const std::string &DomainName, const std::string &IPAddress, TSBHostRole HostRole, TElCustomCertStorage &AdditionalCertificates, bool CompleteChainValidation, int64_t ValidityMoment, bool InternalValidation, TSBCertificateValidity &Validity, TSBCertificateValidityReason &Reason);
    void ValidateForSSL(TElX509Certificate *Certificate, const std::string &DomainName, const std::string &IPAddress, TSBHostRole HostRole, TElCustomCertStorage *AdditionalCertificates, bool CompleteChainValidation, int64_t ValidityMoment, bool InternalValidation, TSBCertificateValidity &Validity, TSBCertificateValidityReason &Reason);

[PHP]
void ValidateForSSL(TElX509Certificate $Certificate, string $DomainName, string $IPAddress, integer $HostRole, TElCustomCertStorage $AdditionalCertificates, bool $CompleteChainValidation, DateTime $ValidityMoment, integer &$Validity, integer &$Reason)
void ValidateForSSL(TElX509Certificate $Certificate, string $DomainName, string $IPAddress, integer $HostRole, TElCustomCertStorage $AdditionalCertificates, bool $CompleteChainValidation, DateTime $ValidityMoment, bool $InternalValidation, integer &$Validity, integer &$Reason)

[Java]
void validateForSSL(TElX509Certificate Certificate, String DomainName, String IPAddress, TSBHostRole HostRole, TElCustomCertStorage AdditionalCertificates, boolean CompleteChainValidation, Date ValidityMoment, TElX509CertificateValidatorResult Res);
void validateForSSL(TElX509Certificate Certificate, String DomainName, String IPAddress, TSBHostRole HostRole, TElCustomCertStorage AdditionalCertificates, boolean CompleteChainValidation, Date ValidityMoment, boolean InternalValidation, TElX509CertificateValidatorResult Res);

Parameters

AdditionalCertificates - Additional certificates that might be known or obtained during the handshake.
Certificate - Certificate to be validated.
CompleteChainValidation - Specifies whether to check issuer (CA) certificates when the certificate is invalid.
DomainName - Domain name of the host, whose certificate is validated. Can be empty, if it is not known.
HostRole - The role of the remote host. Can be none (then the key usage is not checked against the role), server, client or both.
IPAddress - IP address of the host, whose certificate is validated. Can be empty if it is not known.
InternalValidation - specifies if internal validation should be performed.
Reason - On return contains validity status reasons of the certificate.
Validity - On return contains validity status of the certificate.
ValidityMoment - Specifies the time when the certificate must be valid (i.e. the moment of handshake).
Res -

Host roles

[.NET] [C++]	[Pascal]	Description
hrNone = 0	hrNone	Host has no role
hrServer = 1	hrServer	Host is a server
hrClient = 2	hrClient	Host is a client
hrBoth = 3	hrBoth	Host can be both client and server

Validity values

[.NET] [C++]	[Pascal]	Description
cvOk = 0	cvOk	Certificate was validated successfully and is valid
cvSelfSigned = 1	cvSelfSigned	Certificate is self signed
cvInvalid = 2	cvInvalid	Certificate is invalid
cvStorageError = 3	cvStorageError	Certificate was not validated due to certificate storage error
cvChainUnvalidated = 4	cvChainUnvalidated	Certificate chain was not validated because while the certificate itself is valid, one or more of CA Certificates in the chain have validation problems

Validity reasons

[.NET]	[Pascal]	[C++]	Description
vrBadData = 1	vrBadData	f_vrBadData = 1	Invalid certificate format or certificate is corrupted
vrRevoked = 2	vrRevoked	f_vrRevoked = 2	Certificate is revoked by Issuer
vrNotYetValid = 4	vrNotYetValid	f_vrNotYetValid = 4	Certificate is not valid yet
vrExpired = 8	vrExpired	f_vrExpired = 8	Certificate is expired
vrInvalidSignature = 16	vrInvalidSignature	f_vrInvalidSignature = 16	Certificate contains invalid digital signature, it could be corrupted
vrUnknownCA = 32	vrUnknownCA	f_vrUnknownCA = 32	Issuer (CA) certificate was not found.
vrCAUnauthorized = 64	vrCAUnauthorized	f_vrCAUnauthorized = 64	Issuer (CA) certificate was found but its key usage fields don't allow use of this certificate for signing other certificates.
vrCRLNotVerified = 128	vrCRLNotVerified	f_vrCRLNotVerified = 128	Certificate Revocation List for this certificate could not be retrieved and/or validated.
vrOCSPNotVerified = 256	vrOCSPNotVerified	f_vrOCSPNotVerified = 256	OCSP response for this certificate could not be retrieved and/or validated.
vrIdentityMismatch = 512	vrIdentityMismatch	f_vrIdentityMismatch = 512	Provided certificate doesn't include the specified name and / or IP address. Either the remote side in TLS or sender in S/MIME is misconfigured, or the certificate is misused by the remote side or sender, or authenticity of the remote side or sender is forged.
vrNoKeyUsage = 1024	vrNoKeyUsage	f_vrNoKeyUsage = 1024	Provided certificate may not be used for chosen activity (identifying TLS server or client or S/MIME message sender)
vrBlocked = 2048	vrBlocked	f_vrBlocked = 2048	Provided certificate has been found in the list of blocked certificates
vrFailure = 4096	vrFailure	f_vrFailure = 4096	Validation took too long, aborted
vrChainLoop = 8192	vrChainLoop	f_vrChainLoop = 8192	Certificate chain includes a loop. Further validation is not possible.
vrWeakAlgorithm = 16384	vrWeakAlgorithm	f_vrWeakAlgorithm = 16384	One of certificates is signed using the weak hash algorithm

Description

Use this method to validate the certificate received during SSL / TLS handshake (e.g., via OnCertificateValidate event of SSL components). You need to pass the end-entity certificate only - CA certificates will be retrieved via Certificate's Chain property. So the event handler for OnCertificateValidate should look like this (in pseudocode):

			
if (Certificate.Chain = null) or (Certificate.Chain.Certificates[0] = Certificate) then
Validator.ValidateForSSL(Certificate, …)

If the chain is not available, you can pass CA certificates via AdditionalCertificates parameter or using AddKnownCertificates() method.

The method checks whether the certificate subject and names correspond to given domain name or IP address. Next certificate's Key Usage fields are checked to ensure that the certificate may be used for TLS handshake. Finally, Validate() method is called to validate the certificate itself.

Domain name and IP address of the other party can be obtained via RemoteHost and RemoteIP properties of SSL classes (TElHTTPSClient, TElSimpleFTPSClient, TElSMTPClient).

When CompleteChainValidation = true and the certificate is found to be not valid, certificate validation continues, i.e. issuer (CA) certificates are validated as well. This lets you create validation report which should include all certificates in the chain. When CompleteChainValidation = false and the certificate is not valid, further validation is not performed and Validate() method returns immediately.

Since version 13 ResetCertificateCache parameter has been replaced with ResetCertificateCache class method.

See also: ResetCertificateCache Validate ValidateForSMIME ValidateForTimestamping

Discuss this help topic in SecureBlackbox Forum