The TLValidationJob allows downloading, parsing and validating the Trusted List(s) (TL) (cf. [EUTL]) and List(s) Of Trusted Lists (LOTL) (cf. [LOTL]). Once the task is done, its result is stored in the TrustedListsCertificateSource. The job uses 3 different caches (download, parsing and validation) and a state-machine to be efficient.
Trusted lists are stored in the file system. That offers the possibility to run the validation job in offline mode with the stored trusted lists. Trusted Lists can be loaded from the file system and/or from Internet.
In the next sections the different configurations will be covered.
Several TLSources and several LOTLSources can be injected in a TLValidationJob. The only constraint is the uniqueness of the Trusted List URLs.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]A TLSource allows quickly setting up a trusted list configuration. The URL and the signing certificates for this TL are mandatory. Optionally, predicates or/and filters can be configured to retrieve only a part of the trust service providers or trust services.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]A similar configuration is possible for Lists Of Trusted Lists (LOTL) with a LOTLSource. That requires an URL and a list of potential LOTL signers. Some other parameters are also possible. By default, all listed trusted lists are loaded.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]The DSSFileLoader represents an interface for accessing documents from a file system. DSS provides the following implementations of the interface:
-
FileCacheDataLoader- returns a cached document from a file system when available, otherwise performs a request to a providedDataLoader(e.g. to download the content from a remote source); -
Sha2FileCacheDataLoader(available since DSS6.1) - implements a Trusted List download logic defined within ETSI TS 119 612 (cf. [R11]), using a ".sha2" file, containing digest of the corresponding Trusted List. When digest is updated or a NextUpdate is reached, re-downloads the XML Trusted List. This class is meant to save bandwidth onTLValidationJob, as well as to improve performance.
TLValidationJob requires two objects for configuration of the Trusted Lists download process, namely:
-
offline refresh is used to load a document from a local file system, without querying online sources, providing an unlimited cache expiration. Usually is used on an application’s build;
-
online refresh is used to download a document from a remote source, using none or a limited cache expiration. Usually is used within a cron job, updating content of Trusted Lists regularly (e.g. every hour).
The snippets below provide an example of a basic configuration of offline and online DSSFileLoader for configuration of TLValidationJob.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]As an alternative, in order to improve efficiency of the Trusted List download process, a Sha2FileCacheDataLoader class can be used.
DSS provides multiple ways to configure the class, see examples below:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]|
Note
|
Sha2FileCacheDataLoader is meant to be used for downloading of Trusted Lists implementing the ETSI TS 119 612 standard (cf. [R11]). There is no guarantee the class will work as intended in any other scope. Thus, it is use is not recommended outside of TLValidationJob. If needed, please use FileCacheDataLoader instead.
|
The SynchronizationStrategy defines the trusted lists or list(s) of trusted lists to be synchronized. By default, DSS synchronizes all of them and DSS does not reject any trusted lists (e.g. expired, invalid, etc.). The default behavior can be customized with implementation of the SynchronizationStrategy.
DSS provides two implementations within the framework:
-
AcceptAllStrategy(default) - accepts all Trusted List, whatever the validation status is. -
ExpirationAndSignatureCheckStrategy- rejects Trusted Lists with invalid signature or expired Trusted Lists (nextUpdate is before the control time). The certificates from a such Trusted List are not loaded to theTrustedListsCertificateSource.
The use of the strategies is demonstrated within the example below:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]An example of a custom implementation of SynchronizationStrategy can be found below:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]The CacheCleaner specifies how DSS clears the cache (e.g. in case of expired URL, etc.). Two cleaning options are available : memory and file system.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]DSS allows running of custom alerts in some situations (e.g. invalid TL signature, LOTL location change, etc.). Alert works with two concepts: detection and alert handler. After the download/parsing/validation and before the synchronization, the results are tested to detect events and launch alert(s).
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]See section [Alerts] in the Annex for more information on related alerts.
TSL predicates provide an option to filter the extracted TSL Pointers from LOTL or TL sources, allowing a customization of a trusted certificates and trusted services loading.
The following predicates are provided within the framework:
-
EULOTLOtherTSLPointer- filters the EU LOTL pointer; -
EUTLOtherTSLPointer- filters the EU TL pointers; -
MimetypeOtherTSLPointer- filters TL pointers by a MimeType (e.g. to filter XML files only); -
XMLOtherTSLPointer- filters XML TL pointers; -
PDFOtherTSLPointer- filters PDF TL pointers; -
SchemeTerritoryOtherTSLPointer- filters TL pointers with a specific scheme territory (i.e. filter by country).
|
Note
|
For ready-to-use predicates, please see TLPredicateFactory that contains a list of methods to create the most commonly used predicates in a simplified way.
|
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]Defined within TLSource predicated allow filtering of TrustServiceProvider elements based on the JAXB object containing information extracted about the TrustServiceProvider from an XML Trusted List.
The Trusted Service Provider predicates are not enforced by default, therefore in a plain configuration, DSS would accept all found Trust Service Providers and extract the corresponding information from them.
Within the framework the following `TrustServiceProviderPredicate`s are provided:
-
TrustServiceProviderByTSPName- this predicate is meant to filter trust service providers with the given TSP name. All other Trust Service Providers will be skipped. -
NonEmptyTrustService- this predicate filters trust service providers that have at least oneTSPServicedefined within it.
Below you may find an example of TrustServiceProviderPredicate configuration:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]It is also possible to create a custom TrustServiceProviderPredicate, see an example below, used to filter TrustServiceProviders with a particular TSPName:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]Defined within TLSource predicated allow filtering of specific TSPService elements based on the JAXB object containing information extracted about the TSPService from an XML Trusted List.
The TSP Service predicates are not enforced by default, therefore in a plain configuration, DSS would accept all found TSP Services and extract the corresponding information from them.
Within the framework the following TrustServicePredicate is provided:
-
GrantedTrustService- this predicate is meant to filter trusted services containing an acceptable (i.e. accredited or granted) status with despite it was defined before or after eIDAS regulation.
Below you may find an example of TrustServicePredicate configuration:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]An Executor Service allows you to customize a way of the program execution on your Java machine, by configuring a number of possible threads to be running, await time and so on.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]Below, you can find a complete configuration for the European List Of Trusted Lists. The URLs need to be externalized.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/EuropeanLOTLSnippets.java[role=include]The TL / LOTL loading in DSS works as below :
-
Download / parse / validate all LOTLSources from the configuration with/without pivot support (multi-threaded);
-
Analyze introduced changes and expired cache entries (new TL URLs, new signing certificates for a TL, etc.);
-
Create TLSources from the retrieved LOTLs;
-
Combine these TLSources with independent TLSources (from the configuration);
-
Download / parse / validate all TLs (multi-threaded);
-
If alerts are configured, test if an alert needs to be launched;
-
If the debug is enabled, print in the log the cache status;
-
Synchronize the
TrustedListCertificateSource; -
If the cache cleaner is configured, execute it;
-
If the debug is enabled, print in the log the cache status.
The refresh can be called with the offline or the online loader and run exactly the same code:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]Generally (like in case of European LOTL) DSS downloads Trusted Lists by using the SSL protocol (for resources using HTTPS extension), that requires to have a certificate of a remote source in the Java trust store. The certificates have their own validity period and can expire. If a certificate is expired, it will be replaced on a server by a new one in order to support a secure SSL connection. The easiest way to know if your Java trust store is outdated and new certificates need to be added is to check your logs during a TLValidationJob update :
ERROR 14052 --- [pool-2-thread-30] e.e.e.dss.tsl.runnable.AbstractAnalysis : Unable to process GET call for url [https://sr.riik.ee/tsl/estonian-tsl.xml]. Reason : [PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target]The SunCertPathBuilderException means that the certificate establishing the secure connection is not trusted by your Java Virtual Machine. In order to add the certificate to the trust store, you need to do the following steps (the example is based on Windows OS and Google Chrome browser):
-
Open the failed URL in your browser. In our case it will be 'https://sr.riik.ee/tsl/estonian-tsl.xml' obtained from the logs.
-
Click on a lock icon next to the URL in the tab you just opened. It will open a window about the current connection status.
-
Click on 'Certificate' button to open the Certificate window.
-
Go to 'Details' tab and choose 'Copy to File…'.
-
Process the 'Certificate Export Wizard', by saving the certificate in one of '.CER' formats. Store the file in your file system. For us it will create a file 'ee.cer'.
-
Run 'Command Prompt' with administrator permissions (right click → 'Run As Administrator').
-
Execute the following line (ensure that 'keytool' is installed):
keytool -import -alias newCert -file pathToCert\ee.cer -keystore pathToJavaDirectory\lib\security\cacerts -storepass changeitThe default password for a Java keystore is changeit. Ensure that you have a default configuration, or use another password you have configured.
|
Note
|
In order to apply changes, the application using Java must be rebooted. |
After these steps the TLValidationJob will successfully download the target Trusted List (i.e. Estonian in our example).
|
Note
|
This described algorithm is not only one available solution, if you have difficulties with this, you can search in the Internet for another working for you solution. |
|
Note
|
When using DSS-demonstrations, you may also set property tl.loader.trust.all=true to trust all SSL-certificates on Trusted Lists loading, in order to avoid manual configuration of the trusted store. Be aware, that this constraint will skip the SSL-certificate validation.
|
The class TLValidationJobSummary contains all processed data about the download (time, error, etc.), the parsing (extracted information, parsing error, etc.) and the signature validation (signing certificate, signing time, etc.).
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]An eIDAS XML node linked to the status of the Trusted List is included in the DSS validation policy (see [validationPolicy] for more information). The following elements are contained in that node:
-
TLFreshness: Given that TLs are too heavy to be downloaded at each validation, TLs are downloaded every few hours. However, it can happen that a download is not possible because the TL is not available or because there is a problem with the downloader on the signature validation algorithm side. For such situations, it is useful to display a message to indicate that the TL is not “fresh”. To achieve this, the TL freshness indicates that TLs were downloaded no later than the validation time minus the TL freshness time interval.
-
TLNotExpired: The TL might be expired in case of an attack consisting in replacing the current TL by an older one. Using an old TL might bring problems. The expired TL could for example contain Certificate Authorities that are not present in the current TL. Thus, an expired TL should lead to a warning during the validation.
-
TLWellSigned: If the signature of the TL is not valid, the TL should be discarded. A non-valid TL signature might indicate that the content of that TL is "fake" and should not be trusted.
-
TLVersion: If the version of the trusted list does not correspond to the version indicated in the validation policy, the validation process fails.
Non-EU trusted lists are supported by DSS. However, there are a few limitations:
-
Non-EU trusted lists shall have the same XML structure as EU TLs, i.e. they shall be compliant with the XSD schema.
-
There is no guarantee for a proper qualification determination as the non-EU TL shall also be compliant with EU regulations.
|
Note
|
Even though the ETSI TS 119 615 standard ([R14]) is EU-specific, the diagnostic data contains the necessary information for implementers to implement non-EU ETSI TS 119 615 status determination. |
Starting from the version 5.11, DSS supports a trust service equivalence mapping, aiming to establish recognition rules between the local legal framework and a legal framework of a third-country for qualified trust services.
The two trust service equivalence mapping schemes are supported:
-
Mutual Recognition Agreement (MRA) as per Article 14 of the eIDAS Regulation ([R12]) - establishes that "trust services provided by trust service providers established in a third country shall be recognised as legally equivalent to qualified trust services provided by qualified trust service providers established in the Union where the trust services originating from the third country are recognised under an agreement concluded between the Union and the third country in question or an international organisation in accordance with Article 218 TFEU"; and
-
Trust service equivalence mapping to facilitate the validation of third countries advanced electronic signatures and advanced electronic seals in public services of voluntary Member States, in the context of Article 27(1) and Article 37(1) of the eIDAS Regulation ([R12]).
A Pilot for the International Compatibility of Trust Services based on the Mutual Recognition Agreement (as per Article 14 of eIDAS Regulation) can be found by the link.
To enable Trust Service Equivalence Mapping in DSS, the corresponding instance of LOTLSource supporting the MRA-equivalence scheme has to be configured and provided within TLValidationJob:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/validate/mra/ThirdCountryLOTLTest.java[role=include]The standard ETSI TS 119 612 (cf. [R11]) specifies in its annex B the XML structure and the format of the signature (XAdES, enveloped signature, transformation, canonicalization, etc.). With the class TrustedListSignatureParametersBuilder, DSS is able to pre-configure the signature parameters to comply with the specifications and simplify the signature creation.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignTrustedListTest.java[role=include]