Skip to content

Latest commit

 

History

History
202 lines (141 loc) · 13.6 KB

revocation-data-management.adoc

File metadata and controls

202 lines (141 loc) · 13.6 KB

1. Revocation data management

Revocation data management is an essential part in the lifecycle of a digital certificate and thus of a digital signature too.

1.1. Tokens and sources

DSS provides utilities for processing and validation of both CRL and OCSP tokens, containing a revocation information about a certificate (see [CRLsAndOCSP] for more information on CRLs and OCSP)

For every certificate, the validity has to be checked via CRL or OCSP responses. The information may originate from different CRL or OCSP sources. For easing the usage of such sources, DSS implements a CRLSource and OCSPSource interfaces (which inherit from RevocationSource), which offer a generic and uniform way of accessing CRL and OCSP sources, respectively. Furthermore, a caching mechanism can be easily attached to those sources, optimizing the access time to revocation information by reducing network connections to online servers.

The interface CRLSource defines the method which returns a CRLToken for the given certificate/issuer certificate couple:

CRLSource usage
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/CRLSourceSnippet.java[role=include]

The interface OCSPSource defines the method which returns OCSPToken for the given certificate/issuer certificate couple:

OCSPSource usage
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/OCSPSourceSnippet.java[role=include]

We use these classes during the certificate validation process through validationContext object (based on ValidationContext class) which is a "cache" for a validation request that contains every object required for a complete validation process. This object in turn instantiates a RevocationDataVerifier used by RevocationDataLoadingStrategy class whose role is to fetch revocation data by querying an OCSP or CRL source in the defined order and return the succeeded result (see Revocation data loading strategy for more details).

In general, we can distinguish three main sources:

  • Offline sources (OfflineRevocationSource);

  • Online sources (OnlineRevocationSource);

  • Sources with the cache mechanism.

As well as a list of sources (ListRevocationSource) with a collection of several sources.

1.2. Caching

The above-mentioned class allows caching of CRL and OCSP responses to a user-chosen source. By default, DSS provides a JDBC based implementation for this class, but other implementations also can be created. The class contains a complete set of functions to save revocation data to a database, extract, update and remove it.
Furthermore, the RepositoryRevocationSource allows the implementer to define a backup revocation source, for the case if the database does not contain the certificate’s revocation data yet.

List of cached Revocation sources implemented in DSS:

  • JdbcRevocationSource

    • JdbcCacheCRLSource

    • JdbcCacheOCSPSource

Warning
 A database table shall be initialized before you start working with the cached revocation repository.

1.2.1. CRL

An example for JdbcCacheCRLSource :

JdbcCacheCRLSource usage
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/CRLSourceSnippet.java[role=include]

1.2.2. OCSP

An example for JdbcCacheOCSPSource :

JdbcCacheOCSPSource usage
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/OCSPSourceSnippet.java[role=include]

1.2.3. JDBC sources with other databases

Depending on a used database, the executed SQL requests may differ (for example one or another datatype may be not supported). In order to adapt the JdbcRevocationSource to the used database, the easiest way is to override the SQL requests with values supported by the target database.

For instance, in PostgreSQL a bytea datatype is required for storing binary data instead of blob or longvarbinary used in default implementation of Jdbc sources. The following example demonstrates a Jdbc implementation example for CRL data storing adapted for PostgreSQL:

JdbcCacheCRLSource with PostgreSQL
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/CRLSourceSnippet.java[role=include]

1.3. Online fetching

DSS provides utilities for online fetching of revocation data from remote sources, during the signature augmentation and validation processes.

Warning
 By default, revocation data are not fetched from untrusted sources. In other words, revocation data are not fetched when the prospective certificate chain does not contain a trust anchor.

1.3.1. CRL

This is a representation of an Online CRL repository. This implementation will download the CRL using the protocol referenced in the certificate (e.g. HTTP, LDAP). The URIs of CRL server will be extracted from this property (OID value: 1.3.6.1.5.5.7.48.1.3).

It allows the following configuration :

OnlineCRLSource usage
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/CRLSourceSnippet.java[role=include]

1.3.2. OCSP

This is a representation of an Online OCSP repository. This implementation will access the OCSP responder using the access point defined in the certificate. Note that the certificate’s Authority Information Access (AIA) extension is used to find issuer’s resources location like Online Certificate Status Protocol (OCSP). The URIs of OCSP server will be extracted from this property (OID value: 1.3.6.1.5.5.7.48.1).

It allows the following configuration :

OnlineOCSPSource usage
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/OCSPSourceSnippet.java[role=include]

1.4. Other implementations of CRL and OCSP Sources

