CertificateValidator Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

secureblackbox.CertificateValidator

Remarks

This is a powerful and configurable class 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 class with short descriptions. Click on the links for further details.

Method List

---

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

Event List

---

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

Config Settings

---

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

BlockedCertificates Property (CertificateValidator Class)

The certificates that must be rejected as trust anchors.

Syntax

public CertificateList getBlockedCertificates();
public void setBlockedCertificates(CertificateList 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 Class)

Enables or disables validation result caching.

Syntax

public boolean isCacheValidationResults();
public void setCacheValidationResults(boolean cacheValidationResults);

Default Value

False

Remarks

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

Certificate Property (CertificateValidator Class)

The certificate to be validated.

Syntax

public Certificate getCertificate();
public void setCertificate(Certificate 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 Class)

The details of a certificate chain validation outcome.

Syntax

public int getChainValidationDetails();

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 Class)

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

Syntax

public int getChainValidationResult();

Enumerated values:
  public final static int cvtValid = 0;
  public final static int cvtValidButUntrusted = 1;
  public final static int cvtInvalid = 2;
  public final static int cvtCantBeEstablished = 3;

Default Value

0

Remarks

Available options:

Use the ValidationLog property to access the detailed validation log.

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

CheckTrustedLists Property (CertificateValidator Class)

Specifies whether the class should attempt to validate chain trust via a known Trusted List.

Syntax

public boolean isCheckTrustedLists();
public void setCheckTrustedLists(boolean checkTrustedLists);

Default Value

False

Remarks

Set this property to true to enable the component to validate chain trust against an internal list of known Trusted Lists (such as EUTL).

CurrentCACertificate Property (CertificateValidator Class)

The CA of the currently processed certificate.

Syntax

public Certificate getCurrentCACertificate();

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 Class)

The certificate that is currently being processed.

Syntax

public Certificate getCurrentCertificate();

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 Class)

Reserved.

Syntax

public boolean isFIPSMode();
public void setFIPSMode(boolean FIPSMode);

Default Value

False

Remarks

This property is reserved for future use.

GracePeriod Property (CertificateValidator Class)

Specifies a grace period to apply during certificate validation.

Syntax

public int getGracePeriod();
public void setGracePeriod(int 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 Class)

Contains the validation details of the moment.

Syntax

public int getInterimValidationDetails();
public void setInterimValidationDetails(int 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 Class)

Contains the validation status of the moment.

Syntax

public int getInterimValidationResult();
public void setInterimValidationResult(int interimValidationResult);

Enumerated values:
  public final static int cvtValid = 0;
  public final static int cvtValidButUntrusted = 1;
  public final static int cvtInvalid = 2;
  public final static int cvtCantBeEstablished = 3;

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 status mid-flight.

This property is not available at design time.

KnownCertificates Property (CertificateValidator Class)

Additional certificates for chain validation.

Syntax

public CertificateList getKnownCertificates();
public void setKnownCertificates(CertificateList 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 class 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 Class)

Additional CRLs for chain validation.

Syntax

public CRLList getKnownCRLs();
public void setKnownCRLs(CRLList 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 Class)

Additional OCSP responses for chain validation.

Syntax

public OCSPResponseList getKnownOCSPs();
public void setKnownOCSPs(OCSPResponseList 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 Class)

Specifies the maximum time the validation process may take.

Syntax

public int getMaxValidationTime();
public void setMaxValidationTime(int 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 Class)

Switches the class to offline mode.

Syntax

public boolean isOfflineMode();
public void setOfflineMode(boolean offlineMode);

Default Value

False

Remarks

When working in offline mode, the class 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 Class)

The proxy server settings.

Syntax

public ProxySettings getProxy();

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 Class)

The qualified details for the validated certificate.

Syntax

public QualifiedInfo getQualifiedInfo();

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 Class)

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

Syntax

public int getRevocationCheck();
public void setRevocationCheck(int revocationCheck);

Enumerated values:
  public final static int crcNone = 0;
  public final static int crcAuto = 1;
  public final static int crcAllCRL = 2;
  public final static int crcAllOCSP = 3;
  public final static int crcAllCRLAndOCSP = 4;
  public final static int crcAnyCRL = 5;
  public final static int crcAnyOCSP = 6;
  public final static int crcAnyCRLOrOCSP = 7;
  public final static int crcAnyOCSPOrCRL = 8;

Default Value

1

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 Class)

Manages network connection settings.

Syntax

public SocketSettings getSocketSettings();

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 Class)

The TLS client certificate chain.

Syntax

public CertificateList getTLSClientChain();
public void setTLSClientChain(CertificateList TLSClientChain);

Remarks

Assign a certificate chain to this property to enable TLS client authentication in the class. 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 Class)

The TLS server's certificate chain.

Syntax

public CertificateList getTLSServerChain();

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 Class)

