CertificateValidator Component

Properties   Methods   Events   Config Settings   Errors  

The CertificateValidator component provides fine-grained validation of X.509 certificates.

Syntax

TsbxCertificateValidator

Remarks

This is a powerful and configurable component which can be used to validate all kinds of certificates and their chains.

The purpose of CertificateValidator is to validate certificate chains according to the X.509 specification. It supports a variety of technologies, including CRL and OCSP services, and can provide a comprehensive output on the certificate cryptographic validity, chain integrity, and trust levels. CertificateValidator is used internally in many other SecureBlackbox components, such as PDFSigner, HTTPClient, and OfficeVerifier.

To validate a certificate, please tune up the component as following:

• Assign the certificate to be validated to the Certificate property.
• Set RevocationCheck in accordance with your revocation check preferences.
• Enable UseSystemCertificates property to trust certificates that are trusted by the operating system. Copy any certificates that are not available in the standard system locations to KnownCertificates and TrustedCertificates collections (see Note 1 below).
• Optionally, adjust TLSSettings and SocketSettings.
• Adjust ValidationMoment if you would like to check the certificate validity at a different moment in time. Leave it unchanged to validate the certificate at the current time moment.
• Call Validate or ValidateForSSL method to initiate chain validation.

Depending on the complexity of the chain and the configuration of the component, the validation routine may take certain amount of time. The validator reports chain validation progress using a selection of events, such as BeforeCertificateProcessing, AfterCertificateProcessing, and CRLDownloaded events. It may also ask you for missing objects using CRLNeeded or CACertificateNeeded events. In each such event handler you can access the currently validated certificate via the CurrentCertificate property, and the interim validity figures via the InterimValidationResult and InterimValidationDetails property.

The return of the Validate (or similar) method indicates the completion of the validation procedure. The outcome of the chain validation is represented with the two parameters:

• ChainValidationResult reports the general validation outcome: valid, valid-but-untrusted, invalid, and unknown. As a rule, only the valid result can be taken as a good reason to consider the chain valid.
• ChainValidationDetails provides insights into the factors that caused the validation to fail.

Apart from these two parameters, you can check the low-level validation details by consulting the ValidationLog property. The validation log is often a great source for tracking and reacting to various validation issues.

Note 1: On Windows, CertificateValidator can use CA and ROOT system stores to look for any missing CA certificates and trust anchors. No similar functionality is currently available for other platforms, so in most cases you must provide your own list of trusted and CA certificates via TrustedCertificates and KnownCertificates collections to have your chains validate fully in Linux and macOS projects.

Note 2: The OfflineMode property is a handy way to check the completeness of your revocation/validation information. When the offline mode is on, CertificateValidator won't go online for any missing certificates, CRLs, and OCSP responses. Paired with a switched-off UseSystemCertificates property, it allows to make sure that any content provided via KnownCertificates, KnownCRLs, and KnownOCSPs represents the complete set of validation information required to validate the chain.

Property List

---

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

BlockedCertificates Property (CertificateValidator Component)

The certificates that must be rejected as trust anchors.

Syntax

property BlockedCertificates: TsbxCertificateList read get_BlockedCertificates write set_BlockedCertificates;

Remarks

Use this property to provide a list of compromised or blocked certificates. Any chain containing a blocked certificate will fail validation.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

CacheValidationResults Property (CertificateValidator Component)

Enables or disables validation result caching.

Syntax

property CacheValidationResults: Boolean read get_CacheValidationResults write set_CacheValidationResults;

Default Value

false

Remarks

Set this property to True to enable caching of validation results.

Certificate Property (CertificateValidator Component)

The certificate to be validated.

Syntax

property Certificate: TsbxCertificate read get_Certificate write set_Certificate;

Remarks

Assign the certificate that needs to be validated to this property.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

ChainValidationDetails Property (CertificateValidator Component)

The details of a certificate chain validation outcome.

Syntax

property ChainValidationDetails: Integer read get_ChainValidationDetails;

Default Value

0

Remarks

Use the value(s) returned by this property to identify the reasons that contributed to the overall validation result.

Returns a bit mask of the following options:

This property is read-only and not available at design time.

ChainValidationResult Property (CertificateValidator Component)

The general outcome of a certificate chain validation routine. Use ChainValidationDetails to get information about the reasons that contributed to the validation result.

Syntax

property ChainValidationResult: TsbxChainValidities read get_ChainValidationResult;

TsbxChainValidities = (
  cvtValid,
  cvtValidButUntrusted,
  cvtInvalid,
  cvtCantBeEstablished
);