Other revocation sources find the status of a certificate either from a list stored locally or using the information contained in the advanced signature or online way. Here is the list of sources already implemented in the DSS framework:

  • CRL sources:

    • OfflineCRLSource : This class implements the OfflineRevocationSource and retrieves the revocation data from extracted information. The code is common for all signature formats and CRL contents are injected by its sub-classes:

      • CMSCRLSource : Extracts CRLs and CRL references from a CMS Signed Data:

        • CAdESCRLSource : Sub-class of CMSCRLSource for a CAdES Signature;

        • TimestampCRLSource: Sub-class of CMSCRLSource for a Timestamp token (RFC 3161);

      • PAdESCRLSource : Extracts CRLs and CRL references from a PAdES signature.

      • XAdESCRLSource : Extracts CRLs and CRL references from a XAdES signature.

      • ExternalResourcesCRLSource : A class that can instantiate a list of certificate revocation lists from a directory where the individual lists should be.

    • OnlineCRLSource : Retrieves CRL files from online sources with the CRL Distribution Points information from the certificate.

    • JdbcCacheCrlSource : Implementation of the JdbcRevocationSource. This implementation allows storage of valid CRL entries to a defined DataSource' and retrieve them locally.

  • OCSP sources:

    • OfflineOCSPSource : This class implements the OfflineRevocationSource and retrieves the revocation data from extracted information. The code is common for all signature formats and OCSP responses are injected by its sub-classes:

      • CMSOCSPSource : Extracts OCSP responses and OCSP references from a CMS Signed Data:

        • CAdESOCSPSource : Sub-class of CMSOCSPSource for a CAdES Signature;

        • TimestampOCSPSource: Sub-class of CMSOCSPSource for a Timestamp token (RFC 3161);

      • PAdESOCSPSource : Extracts OCSP responses and OCSP references from a PAdES signature.

      • XAdESOCSPSource : Extracts OCSP responses and OCSP references from a XAdES signature.

        • ExternalResourcesOCSPSource : A class that can instantiate a list of OCSPToken from a directory where should be the individual DER Encoded X509 certificates files.

    • OnlineOCSPSource : Retrieves OCSP responses from online source.

    • JdbcCacheOcspSource : Implementation of the JdbcRevocationSource. This implementation allows storage of valid OCSP entries to a defined DataSource and retrieve them locally.

1.5. Revocation data loading strategy

Since version 5.9, DSS allows the use of a RevocationDataLoadingStrategy. The latter defines logic for loading OCSP or CRL data. Two strategies are available in the core package of DSS:

  • OCSPFirstRevocationDataLoadingStrategy: loads OCSP first, if not available or the response is invalid, then tries to load CRL and returns the first succeeded result. This strategy is used by default for revocation retrieving.

  • CRLFirstRevocationDataLoadingStrategy: fetches firstly CRL response, if not available, tries OCSP and returns the first succeeded result.

Note
 Since DSS 5.11 in order to avoid concurrency issues, the RevocationDataLoadingStrategy shall be configured within a CertificateVerifier using the new RevocationDataLoadingStrategyFactory class.

See section [certificateVerifier] for an example of how to customize a used RevocationDataLoadingStrategy with a builder.

Using an OCSP first (i.e. OCSPFirstRevocationDataLoadingStrategy) has some advantages:

  1. There is a potential benefit of freshness compared to using CRLs: in case the OCSP sends queries to a database that is updated in real time or every x hours, the information fetched by the OCSP is more recent (thisUpdate field) than the information contained in the CRL, given that the CRL is built from that database. In the worst case, the OCSP uses the data contained in the CRL and they both have the same thisUpdate field. The information fetched by an OCSP will never be older than the one obtained from a CRL.

  2. The certificate that signed the OCSP response might contain an OCSPNoCheck extension. This extension indicates that the revocation data of the certificate that contains the public key linked to the private key that was used to sign the OCSP response does not need to be checked.

  3. Getting a response takes less time and less memory space for OCSP than with CRLs. A CRL can take a lot of space and a long time to be downloaded due its big size. There is also no obligation to sort CRLs according to serial number which means that the whole list needs to be browsed until finding the searched serial number.

1.5.1. Revocation fallback

Since version 5.11, DSS performs a validation of revocation data obtained from online sources (on signature extension and validation included) through Revocation data verifier. Revocation data loading strategy runs the revocation verification process for each obtained revocation token (i.e. OCSP or CRL) until receiving the first successful result. In case none of the fetched revocation tokens are good to continue the validation process (i.e. verification has failed), then the strategy decides whether any results must be returned based on the "revocation fallback" property. The revocation fallback has two possible values:

  • FALSE (by default) - does not return any revocation token in case none of the obtained revocation tokens have passed the verification process; and

  • TRUE - returns the first obtained revocation token when verification of all tokens has failed.

Note
 While the revocation fallback is set to FALSE by default, it is enforced to TRUE value within a SignedDocumentValidator class for performing a signature validation, in order to produce a complete validation report. Therefore, the change of the value within CertificateVerifier will only impact the signature extension process.

To configure the revocation fallback behavior, the property should be configured within CertificateVerifier, see section [certificateVerifier] for an example.

1.6. Revocation data verifier

Since version 5.11, DSS provides a way to configure a revocation data checking algorithm within SignatureValidationContext in order to define whether the available revocation data is good and sufficient and if a new revocation data should be loaded, as well as the acceptance of a freshly fetched revocation data itself.

RevocationDataVerifier must be provided within the used CertificateVerifier in order to configure the revocation data checking behaviour. See section [certificateVerifier] for an example of how to provide a custom RevocationDataVerifier to a CertificateVerifier.

Warning
 An instance of RevocationDataVerifier should not be shared between multiple CertificateVerifier instances, as it re-uses the same trusted certificate stores defined within a CertificateVerifier.

An example of RevocationDataVerifier please see below:

RevocationDataVerifier usage
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/CertificateVerifierSnippet.java[role=include]

1.7. Timestamp token verifier

Since version 6.1, DSS provides a way to configure the process for accepting of embedded timestamps in order to extract the corresponding POEs during the validation process.

TimestampTokenVerifier must be provided within the used CertificateVerifier in order to configure the revocation data checking behaviour. See section [certificateVerifier] for an example of how to provide a custom TimestampTokenVerifier to a CertificateVerifier.

An example of TimestampTokenVerifier configuration please see below:

TimestampTokenVerifier usage
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/CertificateVerifierSnippet.java[role=include]