Manages TLS layer settings.

Syntax

public TLSSettings getTLSSettings();

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 Class)

A list of trusted certificates for chain validation.

Syntax

public CertificateList getTrustedCertificates();
public void setTrustedCertificates(CertificateList 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 Class)

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

Syntax

public CertificateList getUsedCertificates();

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 Class)

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

Syntax

public CRLList getUsedCRLs();

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.

UsedOCSPs Property (CertificateValidator Class)

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

Syntax

public OCSPResponseList getUsedOCSPs();

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 Class)

Enables or disables the use of the system certificates.

Syntax

public boolean isUseSystemCertificates();
public void setUseSystemCertificates(boolean 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 Class)

Contains the complete log of the certificate validation routine.

Syntax

public String getValidationLog();

Default Value

""

Remarks

Use this property to access the chain validation log produced by the class. 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 Class)

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

Syntax

public String getValidationMoment();
public void setValidationMoment(String 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 Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, 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 Class)

Performs an additional action.

Syntax

public String doAction(String actionID, String actionParams);

Remarks

DoAction is a generic method available in every class. 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;....

Common ActionIDs:

GetQualifiedStatus Method (CertificateValidator Class)

Obtains the qualified information for Certificate .

Syntax

public void getQualifiedStatus();

Remarks

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

GetTrustedListProperty Method (CertificateValidator Class)

Returns a specific TrustedList property.

Syntax

public String getTrustedListProperty(String propName, String language);

Remarks

Use this method to obtain the value of a specific TrustedList 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 TrustedList). Leave the parameter empty to return the value in the default language.

Please find a list of common TrustedList 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 Class)

Refreshes the certificate cache.

Syntax

public void refreshCache();

Remarks

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

Reset Method (CertificateValidator Class)

Resets the class settings.

Syntax

public void reset();

Remarks

Reset is a generic method available in every class.

ResetCache Method (CertificateValidator Class)

Clears all data contained in the validation cache.

Syntax

public void resetCache();

Remarks

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

Terminate Method (CertificateValidator Class)

Terminates the validation process.

Syntax

public void terminate();

Remarks

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

Validate Method (CertificateValidator Class)

Validates the certificate chain.

Syntax

public int validate();

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 Class)

Validates an e-mail signing certificate.

Syntax

public int validateForSMIME(String emailAddress);

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 Class)

Validates a server-side SSL/TLS certificate.

Syntax

public int validateForSSL(String URL, String IPAddress);

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 Class)

Marks the end of a single certificate processing step.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void afterCertificateProcessing(CertificateValidatorAfterCertificateProcessingEvent e) {}
  ...
}

public class CertificateValidatorAfterCertificateProcessingEvent {
  public String cert;
  public int validity;
  public int validationDetails;
}

Remarks

This event is fired when the class 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 Class)

Marks the end of a single certificate validation step.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void afterCertificateValidation(CertificateValidatorAfterCertificateValidationEvent e) {}
  ...
}

public class CertificateValidatorAfterCertificateValidationEvent {
  public String cert;
  public String CACert;
  public int validity;
  public int validationDetails;
}

Remarks

This event is fired when the class 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 Class)

Fires when a CA certificate is about to be downloaded.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void beforeCACertificateDownload(CertificateValidatorBeforeCACertificateDownloadEvent e) {}
  ...
}

public class CertificateValidatorBeforeCACertificateDownloadEvent {
  public String cert;
  public String location;
}

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 Class)

Reports the start of certificate processing.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void beforeCertificateProcessing(CertificateValidatorBeforeCertificateProcessingEvent e) {}
  ...
}

public class CertificateValidatorBeforeCertificateProcessingEvent {
  public String cert;
  public int validity;
  public int validationDetails;
}

Remarks

This event is fired when the class 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 Class)

Reports the start of certificate validation.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void beforeCertificateValidation(CertificateValidatorBeforeCertificateValidationEvent e) {}
  ...
}

public class CertificateValidatorBeforeCertificateValidationEvent {
  public String cert;
  public String CACert;
}

Remarks

This event is fired when the class 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 Class)

Fires when a CRL is about to be downloaded.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void beforeCRLDownload(CertificateValidatorBeforeCRLDownloadEvent e) {}
  ...
}

public class CertificateValidatorBeforeCRLDownloadEvent {
  public String cert;
  public String CACert;
  public String location;
}

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 Class)

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

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void beforeOCSPDownload(CertificateValidatorBeforeOCSPDownloadEvent e) {}
  ...
}

public class CertificateValidatorBeforeOCSPDownloadEvent {
  public String cert;
  public String CACert;
  public String location;
}

Remarks

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

CACertificateDownloaded Event (CertificateValidator Class)

Marks the success of a certificate download.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void CACertificateDownloaded(CertificateValidatorCACertificateDownloadedEvent e) {}
  ...
}