Default Value

cvtValid

Remarks

Available options:

Use the ValidationLog property to access the detailed validation log.

This property is read-only and not available at design time.

CurrentCACertificate Property (CertificateValidator Component)

The CA of the currently processed certificate.

Syntax

property CurrentCACertificate: TsbxCertificate read get_CurrentCACertificate;

Remarks

The validator component uses this property to publish the issuer certificate of the certificate that is currently being processed, if it is available.

This property is read-only and not available at design time.

Please refer to the Certificate type for a complete list of fields.

CurrentCertificate Property (CertificateValidator Component)

The certificate that is currently being processed.

Syntax

property CurrentCertificate: TsbxCertificate read get_CurrentCertificate;

Remarks

This property returns the certificate that is currently being processed by the validator.

This property is read-only and not available at design time.

Please refer to the Certificate type for a complete list of fields.

FIPSMode Property (CertificateValidator Component)

Reserved.

Syntax

property FIPSMode: Boolean read get_FIPSMode write set_FIPSMode;

Default Value

false

Remarks

This property is reserved for future use.

GracePeriod Property (CertificateValidator Component)

Specifies a grace period to apply during certificate validation.

Syntax

property GracePeriod: Integer read get_GracePeriod write set_GracePeriod;

Default Value

0

Remarks

Use this property to specify a grace period (in seconds). Grace period applies to certain subprotocols, such as OCSP, and caters to the inaccuracy and/or missynchronization of clocks on different participating systems. Any time deviations within the grace period will be tolerated.

InterimValidationDetails Property (CertificateValidator Component)

Contains the validation details of the moment.

Syntax

property InterimValidationDetails: Integer read get_InterimValidationDetails write set_InterimValidationDetails;

Default Value

0

Remarks

Over the course of the validation process, the validator maintains an interim validity status for the chain that is being processed. This status is influenced by every single step of the validation routine, and may change along the way, before the end of the chain is reached and the final validation conclusion is drawn.

Use this property to check the interim validity details mid-flight.

The value of this property is a bit mask of the following options:

This property is not available at design time.

InterimValidationResult Property (CertificateValidator Component)

Contains the validation status of the moment.

Syntax

property InterimValidationResult: TsbxChainValidities read get_InterimValidationResult write set_InterimValidationResult;

TsbxChainValidities = (
  cvtValid,
  cvtValidButUntrusted,
  cvtInvalid,
  cvtCantBeEstablished
);

Default Value

cvtValid

Remarks

Over the course of the validation process, the validator maintains an interim validity status for the chain that is being processed. This status is influenced by every single step of the validation routine, and may change along the way, before the end of the chain is reached and the final validation conclusion is drawn.

Use this property to check the interim validity status mid-flight.

This property is not available at design time.

KnownCertificates Property (CertificateValidator Component)

Additional certificates for chain validation.

Syntax

property KnownCertificates: TsbxCertificateList read get_KnownCertificates write set_KnownCertificates;

Remarks

Use this property to supply a list of additional certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when intermediary CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of the certificates to be added to this collection is roughly equivalent to that of the Intermediate Certification Authorities system store in Windows.

Do not add trust anchors or root certificates to this collection: add them to TrustedCertificates instead.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

KnownCRLs Property (CertificateValidator Component)

Additional CRLs for chain validation.

Syntax

property KnownCRLs: TsbxCRLList read get_KnownCRLs write set_KnownCRLs;

Remarks

Use this property to supply additional CRLs that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated CRLs are stored separately from the signed message or document.

This property is not available at design time.

Please refer to the CRL type for a complete list of fields.

KnownOCSPs Property (CertificateValidator Component)

Additional OCSP responses for chain validation.

Syntax

property KnownOCSPs: TsbxOCSPResponseList read get_KnownOCSPs write set_KnownOCSPs;

Remarks

Use this property to supply additional OCSP responses that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated OCSP responses are stored separately from the signed message or document.

This property is not available at design time.

Please refer to the OCSPResponse type for a complete list of fields.

MaxValidationTime Property (CertificateValidator Component)

Specifies the maximum time the validation process may take.

Syntax

property MaxValidationTime: Integer read get_MaxValidationTime write set_MaxValidationTime;

Default Value

0

Remarks

Use this property to limit the amount of time available for the validator to carry out the validation. If the validation process exceeds this time, it is terminated and the validation error is returned.

OfflineMode Property (CertificateValidator Component)

Switches the component to offline mode.

Syntax

property OfflineMode: Boolean read get_OfflineMode write set_OfflineMode;

Default Value

false

Remarks

When working in offline mode, the component restricts itself from using any online revocation information sources, such as CRL or OCSP responders.

Offline mode may be useful if there is a need to verify the completeness of the validation information included within the signature or provided via KnownCertificates, KnownCRLs, and other related properties.

Proxy Property (CertificateValidator Component)

The proxy server settings.

Syntax

property Proxy: TsbxProxySettings read get_Proxy;

Remarks

Use this property to tune up the proxy server settings.

This property is read-only.

Please refer to the ProxySettings type for a complete list of fields.

QualifiedInfo Property (CertificateValidator Component)

The qualified details for the validated certificate.

Syntax

property QualifiedInfo: TsbxQualifiedInfo read get_QualifiedInfo;

Remarks

Use this property to check the qualified information for Certificate. The contents of this property is updated upon completion of the full validation routine performed by the Validate method (if the qualified check is enabled) or after the GetQualifiedStatus call.

This property is read-only.

Please refer to the QualifiedInfo type for a complete list of fields.

RevocationCheck Property (CertificateValidator Component)

Specifies the kind(s) of revocation check to perform for all chain certificates.

Syntax

property RevocationCheck: TsbxRevocationCheckKinds read get_RevocationCheck write set_RevocationCheck;

TsbxRevocationCheckKinds = (
  crcNone,
  crcAuto,
  crcAllCRL,
  crcAllOCSP,
  crcAllCRLAndOCSP,
  crcAnyCRL,
  crcAnyOCSP,
  crcAnyCRLOrOCSP,
  crcAnyOCSPOrCRL
);

Default Value

crcAuto

Remarks

Revocation checking is necessary to ensure the integrity of the chain and obtain up-to-date certificate validity and trustworthiness information.

Certificate Revocation Lists (CRLs) and Online Certificate Status Protocol (OCSP) responses serve the same purpose of ensuring that the certificate had not been revoked by the Certificate Authority (CA) at the time of use. Depending on your circumstances and security policy requirements, you may want to use either one or both of the revocation information source types.

This setting controls the way the revocation checks are performed for every certificate in the chain. Typically certificates come with two types of revocation information sources: CRL (certificate revocation lists) and OCSP responders. CRLs are static objects periodically published by the CA at some online location. OCSP responders are active online services maintained by the CA that can provide up-to-date information on certificate statuses in near real time.

There are some conceptual differences between the two. CRLs are normally larger in size. Their use involves some latency because there is normally some delay between the time when a certificate was revoked and the time the subsequent CRL mentioning that is published. The benefits of CRL is that the same object can provide statuses for all certificates issued by a particular CA, and that the whole technology is much simpler than OCSP (and thus is supported by more CAs).

This setting lets you adjust the validation course by including or excluding certain types of revocation sources from the validation process. The crcAnyOCSPOrCRL setting (give preference to the faster OCSP route and only demand one source to succeed) is a good choice for most typical validation environments. The 'crcAll*' modes are much stricter, and may be used in scenarios where bulletproof validity information is essential.

Note: If no CRL or OCSP endpoints are provided by the CA, the revocation check will be considered successful. This is because the CA chose not to supply revocation information for its certificates, meaning they are considered irrevocable.

Note: Within each of the above settings, if any retrieved CRL or OCSP response indicates that the certificate has been revoked, the revocation check fails.

SocketSettings Property (CertificateValidator Component)

Manages network connection settings.

Syntax

property SocketSettings: TsbxSocketSettings read get_SocketSettings;

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

Please refer to the SocketSettings type for a complete list of fields.

TLSClientChain Property (CertificateValidator Component)

The TLS client certificate chain.

Syntax

property TLSClientChain: TsbxCertificateList read get_TLSClientChain write set_TLSClientChain;

Remarks

Assign a certificate chain to this property to enable TLS client authentication in the component. Note that the client's end-entity certificate should have a private key associated with it.

Use the CertificateStorage or CertificateManager components to import the certificate from a file, system store, or PKCS11 device.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

TLSServerChain Property (CertificateValidator Component)

The TLS server's certificate chain.

Syntax

property TLSServerChain: TsbxCertificateList read get_TLSServerChain;

Remarks

Use this property to access the certificate chain sent by the TLS server. This property is ready to read when the TLSCertValidate event is fired by the client component.

This property is read-only and not available at design time.

Please refer to the Certificate type for a complete list of fields.

TLSSettings Property (CertificateValidator Component)