public class CertificateValidatorCACertificateDownloadedEvent {
  public String cert;
  public String location;
}

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 Class)

Requests a missing certificate from the user.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void CACertificateNeeded(CertificateValidatorCACertificateNeededEvent e) {}
  ...
}

public class CertificateValidatorCACertificateNeededEvent {
  public String cert;
}

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 Class)

Marks the success of a CRL download.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void CRLDownloaded(CertificateValidatorCRLDownloadedEvent e) {}
  ...
}

public class CertificateValidatorCRLDownloadedEvent {
  public String cert;
  public String CACert;
  public String location;
}

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 Class)

Requests a missing CRL from the user.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void CRLNeeded(CertificateValidatorCRLNeededEvent e) {}
  ...
}

public class CertificateValidatorCRLNeededEvent {
  public String cert;
  public String CACert;
}

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 Class)

Information about errors during certificate validation.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void error(CertificateValidatorErrorEvent e) {}
  ...
}

public class CertificateValidatorErrorEvent {
  public int errorCode;
  public String description;
}

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 Class)

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

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void notification(CertificateValidatorNotificationEvent e) {}
  ...
}

public class CertificateValidatorNotificationEvent {
  public String eventID;
  public String eventParam;
}

Remarks

The class fires this event to let the application know about some event, occurrence, or milestone in the class. 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 class, the exact action it is performing, or the document being processed, one or both may be omitted.

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

OCSPDownloaded Event (CertificateValidator Class)

Marks the success of an OCSP request.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void OCSPDownloaded(CertificateValidatorOCSPDownloadedEvent e) {}
  ...
}

public class CertificateValidatorOCSPDownloadedEvent {
  public String cert;
  public String CACert;
  public String location;
}

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 Class)

Fires when a remote TLS party requests a client certificate.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void TLSCertNeeded(CertificateValidatorTLSCertNeededEvent e) {}
  ...
}

public class CertificateValidatorTLSCertNeededEvent {
  public String host;
  public String CANames;
}

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 Class)

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

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void TLSCertValidate(CertificateValidatorTLSCertValidateEvent e) {}
  ...
}

public class CertificateValidatorTLSCertValidateEvent {
  public String serverHost;
  public String serverIP;
  public boolean accept; //read-write
}

Remarks

This event is fired during a TLS handshake. Use the TLSServerChain property to access the certificate chain. In general, classes 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 class, and can be adjusted if needed.

TLSEstablished Event (CertificateValidator Class)

Fires when a TLS handshake with Host successfully completes.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void TLSEstablished(CertificateValidatorTLSEstablishedEvent e) {}
  ...
}

public class CertificateValidatorTLSEstablishedEvent {
  public String host;
  public String version;
  public String ciphersuite;
  public byte[] connectionId;
  public boolean abort; //read-write
}

Remarks

The class 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 Class)

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

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void TLSHandshake(CertificateValidatorTLSHandshakeEvent e) {}
  ...
}

public class CertificateValidatorTLSHandshakeEvent {
  public String host;
  public boolean abort; //read-write
}

Remarks

The class 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 Class)

Reports the graceful closure of a TLS connection.

Syntax

public class DefaultCertificateValidatorEventListener implements CertificateValidatorEventListener {
  ...
  public void TLSShutdown(CertificateValidatorTLSShutdownEvent e) {}
  ...
}

public class CertificateValidatorTLSShutdownEvent {
  public String host;
}

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

Encapsulates an individual X.509 certificate.

Remarks

This type keeps and provides access to X.509 certificate details.

Fields

Constructors

public Certificate( bytes,  startIndex,  count,  password);

public Certificate( certBytes,  certStartIndex,  certCount,  keyBytes,  keyStartIndex,  keyCount,  password);

public Certificate( bytes,  startIndex,  count);

public Certificate( path,  password);

public Certificate( certPath,  keyPath,  password);

public Certificate( path);

public Certificate( stream);

public Certificate( stream,  password);

public Certificate( certStream,  keyStream,  password);

public Certificate();

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

public CRL( bytes,  startIndex,  count);

public CRL( location);

public CRL( stream);

public CRL();

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

public OCSPResponse( bytes,  startIndex,  count);

public OCSPResponse( location);

public OCSPResponse( stream);

public OCSPResponse();

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

public ProxySettings();

QualifiedInfo Type

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

Remarks

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

Fields

Constructors

public QualifiedInfo();

SocketSettings Type

A container for the socket settings.

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

public SocketSettings();

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

public TLSSettings();

Config Settings (CertificateValidator Class)

The class 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 class, access to these internal properties is provided through the Config method.

CertificateValidator Config Settings

TrustedLists Config Settings

Base Config Settings

Trappable Errors (CertificateValidator Class)

CertificateValidator Errors