Manages TLS layer settings.

Syntax

property TLSSettings: TsbxTLSSettings read get_TLSSettings;

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

Please refer to the TLSSettings type for a complete list of fields.

TrustedCertificates Property (CertificateValidator Component)

A list of trusted certificates for chain validation.

Syntax

property TrustedCertificates: TsbxCertificateList read get_TrustedCertificates write set_TrustedCertificates;

Remarks

Use this property to supply a list of trusted certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when root CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of this certificate collection is largely the same as that of the Windows Trusted Root Certification Authorities system store.

Use this property with extreme care as it directly affects chain verifiability; a wrong certificate added to the trusted list may result in bad chains being accepted, and forfeited signatures being recognized as genuine. Only add certificates that originate from the parties that you know and trust.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

UsedCertificates Property (CertificateValidator Component)

Contains a list of certificates used during the chain validation routine.

Syntax

property UsedCertificates: TsbxCertificateList read get_UsedCertificates;

Remarks

Use this property to access the list of certificates that were used during the chain validation.

This property is read-only and not available at design time.

Please refer to the Certificate type for a complete list of fields.

UsedCRLs Property (CertificateValidator Component)

Contains a list of CRLs used during the chain validation routine.

Syntax

property UsedCRLs: TsbxCRLList read get_UsedCRLs;

Remarks

Use this property to access the list of CRLs that were used during the chain validation.

This property is read-only and not available at design time.

Please refer to the CRL type for a complete list of fields.

UseDefaultTSLs Property (CertificateValidator Component)

Enables or disables the use of the default TSLs.

Syntax

property UseDefaultTSLs: Boolean read get_UseDefaultTSLs write set_UseDefaultTSLs;

Default Value

false

Remarks

Use this property to tell the validator to use (or not to use) the default TSLs (Trust Service status Lists). The result of this check reported in Qualified property.

The following default TSLs are used: EU (European Union) TSL.

UsedOCSPs Property (CertificateValidator Component)

Contains a list of OCSP responses used during the chain validation routine.

Syntax

property UsedOCSPs: TsbxOCSPResponseList read get_UsedOCSPs;

Remarks

Use this property to access the list of OCSP responses that were used during the chain validation.

This property is read-only and not available at design time.

Please refer to the OCSPResponse type for a complete list of fields.

UseSystemCertificates Property (CertificateValidator Component)

Enables or disables the use of the system certificates.

Syntax

property UseSystemCertificates: Boolean read get_UseSystemCertificates write set_UseSystemCertificates;

Default Value

false

Remarks

Use this property to tell the validator to use (or not to use) the system certificates. In many cases it is beneficial to switch this property on, as the operating system certificate configuration provides a representative trust framework.

ValidationLog Property (CertificateValidator Component)

Contains the complete log of the certificate validation routine.

Syntax

property ValidationLog: String read get_ValidationLog;

Default Value

''

Remarks

Use this property to access the chain validation log produced by the component. The log can be very useful when investigating issues with chain validation, as it contains a step-by-step trace of the entire validation procedure.

This property is read-only and not available at design time.

ValidationMoment Property (CertificateValidator Component)

The time point at which chain validity is to be established.

Syntax

property ValidationMoment: String read get_ValidationMoment write set_ValidationMoment;

Default Value

''

Remarks

Use this property to specify the moment in time at which chain validity should be established. The time is in UTC. Leave the setting empty to stick to the current moment.

The validity of the same chain may differ depending on the time point chosen due to temporal changes in subchain validities and revocation statuses.

Config Method (CertificateValidator Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

DoAction Method (CertificateValidator Component)

Performs an additional action.

Syntax

function DoAction(ActionID: String; ActionParams: String): String;

Remarks

DoAction is a generic method available in every component. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

GetQualifiedStatus Method (CertificateValidator Component)

Obtains the qualified information for Certificate .

Syntax

procedure GetQualifiedStatus();

Remarks

Use this method to obtain a fresh qualified status for the certificate.

GetTSLProperty Method (CertificateValidator Component)

Returns a specific TSL property.

Syntax

function GetTSLProperty(PropName: String; Language: String): String;

Remarks

Use this method to obtain the value of a specific TSL property. Use the Language parameter to specify the language identifier (e.g. it) in which you would like to have the property returned (if supported by the TSL). Leave the parameter empty to return the value in the default language.

Please find a list of common TSL properties below:

• VersionIdentifier
• SequenceNumber
• Type
• SchemeName
• SchemeOperatorName
• SchemeOperatorAddress
• SchemeInformationURI
• StatusDeterminationApproach
• SchemeTypeCommunityRules
• SchemeTerritory
• Policies
• LegalNotices
• HistoricalInformationPeriod
• ListIssueDateTime
• NextUpdate
• DistributionPoints
• SchemeExtensions
• TSPXML
• TSPName
• TSPTradeName
• TSPInformationURI
• TSPAddress
• TSPInformationExtensions
• TSPServiceXML
• TSPServiceTypeIdentifier
• TSPServiceName
• TSPServiceStatus
• TSPServiceStatusStartingTime
• TSPSchemeServiceDefinitionURI
• TSPServiceDefinitionURI
• TSPServiceSupplyPoints
• TSPServiceInformationExtensions
• TSPServiceQualifiers
• TSPAdditionalServiceInformation
• TSPHistoryInstance
• TSPHistoryInstanceXML
• TSPHistoryInstanceServiceTypeIdentifier
• TSPHistoryInstanceServiceName
• TSPHistoryInstanceServiceStatus
• TSPHistoryInstanceServiceStatusStartingTime
• TSPHistoryInstanceServiceInformationExtensions
• TSPHistoryInstanceQualifiers
• TSPHistoryInstanceAdditionalServiceInformation

RefreshCache Method (CertificateValidator Component)

Refreshes the certificate cache.

Syntax

procedure RefreshCache();

Remarks

Use this method to remove obsolete information from the validation cache (only makes sense if CacheValidationResults is on).

ResetCache Method (CertificateValidator Component)

Clears all data contained in the validation cache.

Syntax

procedure ResetCache();

Remarks

Use this method to clear the validation cache (only makes sense if CacheValidationResults is on).

Terminate Method (CertificateValidator Component)

Terminates the validation process.

Syntax

procedure Terminate();

Remarks

Call this method if you would like to stop the validation process.

Validate Method (CertificateValidator Component)

Validates the certificate chain.

Syntax

function Validate(): Integer;

Remarks

Use this method to validate the certificate chain that starts with Certificate.

The chain validation is a multi-step process which includes validation of each certificate in the chain up to the trusted anchor. The ultimate goal of this process is to establish the integrity of the chain and its trustworthiness.

Depending on the component tuneup, the validation process may differ drastically, even for the same certificate: it may be more or less rigorous, may include or exclude revocation checks, and may be more or less tolerant to minor chain issues.

When this process is completed, the final decision on the validity of the checked certificate is returned from this method, and also saved in ChainValidationResult property. Another property, ChainValidationDetails, provides insight into the reasons that contributed to that decision. Use ValidationLog to get a detailed step-by-step log of the entire validation process.

ValidateForSMIME Method (CertificateValidator Component)

Validates an e-mail signing certificate.

Syntax

function ValidateForSMIME(EmailAddress: String): Integer;

Remarks

Use this method to validate an e-mail security certificate.

This is a variant of Validate method that performs some additional e-mail specific checks, imposed by e-mail certificate rules. This method returns the overall chain validation result.

ValidateForSSL Method (CertificateValidator Component)

Validates a server-side SSL/TLS certificate.

Syntax

function ValidateForSSL(URL: String; IPAddress: String): Integer;

Remarks

Use this method to validate a server-side SSL/TLS certificate.

This is a variant of Validate method that performs some additional TLS-specific checks. It is important that you provide a correct URL or IPAddress for the check to return a reasonable and justified result.

This method returns the overall result of the chain validation.

AfterCertificateProcessing Event (CertificateValidator Component)

Marks the end of a single certificate processing step.

Syntax

type TAfterCertificateProcessingEvent = procedure (
  Sender: TObject;
  const Cert: String;
  Validity: Integer;
  ValidationDetails: Integer
) of Object;

property OnAfterCertificateProcessing: TAfterCertificateProcessingEvent read FOnAfterCertificateProcessing write FOnAfterCertificateProcessing;

Remarks

This event is fired when the component has finished processing Cert, and returns its Validity status and ValidationDetails.

'Processing' consists of one or more 'validations' (with one CA certificate each), completion of each of which is reported via AfterCertificateValidation events. If a certificate is signed by a single CA (which is a typical case), processing is synonymous to validation.

You can influence the validation process by altering the provided validation outcome, such as changing the invalid status to valid. This can be done via InterimValidationResult and InterimValidationDetails properties.

Validity status:

Validation details:

AfterCertificateValidation Event (CertificateValidator Component)

Marks the end of a single certificate validation step.

Syntax

type TAfterCertificateValidationEvent = procedure (
  Sender: TObject;
  const Cert: String;
  const CACert: String;
  Validity: Integer;
  ValidationDetails: Integer
) of Object;

property OnAfterCertificateValidation: TAfterCertificateValidationEvent read FOnAfterCertificateValidation write FOnAfterCertificateValidation;

Remarks

This event is fired when the component has finished validation of Cert with CACert, and returns its Validity status and ValidationDetails.

'Validation', in this context, means a single validation of a certificate with its CA certificate. For certificates with multiple CAs, validations are grouped into 'processings.' Each processing, therefore, is a set of validations of the same certificate with all its CAs.

You can influence the validation process by altering the provided validation outcome, such as changing the invalid status to valid. This can be done via InterimValidationResult and InterimValidationDetails properties.

Validity status:

Validation details:

BeforeCACertificateDownload Event (CertificateValidator Component)

Fires when a CA certificate is about to be downloaded.

Syntax

type TBeforeCACertificateDownloadEvent = procedure (
  Sender: TObject;
  const Cert: String;
  const Location: String
) of Object;

property OnBeforeCACertificateDownload: TBeforeCACertificateDownloadEvent read FOnBeforeCACertificateDownload write FOnBeforeCACertificateDownload;

Remarks

This event is fired when a CA certificate that is needed to validate Cert is about to be downloaded from Location.

BeforeCertificateProcessing Event (CertificateValidator Component)

Reports the start of certificate processing.

Syntax

type TBeforeCertificateProcessingEvent = procedure (
  Sender: TObject;
  const Cert: String;
  Validity: Integer;
  ValidationDetails: Integer
) of Object;

property OnBeforeCertificateProcessing: TBeforeCertificateProcessingEvent read FOnBeforeCertificateProcessing write FOnBeforeCertificateProcessing;

Remarks

This event is fired when the component is about to start the processing of Cert.

'Processing' consists of one or more 'validations' (with one CA certificate each), completion of each of which is reported via AfterCertificateValidation events. If a certificate is signed by a single CA (which is a typical case), processing is synonymous to validation.

The firing of AfterCertificateProcessing marks the end of the certificate processing.

Validity and ValidationDetails specify the current validation status.

Validity status:

Validation details:

BeforeCertificateValidation Event (CertificateValidator Component)

Reports the start of certificate validation.

Syntax

type TBeforeCertificateValidationEvent = procedure (
  Sender: TObject;
  const Cert: String;
  const CACert: String
) of Object;

property OnBeforeCertificateValidation: TBeforeCertificateValidationEvent read FOnBeforeCertificateValidation write FOnBeforeCertificateValidation;

Remarks

This event is fired when the component is about to start validating Cert with CACert.

A 'validation' is a single step of validating a certificate with its CA certificate. A row of consecutive validations of the same certificate with different CAs are grouped into 'processings.'

The firing of AfterCertificateValidation marks the end of the certificate validation step.

BeforeCRLDownload Event (CertificateValidator Component)

Fires when a CRL is about to be downloaded.

Syntax

type TBeforeCRLDownloadEvent = procedure (
  Sender: TObject;
  const Cert: String;
  const CACert: String;
  const Location: String
) of Object;

property OnBeforeCRLDownload: TBeforeCRLDownloadEvent read FOnBeforeCRLDownload write FOnBeforeCRLDownload;

Remarks

This event is fired when a CRL (Certificate Revocation List) needed to validate Cert is going to be downloaded from Location.

BeforeOCSPDownload Event (CertificateValidator Component)

Fires when a certificate's OCSP status is about to be requested.

Syntax

type TBeforeOCSPDownloadEvent = procedure (
  Sender: TObject;
  const Cert: String;
  const CACert: String;
  const Location: String
) of Object;

property OnBeforeOCSPDownload: TBeforeOCSPDownloadEvent read FOnBeforeOCSPDownload write FOnBeforeOCSPDownload;

Remarks

This event is fired when the validator is about to request a fresh revocation status from an OCSP responder.

CACertificateDownloaded Event (CertificateValidator Component)

Marks the success of a certificate download.

Syntax

type TCACertificateDownloadedEvent = procedure (
  Sender: TObject;
  const Cert: String;
  const Location: String
) of Object;

property OnCACertificateDownloaded: TCACertificateDownloadedEvent read FOnCACertificateDownloaded write FOnCACertificateDownloaded;

Remarks

This event is fired when a CA certificate has been successfully downloaded from Location. This event is preceded with BeforeCACertificateDownload event.

CACertificateNeeded Event (CertificateValidator Component)

Requests a missing certificate from the user.

Syntax

type TCACertificateNeededEvent = procedure (
  Sender: TObject;
  const Cert: String
) of Object;

property OnCACertificateNeeded: TCACertificateNeededEvent read FOnCACertificateNeeded write FOnCACertificateNeeded;

Remarks

This event is fired when a CA certificate that is needed to validate Cert is not found at any of the available locations. If you have access to the missing certificate, please add it to the KnownCertificates collection to make it available to the validator.

When this event fires, the CurrentCertificate property is assigned with the certificate being validated. It is the CA that issued that certificate that the validator is looking for.

CRLDownloaded Event (CertificateValidator Component)

Marks the success of a CRL download.

Syntax

type TCRLDownloadedEvent = procedure (
  Sender: TObject;
  const Cert: String;
  const CACert: String;
  const Location: String
) of Object;

property OnCRLDownloaded: TCRLDownloadedEvent read FOnCRLDownloaded write FOnCRLDownloaded;

Remarks

This event is fired when a CRL containing the validation information for Cert has been successfully downloaded from Location. This event is always preceded with BeforeCRLDownload event.

CRLNeeded Event (CertificateValidator Component)

Requests a missing CRL from the user.

Syntax

type TCRLNeededEvent = procedure (
  Sender: TObject;
  const Cert: String;
  const CACert: String
) of Object;

property OnCRLNeeded: TCRLNeededEvent read FOnCRLNeeded write FOnCRLNeeded;

Remarks

This event is fired when a CRL that is needed to validate Cert is not found at any of the available locations. If you have access to the missing CRL, please add it to the KnownCRLs collection to make it available to the validator.

When this event fires, the CurrentCertificate and CurrentCACertificate properties are assigned with the certificate being validated and its issuer certificate.

Error Event (CertificateValidator Component)

Information about errors during certificate validation.

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent read FOnError write FOnError;

Remarks

The event is fired in case of exceptional conditions during certificate processing or online information retrieval.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the corresponding section.

Notification Event (CertificateValidator Component)

This event notifies the application about an underlying control flow event.

Syntax

type TNotificationEvent = procedure (
  Sender: TObject;
  const EventID: String;
  const EventParam: String
) of Object;

property OnNotification: TNotificationEvent read FOnNotification write FOnNotification;

Remarks

The component fires this event to let the application know about some event, occurrence, or milestone in the component. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, the exact action it is performing, or the document being processed, one or both may be omitted.

This component can fire this event with the following EventID values:

OCSPDownloaded Event (CertificateValidator Component)

Marks the success of an OCSP request.

Syntax

type TOCSPDownloadedEvent = procedure (
  Sender: TObject;
  const Cert: String;
  const CACert: String;
  const Location: String
) of Object;

property OnOCSPDownloaded: TOCSPDownloadedEvent read FOnOCSPDownloaded write FOnOCSPDownloaded;

Remarks

This event is fired when an OCSP response containing the validation information for Cert has been successfully downloaded from Location. This event is always preceded with BeforeOCSPDownload event.

TLSCertNeeded Event (CertificateValidator Component)

Fires when a remote TLS party requests a client certificate.

Syntax

type TTLSCertNeededEvent = procedure (
  Sender: TObject;
  const Host: String;
  const CANames: String
) of Object;

property OnTLSCertNeeded: TTLSCertNeededEvent read FOnTLSCertNeeded write FOnTLSCertNeeded;

Remarks

This event fires to notify the implementation that a remote TLS server has requested a client certificate. The Host parameter identifies the host that makes a request, and the CANames parameter (optional, according to the TLS spec) advises on the accepted issuing CAs.

Use the TLSClientChain property in response to this event to provide the requested certificate. Please make sure the client certificate includes the associated private key. Note that you may set the certificates before the connection without waiting for this event to fire.

This event is preceded by the TLSHandshake event for the given host and, if the certificate was accepted, succeeded by the TLSEstablished event.

TLSCertValidate Event (CertificateValidator Component)

This event is fired upon receipt of the TLS server's certificate, allowing the user to control its acceptance.

Syntax

type TTLSCertValidateEvent = procedure (
  Sender: TObject;
  const ServerHost: String;
  const ServerIP: String;
  var Accept: Boolean
) of Object;

property OnTLSCertValidate: TTLSCertValidateEvent read FOnTLSCertValidate write FOnTLSCertValidate;

Remarks

This event is fired during a TLS handshake. Use the TLSServerChain property to access the certificate chain. In general, components may contact a number of TLS endpoints during their work, depending on their configuration.

Accept is assigned in accordance with the outcome of the internal validation check performed by the component, and can be adjusted if needed.

TLSEstablished Event (CertificateValidator Component)

Fires when a TLS handshake with Host successfully completes.

Syntax

type TTLSEstablishedEvent = procedure (
  Sender: TObject;
  const Host: String;
  const Version: String;
  const Ciphersuite: String;
  ConnectionId: TBytes;
  var Abort: Boolean
) of Object;

property OnTLSEstablished: TTLSEstablishedEvent read FOnTLSEstablished write FOnTLSEstablished;

Remarks

The component uses this event to notify the application about a successful completion of a TLS handshake.

The Version, Ciphersuite, and ConnectionId parameters indicate the security parameters of the new connection. Use the Abort parameter if you need to terminate the connection at this stage.

TLSHandshake Event (CertificateValidator Component)

Fires when a new TLS handshake is initiated, before the handshake commences.

Syntax

type TTLSHandshakeEvent = procedure (
  Sender: TObject;
  const Host: String;
  var Abort: Boolean
) of Object;

property OnTLSHandshake: TTLSHandshakeEvent read FOnTLSHandshake write FOnTLSHandshake;

Remarks

The component uses this event to notify the application about the start of a new TLS handshake to Host. If the handshake is successful, this event will be followed by the TLSEstablished event. If the server chooses to request a client certificate, the TLSCertNeeded event will also be fired.

TLSShutdown Event (CertificateValidator Component)

Reports the graceful closure of a TLS connection.

Syntax

type TTLSShutdownEvent = procedure (
  Sender: TObject;
  const Host: String
) of Object;

property OnTLSShutdown: TTLSShutdownEvent read FOnTLSShutdown write FOnTLSShutdown;

Remarks

This event notifies the application about the closure of an earlier established TLS connection. Note that only graceful connection closures are reported.

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

Constructors

>

constructor Create();

Creates a new object with default field values.

CRL Type

Represents a Certificate Revocation List.

Remarks

CRLs store information about revoked certificates, i.e., certificates that have been identified as invalid by their issuing certificate authority (CA) for any number of reasons.

Each CRL object lists certificates from a single CA and identifies them by their serial numbers. A CA may or may not publish a CRL, may publish several CRLs, or may publish the same CRL in multiple locations.

Unlike OCSP responses, CRLs only list certificates that have been revoked. They do not list certificates that are still valid.

Fields

Constructors

>

constructor Create();

Creates an empty CRL object.

OCSPResponse Type

Represents a single OCSP response originating from an OCSP responder.

Remarks

OCSP is a protocol that allows verification of certificate status in real-time, and is an alternative to Certificate Revocation Lists (CRLs).

An OCSP response is a snapshot of the certificate status at a given time.

Fields

Constructors

>

constructor Create();

Creates an empty OCSP response object.

ProxySettings Type

A container for proxy server settings.

Remarks

This type exposes a collection of properties for tuning up the proxy server configuration.

Fields

Constructors

>

constructor Create();

Creates a new ProxySettings object.

QualifiedInfo Type

This component is a container for X.509 qualified information.

Remarks

Use this property to access the qualified information for the validated certificate.

Fields

Constructors

>

constructor Create();

Creates a new QualifiedInfo object.

SocketSettings Type

A container for the socket settings.

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

>

constructor Create();

Creates a new SocketSettings object.

TLSSettings Type

A container for TLS connection settings.

Remarks

The TLS (Transport Layer Security) protocol provides security for information exchanged over insecure connections such as TCP/IP.

Fields

Constructors

>

constructor Create();

Creates a new TLSSettings object.

Config Settings (CertificateValidator Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

CertificateValidator Config Settings

TrustedLists Config Settings

Base Config Settings

Trappable Errors (CertificateValidator Component)

CertificateValidator Errors

	1048577   Invalid parameter value (SB_ERROR_INVALID_PARAMETER)
	1048578   Component is configured incorrectly (SB_ERROR_INVALID_SETUP)
	1048579   Operation cannot be executed in the current state (SB_ERROR_INVALID_STATE)
	1048580   Attempt to set an invalid value to a property (SB_ERROR_INVALID_VALUE)
	1048581   Certificate does not have its private key loaded (SB_ERROR_NO_PRIVATE_KEY)
	1048581   Cancelled by the user (SB_ERROR_CANCELLED_BY_USER)