The signature validation starts from a validation of a certificate chain (cf. [CertificatePathValidation]). For a given certificate, the framework builds a certificate path until a known trust anchor (trusted list, keystore,…), validates each found certificate (OCSP / CRL) and determines its European "qualification".
To determine the certificate qualification, DSS follows the standard ETSI TS 119 615 ([R14]). It analyses the certificate properties (QCStatements, Certificate Policies, etc.) and applies possible overrules from the related trusted list ("caught" qualifiers from a trust service). More information about qualifiers can be found in the standard ETSI TS 119 612 ([R11]).
DSS always computes the status at 2 different times: certificate issuance and signing/validation time. The certificate qualification can evolve in time, its status is not immutable (e.g.: a trust service provider can lose the granted status). The eIDAS regulation ([R12]) clearly defines these different times in the Article 32 and related Annex I.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/validate/CertificateValidationTest.java[role=include]Trust anchors are an essential part of the validation process of a signature as described in section [TrustAnchors]. DSS allows configuring of various trusted certificate source(s). These sources can be defined from a TrustStore (kind of keystore which only contains certificates), a trusted list or a list of trusted lists.
If you have a collection of certificates to trust, the easier way to provide them to DSS it to use a KeyStore / TrustStore (cf. Trust Stores).
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]To generate the trust store, there’s an utility class CreateKeyStoreApp in the dss-cookbook module.
In several countries, a list of Trust Service Providers (TSP) is published. This list is usually published in a machine processable format (XML) and sometimes in a human-readable format (PDF). A standard (ETSI TS 119 612 [R11]) exists with the specifications for the XML format.
DSS contains all needed resources to download, parse, validate and interpret the trusted list contents. In DSS, it is possible to configure one or more independent trusted list(s) (aka not linked to a list of trusted lists) and/or one or more list of trusted lists.
If you want to collect your trusted certificates from trusted list(s), the TrustedListsCertificateSource is required. The trusted list(s) loading can require some time (connection time-out, xml parsing, xml validation, etc.). This process is usually executed in background. An instance of TrustedListsCertificateSource needs to be created. That will be synchronized with the TLValidationJob.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]DSS provides a possibility to use multiple trusted certificate sources at one time. An example of the configuration is provided below:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[role=include]The validation of a certificate requires the access to some other certificates from multiple sources like trusted lists, trust store, the signature itself: certificates can be contained inside any other source. Within the framework, an X509 certificate is wrapped through the class:
-
eu.europa.esig.dss.model.x509.CertificateToken
This encapsulation helps make certificate handling more suited to the needs of the validation in the context of trust. The framework associates two internal identifiers to the certificate: the DSS Id based on the certificate binary (unique for each certificate) and the Entity Id based on its public key (common to cross-signed certificates).
Certificate tokens are grouped into sources. A certificate token can be declared in several sources. The class that models a source is called:
-
eu.europa.esig.dss.spi.x509.CertificateSource
This class stores all extracted/injected certificates for a specific source (Signature, OCSP Response, Trust store, Trusted-list, etc.). All source types are specified in the enumeration:
-
eu.europa.esig.dss.enumerations.CertificateSourceType
This information is used, for example, to distinguish between the certificate from a trusted source and the others. A source has one and only one type, but a certificate token can be found in multiple sources. The DSS framework supplies some standard implementations, but also gives the possibility to implement custom solutions. Among the standard solutions you can find:
-
eu.europa.esig.dss.spi.x509.CommonCertificateSource
This is the superclass of almost of the certificate sources. It stores the extracted certificates and implements the common methods from the CertificateSource to retrieve certificate(s) by subject, public key, subject key identifier (ski), etc.
It also exposes the method CommonCertificateSource#addCertificate which gives the possibility to add manually any CertificateToken as a part of this source.
-
eu.europa.esig.dss.spi.x509.CommonTrustedCertificateSource
The CommonTrustedCertificateSource is a certificate source for trusted certificates. All added certificates are marked as trust anchors and no revocation data are required for these certificates.
-
eu.europa.esig.dss.validation.SignatureCertificateSource
This class and its sub-classes are used to extract and collect certificates from signatures / timestamps. It also has methods to retrieve certificates / certificate references by their origin (e.g. SigningCertificate attribute, DSS Dictionary, etc.).
-
eu.europa.esig.dss.spi.tsl.TrustedListsCertificateSource
Certificates coming from the list of Trusted Lists. This class inherits of CommonTrustedCertificateSource and gives the mechanism to define the set of trusted certificates (trust anchors). They are used in the validation process to decide if the prospective certificate chain has a trust anchor. See section [tlValidationJob] to get more information about trusted lists loading (e.g. EU Trusted List).
-
eu.europa.esig.dss.spi.x509.ListCertificateSource
This class follows the composite design pattern with a list of CertificateSources. That is used in the validation to retrieve all sources from the signatures / timestamps / revocation data / trusted lists / etc. It contains some methods which check over all sources to retrieve certificates or verify if a certificate is trusted.
In case when intermediate certificates are not present within a signature document, nor in trusted/adjunct sources, a certificate chain can still be built using AIA URL obtained from a certificate (See [CertificatePathValidation]).
To use AIA URLs DSS provides the interface AIASource with the following implementations:
-
DefaultAIASource- the default implementation used in DSS, allowing retrieving of certificates by AIA URL from online sources. The class allows configuring a list of accepted protocols to be used for remote requests. -
JdbcCacheAIASource- a cache AIA Source, allowing storing and accessing of certificates from a JDBC database.
An example of DefaultAIASource configuration can be found below:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/AIASourceSnippet.java[role=include]For information on how revocation of data is handled, see chapter [RevocationDataManagement].
The revocation freshness constraint (RFC) is a time interval indicating that the validation accepts CRLs that were emitted at a point in time after the validation time minus the RFC: valTime - RFC < CRL.thisUpdate.
If the RFC is respected by a CRL then that CRL can be used. Otherwise, the CRL shall be rejected and shall not be used to determine whether the certificate is revoked or not. Another CRL can be searched online. If no CRL respecting the RFC is found, then it cannot be determined whether the certificate is valid, and it is thus not possible to determine whether the signature is valid.
In case of a signature with a BASELINE-T level, the validation time can be replaced by the best-signature-time when checking the constraint. Revocation data should be issued after the best-signature-time, provided by a signature timestamp.
In case of a BASELINE-B level, there is no timestamp among the unsigned attributes. If the RFC is equal to 0 then the validation time needs to be smaller than the CRL.thisUpdate. This means that the revocation data needs to have been issued after the validation process is concluded which is not possible.
According to the ETSI TS 119 172-4 (cf. [R10]) standard, the RFC shall be set to 0 (zero). If DSS had had an RFC equal to 0 then it would invalidate all B-level signatures without a signature timestamp. Therefore, revocation freshness is not checked in DSS by default. The validation level of the check is set to IGNORE, meaning users are shown that the check exists, but it is not executed in the validation process.
As DSS allows using a custom validation policy (see AdES validation constraints/policy), it is possible to change the validation level of the check and to define a revocation freshness constraint. The validation level and time interval are defined within the <RevocationFreshness /> constraint.
For example applying of <RevocationFreshness /> constraint to a signing-certificate of a signature:
<SignatureConstraints>
...
<BasicSignatureConstraints>
...
<SigningCertificate>
...
<RevocationFreshness Level="FAIL" Unit="DAYS" Value="2" />
...
</SigningCertificate>
...
</BasicSignatureConstraints>
...
</SignatureConstraints>With the following policy, the RevocationFreshness check of the signing certificate of the signature will fail in case the revocation data is older than 2 days.
The CertificateVerifier (with default implementation CommonCertificateVerifier) determines how DSS accesses the external resources and how it should react in some occasions. This object is used to provide the following sources of information and parameters:
-
the source of trusted certificates (based on the trusted list(s) specific to the context);
-
the source of intermediate certificates used to build the certificate chain until the trust anchor. This source is only needed when these certificates are not included in the signature itself;
-
the source of AIA;
-
the source of OCSP;
-
the source of CRL;
-
set of alerts defining the behavior on various occasions.
In the current implementation this object is only used when profiles BASELINE-LT or BASELINE-LTA are created.
This configuration shall be provided into both augmentation and validation processes.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/CertificateVerifierSnippet.java[role=include]See section [Alerts] in the Annex for more information on alerts.
The validation process is driven by a set of constraints that are contained in the XML policy file.
In order to run a validation process with a custom validation policy, an XML file shall be created in compliance with the policy.xsd schema and passed to the relevant DocumentValidator as shown below.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[role=include]For a description of available for configuration constraints within the XML validation policy please see the [validationPolicyConstraints] chapter.
The validation policy allows defining different behavior for various token types or signature formats. The following groups are considered:
-
ContainerConstraints- defines rules for processing of ASiC containers validation; -
PDFAConstraints- contains checks to verify compliance of a PDF document to PDF/A specification (optional, see PDF/A for more details); -
SignatureConstraints- defines rules for signature basic building blocks processing and the related certificate chain; -
CounterSignatureConstraints- allows defining custom rules for counter signature processing; -
Timestamp- defines rules for timestamp validation; -
Revocation- defines rules for revocation data validation; -
Cryptographic- defines common rules for cryptographic validation of used algorithms. The general constraints are used when no cryptographic constraints are defined for a particular token type; -
Model- defines the way of a certificate chain processing; -
eIDAS- defines rules for validation of Trusted Lists.
Each constraint defined in the policy forces an execution of a relevant check in the validation process.
|
Note
|
If a constraint is missing in the policy - the check is not processed. |
The following constraint types are supported:
-
LevelConstraint- a simple constraint type with a defined processingLevel; -
ValueConstraint- defines a single acceptable value for the constraint; -
IntValueConstraint- defines an integer value for the constraint (the behavior depends on the check); -
MultiValuesConstraint- defines a set of accepted values relatively to the using constraint; -
TimeConstraint- defines a time unit and value for the constraint (the behavior depends on the check). See Revocation freshness for an example of the constraint use.
The Level attribute of a constraint defines a validation process behavior in case of a check failure. While used, the following behaviors apply in case of a check failure:
-
FAIL- brakes the validation process and returns the relevant indication; -
WARN- continues the validation process and returns a warning message to the validation process output; -
INFORM- continues the validation process and returns an information message to the validation process output; -
IGNORE- processes the check in a silent mode. The check is shown in the output report, but does not have impact on the process (equivalent to a not defined constraint).
When using the MultiValuesConstraint, a list of acceptable values shall be defined in the list of <Id>…</Id> elements, one for each accepted value. While doing, the following rules apply:
-
Empty list of values → accept only empty values for the item in question, fails otherwise;
-
"*"constraint value → accepts all values, reject empty list of values; -
Custom values → accepts only item values matching the constraint.
Cryptographic constraints define a list of acceptable cryptographic algorithms and their expiration dates when needed. The following settings are possible:
-
AcceptableEncryptionAlgo- defines a list of acceptable encryption algorithms. All tokens and signatures using other algorithms will be rejected. -
MiniPublicKeySize- defines the minimal allowed public key size to be used with the defined encryption algorithms. An algorithm with a key size less than the defined one will be rejected. The minimal key size if required to be defined for an encryption algorithm, otherwise all used key sizes will be rejected. -
AcceptableDigestAlgo- defines a list of acceptable digest algorithms. All tokens and signatures using other algorithms will be rejected. -
AlgoExpirationDate- defines expiration dates for the algorithms. The algorithm is rejected when it is used after the defined date. If the algorithm expiration date is not defined, or set to null, the algorithm is treated as reliable for an unlimited time.
Generally, a signature validation process outputs an indication status and a validation report as described in section [SignatureValidationModel].
In DSS, the result of the validation process consists of four elements:
-
the Simple Report,
-
the Detailed Report ,
-
the Diagnostic Data and
All these reports are represented in XML format, which allows the implementer to easily manipulate and extract information for further analysis. For each report, XML Schema and JaxB model are available as maven dependencies.
DSS also provides XSLT for generation of PDF or HTML reports (simple and detailed reports).
You will find below a detailed description of each of these elements.
The DSS validation process is based on the ETSI standard EN 319 102-1 [R09]. It is driven by the validation policy and allows long term signature validation. It not only verifies the existence of certain data and their validity, but it also checks the temporal dependencies between those elements. The signature check is done following basic building blocks. On the simplified diagram below, showing the process of the signature validation, you can follow the relationships between each building block which represents a logic set of checks used in validation process.
Note that depending on a used signature format and packaging, the whole or only a part of the original data is signed. Thus, in XAdES the signed content depends on the used transforms within a reference element, and in case of CAdES or PAdES signature the whole document must be signed.
At the end of the validation process four reports are created. They contain different detail levels concerning the validation result. They provide different kinds of visions for the validation process: macroscopic, microscopic, validation data and ETSI Validation report conformant with the standard [R09]. For more information about these reports, please refer to Simple Report, Detailed Report, Diagnostic Data and ETSI Validation Report chapters respectively.
Below is the simplest example of signature validation from an input document. The first step consists in instantiating an object named validator, which orchestrates the verification of the different rules. To perform this, it is necessary to invoke a static method fromDocument() on the abstract class SignedDocumentValidator. This method returns the object in question whose type is chosen dynamically based on the type of source document.
The next step is to create an object that will check the status of a certificate using the Trusted List model (see Trusted Lists for more information). In order to achieve this, an instance of a CertificateVerifier must be created with a defined source of trusted certificates. In our example, the trusted source is instantiated with CommonTrustedCertificateSource class. As well as a trusted source, the CertificateVerifier object needs an OCSP and/or CRL source and a TSL source (which defines how the certificates are retrieved from the Trusted Lists). See chapter Revocation Data Management for more information about revocation sources.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/validate/ValidateSignedXmlXadesBTest.java[role=include]|
Note
|
When using the TrustedListsCertificateSource class, for performance reasons, consider creating a single instance of this class and initialize it only once.
|
|
Note
|
In general, the signature must cover the entire document so that the DSS framework can validate it. However, e.g. in the case of a XAdES signature, some transformations can be applied on the XML document. They can include operations such as canonicalization, encoding/decoding, XSLT, XPath, XML schema validation, or XInclude. XPath transforms permit the signer to derive an XML document that omits portions of the source document. Consequently, those excluded portions can change without affecting signature validity. |
For execution of the validation process, DSS uses the SignedDocumentValidator class. The DSS framework provides the following implementations of the validator:
-
XMLDocumentValidator- validates documents in XML format (XAdES format); -
CMSDocumentValidator- validates documents in CMS format (CAdES format); -
PDFDocumentValidator- validates documents in PDF format (PADES format); -
JWSCompactDocumentValidator- validates documents with base64url encoded content (JAdES compact format); -
JWSSerializationDocumentValidator- validates documents in JSON format (JAdES serialization formats); -
ASiCContainerWithXAdESValidator- validates ASiC with XAdES containers; -
ASiCContainerWithCAdESValidator- validates ASiC with CAdES containers; -
DetachedTimestampValidator- validates CMS timestamps provided alone.
DSS initializes a relevant validator based on specific characteristics of an input file (e.g. a PDF file version declaration for a PDF file). It checks the file format and loads the required validator from a classpath. Below you can find a list of settings that can be used for the configuration of the class.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[role=include]The result of the validation process is based on complex algorithm and rules. The purpose of this report is to make as simple as possible the information while keeping the most important elements. Thus the end user can, at a glance, have a synthetic view of the validation. To build this report the framework uses some simple rules and the detailed report as input.
A sample of the simple validation report can be found here.
The structure of a Detailed Report is based on the ETSI EN 319 102-1 standard ([R09]).
It is a representation of steps performed during the validation process, as defined in the ETSI EN 319 102-1 standard, and structured using the processes and blocks defined in that standard:
-
Basic Building Blocks;
-
Validation Process for Basic Signatures;
-
Time-stamp validation building block;
-
Validation process for Signatures with Time and Signatures with Long-Term Validation Material;
-
Validation process for Signatures providing Long Term Availability and Integrity of Validation.
For example the Basic Building Blocks are divided into seven elements:
-
FC - Format Checking;
-
ISC - Identification of the Signing Certificate;
-
VCI - Validation Context Initialization;
-
RFC - Revocation Freshness Checker;
-
XCV - X.509 certificate validation;
-
CV - Cryptographic Verification;
-
SAV - Signature Acceptance Validation.
The following additional elements also can be executed in case of validation in the past:
-
PCV - Past Certificate Validation;
-
VTS - Validation Time Sliding process;
-
POE extraction - Proof Of Existence extraction;
-
PSV - Past Signature Validation.
To process the revocation data, DSS performs the following additional checks:
-
CRS (CertificateRevocationSelector) - validates a set of revocation data for a given certificate and returns the latest valid entry known to contain information about the concerned certificate;
-
RAC (RevocationAcceptanceCheck) - verifies whether one single revocation data is known to contain information about the concerned certificate.
Past certificate/signature validation is used when basic validation of a certificate/signature fails at the current time with an INDETERMINATE status such that the provided proofs of existence may help to go to a determined status. The process shall initialize the best-signature-time either to a time indication for a related POE provided, or the current time when this parameter has not been used by the algorithm.
-
Best-signature-time is an internal variable for the algorithm denoting the earliest time when it can be trusted by the SVA (either because proven by some POE present in the signature or passed by the DA and for this reason assumed to be trusted) that a signature has existed. [R09]
Each block contains a number of rules that are executed sequentially. The rules are driven by the constraints defined in the validation policy. The result of each rule is OK or NOT OK. The process is stopped when the first rule fails. Each block also contains a conclusion. If all rules are met then the conclusion node indicates PASSED. Otherwise, FAILED or INDETERMINATE indication is returned depending on the ETSI standard definition.
Furthermore, a module has been introduced in DSS to allow changing the language of reports generated by DSS. Currently, this is only possible for messages for the checks executed during the validation process. For more information on that topic, see section [i18nLanguage].
A sample of a DetailedReport is provided here, and an illustration on how to interpret "what went wrong" based on a detailed report is provided in [DetaliedReportInterpretation]
Diagnostic data is a data set constructed from the information contained in the signature itself, but also from information retrieved dynamically like revocation data and information extrapolated like the mathematical validity of a signature. The diagnostic data is constructed before the validation is completed, and it is used by DSS to validate the signature and create a validation report.
The diagnostic data is independent of the applied validation policy. Two different validation policies applied to the same diagnostic data can lead to different results.
It is also possible to provide a Diagnostic Data directly to the validation process without the actual signature ("replay the diagnostic data"). Since the diagnostic data is constructed before the validation, it can be used to see what the validation report would have been if certain fields of the diagnostic data would have been different. For example, changing the digest method from SHA-256 to SHA-1 would result in different validation reports. The impact of the different fields on the validation can be observed by replaying the diagnostic data.
|
Warning
|
The validation report resulting from the replay of the diagnostic data is useful for observation but cannot be used as a proof of signature validity like the validation report directly resulting from a validation process. |
Here is an example of the diagnostic data for a XAdES signature. Certain fields and certain values were trimmed or deleted to make reading easier.
The ETSI Validation Report represents an implementation of TS 119 102-2 (cf. [R13]). The report contains a standardized result of an ASiC digital signature validation. It includes the original validation input data, the applied validation policy, as well as the validation result of one or more signature(s) and its(their) constraints.
An example of the ETSI validation report can be found here.
The reports are generated in the XML format, which is not the most straightforward way of reading a report. To represent the information in a user-friendly manner stylesheets are used. A stylesheet is a set of rules that transforms XML content into an HTML or PDF representation to have a human-readable text. Refer to section [ReportStylesheets] for more information on the stylesheets used for final report generation.
It is also possible to use a stylesheet to generate an SVG image from an XML document such as the diagnostic data. (cf. [DiagnosticDataStylesheets])
While there exist four signature levels: BASELINE-B, BASELINE-T, BASELINE-LT and BASELINE-LTA (cf. [SignatureClasses]), for signature validation according to ETSI EN 319 102-1 (cf. [R09]) DSS allows processing the validation of signature with following levels:
-
BASIC_SIGNATURES- the basic signature validation process, supporting validation of signatures where the time of validation lies within the validity period of the signing-certificate and the signing-certificate is not revoked. This level corresponds to section "5.3 Validation process for Basic Signatures" of the standard. -
TIMESTAMPS- the validation process combines the basic signature validation process and the basic validation of embedded timestamp tokens, which signing-certificate is valid at validation time and not revoked. This level corresponds to section "5.4 Time-stamp validation building block" of the standard. -
LONG_TERM_DATA- performs a validation of a signature with time and signatures with long-term validation material. The signing-certificate of a signature passed to this process shall be retrospectively valid, taking into account the available signature-time-stamp and long-term validation material. This level corresponds to section "5.5 Validation process for Signatures with Time and Signatures with Long-Term Validation Material" of the standard. -
ARCHIVAL_DATA- performs validation of signatures providing long-term availability and integrity of validation material. The signing-certificate of a signature passed to this process shall be retrospectively valid with relation to all the available POEs (signature, archive time-stamps and evidence records) and long-term validation material. This level corresponds to section "5.6 Validation process for Signatures providing Long Term Availability and Integrity of Validation Material" of the standard.
For configuration examples please see [AdESValidation] section.
DSS allows adding the certificate that was used to sign the document to the inputs for the validation process. This might be useful if the signing certificate was not included as a signed attribute, for example when validating non-AdES signatures.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[role=include]To build a prospective certificate chain, a list of pre-configured trust anchors must be provided to the validator. It may be done manually by adding a keystore or a set of certificates to the trusted certificate source, or in an automated way, e.g. using the EU LOTL (see [tlValidationJob] for more information).
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/CertificateVerifierSnippet.java[role=include]DSS allows adding a set of certificates that could be used for a certificate path building, e.g. a timestamp certificate, CA certificate, and so on.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/CertificateVerifierSnippet.java[role=include]In DSS, it is possible to return the certificates, included in the signature, as output of the validation process.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[role=include]DSS allows returning the timestamps, included in the signature, as output of the validation process.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[role=include]In DSS, it is possible to return the revocation data (CRLs and OCSPs), included in the signature, as output of the validation process.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[role=include]DSS supports the use of user-friendly identifiers instead of hash-based values to represent signatures and tokens. A hash-base representation could be "S-651B6527872B53437C7B9A8696BD9F7A6C311CE6EE418EFE34A4A994C05D08C8". The same information but presented in a user-friendly way is a string composed of "SIGNATURE" to indicate that it is a signature, the name in the certificate chain, the signature claimed time and so on.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[role=include]With DSS, it is possible to add a "Semantics" section at the end of the reports explaining the meaning of the result indications, i.e. TOTAL_PASSED, PASSED, INDETERMINATE, NO_CERTIFICATE_CHAIN_FOUND.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[role=include]Since version 6.1 DSS provides a functionality allowing configuration of the validation process on a step of validation data preparation, including certificate chain building, revocation data extraction, custom validation checks.
The behavior may be configured with a ValidationContextExecutor provided to a DocumentValidator, as below:
-
DefaultValidationContextExecutor- performs validation of the embedded tokens, including the certificate chain building, revocation data request, etc. This is a default executor used withinSignedDocumentValidator.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[role=include]-
CompleteValidationContextExecutor- performs validation of the embedded tokens, including the certificate chain building, revocation data request, as well as a processing of additional validation checks, such as the ones configured with custom alerts within a CertificateVerifier configuration. When alerts are configured with exceptions, this executor allows a "fail fast" behavior on a signature validation (e.g. in case of a cryptographically invalid signature value).
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[role=include]-
SkipValidationContextExecutor- skips validation of embedded tokens, including certificate chain building and revocation data request.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[role=include]Since version 5.13 DSS provides a functionality of evidence records validation in relation to digital signatures or alone.
DSS provides support of RFC 6283 XML Evidence Records (cf. [R22]) and RFC 4998 Evidence Record Syntax (cf. [R23]).
DSS performs cryptographic validation of the evidence record’s hash tree, as well as processing of evidence record as a material for achieving a long-term preservation and availability as per ETSI EN 319 102-1 (cf. [R09]).
One or both following modules should be included to the project in order to add support of evidence records on validation:
-
dss-evidence-record-xml- for validation of RFC 6283 XML Evidence Records; -
dss-evidence-record-asn1- for validation of RFC 4998 Evidence Records.
For instance, in order to add support of XML evidence records on validation, the dependency should be added to a pom.xml file within your project as following:
<dependency>
<groupId>eu.europa.ec.joinup.sd-dss</groupId>
<artifactId>dss-evidence-record-xml</artifactId>
</dependency>Please note, that as evidence records processing is a part of "5.6 Validation process for Signatures providing Long Term Availability and Integrity of Validation Material" process, the validation level within document validator shall be set to ARCHIVAL_DATA in order to perform validation of evidence records. See Validation level for more information.
DSS is able to validate an evidence record as a material providing a signature’s proof of existence (POE) in the following circumstances:
-
as a detached evidence record applied on the whole document containing the signature(s) (the support is independent of the signature’s type);
-
as an embedded evidence record within an ASiC container, conformant to the specification within ETSI EN 319 162-1 (cf. [R04]) standard. This includes support of ASiC-E and ASiC-S container types with XAdES or CAdES signatures.
In order to provide one or multiple detached evidence records covering the complete signature’s document to the signature validation process, the evidence record document(s) should be provided to the corresponding instance of a DocumentValidator performing validation of the signature:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[role=include]The validator will load a relevant implementation supporting processing of the given evidence record format, providing the corresponding dependency is loaded within the classpath (see above for pom.xml file configuration). If the evidence record is valid, the validator will use the time of the first embedded time-stamp as a proof of existence (POE) time of the signature and the covered data objects.
In addition to the validation of signatures with evidence records, it is also possible to validate evidence records alone against the given data objects covered by the hash tree.
The validation process verifies the cryptographic validity of the hash tree, providing that the hashes of the given archive data objects are present at the first level of the hash tree, as well as perform validation of the evidence record’s time-stamps as per ETSI EN 319 102-1 (cf. [R09]).
To validate an evidence record, one may use the class EvidenceRecordValidator, which will load the corresponding implementation capable of processing the evidence record according to its type:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/EvidenceRecordValidatorTest.java[role=include]It is also possible to validate an evidence record document using a global SignedDocumentValidator, which is capable of distinguishing the document containing an evidence record from a signature or a time-stamp:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/EvidenceRecordValidatorTest.java[role=include]The choice between two approaches have no impact on the final validation process, provided that the corresponding implementation of a document factory is configured within META-INF/services folder. See DocumentValidator implementations for more information.
In order to facilitate preservation of data objects and creation of evidence records, DSS provides utility classes for computation of archive data objects hashes, represented by data or signature documents.
|
Note
|
DSS does not provide a functionality for creation of evidence records. Creation of evidence records would require a hash preservation system, which is out of scope of DSS. |
The following classes are provided, based on the target implementation of evidence records:
-
XMLEvidenceRecordDataObjectDigestBuilder(part ofdss-evidence-record-xmlmodule) - creates digest for a given document to be protected by an RFC 6283 XMLERS Evidence Record (cf. [R22]). Canonicalizes XML data objects.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ERDataObjectBuilderTest.java[role=include]-
ASN1EvidenceRecordDataObjectDigestBuilder(part ofdss-evidence-record-asn1module) - creates digest for a given document to be protected by an RFC 4998 Evidence Record Syntax (ERS) (cf. [R23]).
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ERDataObjectBuilderTest.java[role=include]link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ERDataObjectBuilderTest.java[role=include]-
CAdESEvidenceRecordDigestBuilder(part ofdss-cadesmodule) - creates digest for a CMS or CAdES signature to be protected by an embedded evidence-record. Can be used only for Evidence Record Syntax (cf. [R23]) evidence record implementation.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ERDataObjectBuilderTest.java[role=include]-
ASiCEvidenceRecordDigestBuilder(part ofdss-asic-commonmodule) - creates digest for documents embedded within an ASiC container to be protected by an evidence-record. Can be used for both XMLERS (cf. [R22]) and Evidence Record Syntax (cf. [R23]) evidence record implementations, as well as for XAdES, CAdES and time-stamp ASiC containers.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ERDataObjectBuilderForASiCTest.java[role=include]In order to facilitate creation of evidence record within an ASiC container, an ASiCEvidenceRecordManifestBuilder class has been introduced helping to build an ASiCEvidenceRecordManifest*.xml file to be linked to a target evidence record:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ERDataObjectBuilderForASiCTest.java[role=include]|
Note
|
In case of creation of evidence-record detached from the signature document, one of the XMLEvidenceRecordDataObjectDigestBuilder or ASN1EvidenceRecordDataObjectDigestBuilder classes shall be used.
|
|
Warning
|
Always ensure a correct utility class is chosen based on your implementation of evidence-records. Usage of a wrong class may result to an erroneously computed hash and therefore invalidity of the evidence-record. |
In addition to digest computation for evidence record creation, DSS provides classes for digest computation on evidence record’s renewal, whether it is a time-stamp renewal or a hash-tree renewal (with a possibility to define a new Digest Algorithm or a canonicalization method for XMLERS).
The following classes are provided:
-
XMLEvidenceRecordRenewalDigestBuilder(part ofdss-evidence-record-xmlmodule) - creates digest for time-stamp or hash-tree renewal of an RFC 6283 XMLERS Evidence Record (cf. [R22]).
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ERDataObjectBuilderTest.java[role=include]-
ASN1EvidenceRecordRenewalDigestBuilder(part ofdss-evidence-record-asn1module) - creates digest for time-stamp or hash-tree renewal of an RFC 4998 ERS Evidence Record (cf. [R23]).
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/ERDataObjectBuilderTest.java[role=include]For a signature document, a signature policy validation or an evidence record document, DSS is able to load a corresponding implementation of validator for the given document format at runtime using a ServiceLoader (e.g. XMLDocumentValidator for XAdES signature).
DSS may load the relevant implementation for one of the following interfaces:
-
DocumentValidationFactory- checks a provided signed file’s format and loads a relevant validator; -
EvidenceRecordValidatorFactory- checks a provided evidence record file’s format and loads a relevant validator; -
SignaturePolicyValidator- checks a signature policy file and loads a relevant validator to be able to process the detected format.
|
Warning
|
If no appropriate available implementation is found, an exception will be thrown. |
For more information about ServiceLoader usage please refer to the chapter [ServiceLoaderAdvanced].
This factory is used to create a required instance of a DocumentValidator based on the provided file’s format (signature or timestamp). An implementation shall process a file format check and load the related SignedDocumentValidator implementation to be used for the file’s validation.
The following implementations are present in DSS:
-
CMSDocumentValidatorFactory: loadsCMSDocumentValidator, used for a CAdES validation (delivered indss-cadesmodule); -
XMLDocumentValidatorFactory: loadsXMLDocumentValidator, used for a XAdES validation (delivered indss-xadesmodule); -
PDFDocumentValidatorFactory: loadsPDFDocumentValidator, used for a PAdES validation (delivered indss-padesmodule); -
JAdESDocumentValidatorFactory: loadsJWSCompactDocumentValidatororJWSSerializationDocumentValidator, depending on provided JSON signature type (delivered indss-jadesmodule); -
ASiCContainerWithCAdESValidatorFactory: loadsASiCContainerWithCAdESValidator(delivered indss-asic-cadesmodule); -
ASiCContainerWithXAdESValidatorFactory: loadsASiCContainerWithXAdESValidator(delivered indss-asic-xadesmodule); -
DetachedTimestampValidatorFactory: loadsDetachedTimestampValidator, for an independent timestamp validation (delivered indss-documentmodule).
Additionally, DSS supports loading of an Evidence Record validator using SignedDocumentValidator. See Evidence Record Validator for more information.
A validator implementation for an evidence record document can be loaded using either a SignedDocumentValidator or an EvidenceRecordValidator explicitly.
The following implementation of a validator factory is present in DSS:
-
XMLEvidenceRecordValidatorFactory: loadsXMLEvidenceRecordValidator, used for an RFC 6283 XMLERS Evidence Record (cf. [R22]) validation (delivered indss-evidence-record-xmlmodule); -
ANS1EvidenceRecordValidatorFactory: loadsASN1EvidenceRecordValidator, used for an RFC 4998 Evidence Record Syntax (ERS) (cf. [R23]) validation (delivered indss-evidence-record-asn1module).
During the signature validation process, the signature policy shall be validated to verify that the retrieved policy is the one that was used for the signature creation. This can be achieved by verifying whether the digest within the SignaturePolicyIdentifier signed attribute of the signature matches the computed digest of the retrieved signature policy document.
The signature policy document can be retrieved from the signature itself when a SignaturePolicyStore attribute is present. It can also be retrieved from online or local sources using the SignaturePolicyProvider class (e.g. by URL from the Internet).
The interface SignaturePolicyValidator is used to validate a signature policy reference extracted from a signature. The choice of the implementation is format-specific. The following implementations are provided:
-
BasicASN1SignaturePolicyValidator: validates ASN.1 signature policies; -
XMLSignaturePolicyValidator: validates XML signature policies supporting transformations; -
NonASN1SignaturePolicyValidator: validates a policy by digest computed on an original file’s content; -
ZeroHashSignaturePolicyValidator: validates a policy if "zero hash" value is defined in a signature (see [R02]); -
EmptySignaturePolicyValidator: is proceeded if a policy file is not found or not accessible.
"Shadow attack" is a class of attacks on a signed PDF document that constitutes a change of a visual content of a document after the signature has been made. Due to a structure of PDF document, the signature stays cryptographically valid even after the content’s modification has been taken place. There is no known algorithm to detect the malicious change with 100% guarantee. For more information, please refer to the website.
DSS provides a set of own utils to detect the "shadow attack" on a signed PDF document. The following algorithms have been introduced:
-
Page amount difference- the validation tool compares the number of pages between the obtained PDF and signed revision. If the numbers do not match, the validation fail. The validation level can be configured within the AdES validation constraints/policy with the constraint<PdfPageDifference>. -
Annotations overlap- DSS checks if any annotation overlaps occurred. The overlapping is potentially dangerous, because some annotations can cover a visual content, e.g. forms and signature fields. How this check is applied can be configured with the constraint<PdfAnnotationOverlap>. -
Visual difference- DSS verifies the visual difference between the provided document and signed revision, excluding the newly created annotations (between the validating revisions). How this check is applied can be configured with the constraint<PdfVisualDifference>.
The verification of points introduced above may be configured within an instance of IPdfObjFactory provided to a PdfDocumentValidator. By default, an instance of DefaultPdfDifferencesFinder class is used. For an example of PdfDifferencesFinder configuration, please see below:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/PAdESModificationDetection.java[role=include]As an additional tool to detect malicious changes within a PDF document, an object modification detection has been introduced in DSS 5.10. The util detects all changes occurred within a PDF document after a concerned signature’s or a timestamp’s revision.
The detected modifications are categorized to four categories, depending on the "insecurity" level:
-
Extension change is a secure change defining modification occurred within a PDF document for signature augmentation reasons (e.g. a document timestamp or a /DSS dictionary revision was added);
-
Signature or Form fill is a change occurred for a signature, visual timestamp creation or available form filling (can be restricted by /DocMDP dictionary);
-
Annotation creation change defines a created or modified annotation (can be restricted by /DocMDP dictionary);
-
Undefined change defines a modification that could not be categorized to the upper three categories. It is recommended to investigate the modification in details.
The following constraints are available to verify the validity of a signature based on encountered object modifications:
-
<DocMDP>- when a/DocMDPdictionary is present within a signature, verifies whether the performed modifications in a PDF document are permitted according to the defined level. -
FieldMDP- when a/FieldMDPdictionary is present within a signature, verifies whether the performed modifications in a PDF document are permitted according to the defined level. -
SigFieldLock- when a/FieldMDPdictionary is present within a signature, verifies whether the performed modifications in a PDF document are permitted. -
FormFillChanges- verifies whether the document contains form fill-in or signing modifications. -
AnnotationChanges- verifies whether the document contains annotation creation, modification or deletion changes. -
UndefinedChanges- verifies whether the document contains modifications that cannot be unambiguously identified.
The search of the object differences may be configured within an instance of IPdfObjFactory provided to a PdfDocumentValidator. The categorization is done by a PdfObjectModificationsFilter class.
An example of a PdfObjectModificationsFinder customization is provided below:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/PAdESModificationDetection.java[role=include]The aforementioned security checks may be disabled in favor of performance on signature validation. For this you will need to define the following configuration within IPdfObjFactory provided to the used PDFDocumentValidator:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/PAdESSkipModificationDetection.java[role=include]PDF files can be protected using a password. DSS does not support creation of password-protected PDFs, however it is able to sign, extend, as well as validate existing password-protected documents, if a proper password has been provided.
To sign or extend a password-protected document, a password string shall be provided within PAdESSignatureParameters:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignProtectedPdfPadesBLevelTest.java[role=include]To validate a password-protected PDF, a password string shall be provided within an instance of PDFDocumentValidator:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignProtectedPdfPadesBLevelTest.java[role=include]Since version 5.12 DSS provides a possibility to validate conformance of a PDF document against the PDF/A specification. The verification process is conducted by a VeraPDF library.
|
Note
|
DSS does not claim compliance with the PDF/A specification for created or extended PDF documents with services provided in DSS. The PDF/A verification feature is provided exclusively for validation purposes. |
The PDF/A validation is present in a dedicated dss-pdfa module that makes the inclusion of PDF/A validation process optional and does not interfere with the default PAdES validation.
In order to include PDF/A validation to your project, the dss-pdfa module shall be defined within pom.xml file of the project as a dependency:
<dependency>
<groupId>eu.europa.ec.joinup.sd-dss</groupId>
<artifactId>dss-pdfa</artifactId>
</dependency>|
Note
|
PDF/A module does not replace dss-pades-pdfbox or dss-pades-openpdf implementation. If required, dss-pdfa has to be included in addition to the chosen implementation.
|
The module dss-pdfa implements its own DocumentValidator, as well as DocumentValidatorFactory. In order to perform PDF/A validation on a PDF document, the class PDFADocumentValidator has to be used:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBTest.java[role=include]To load the PDFADocumentValidator instead of default PDF validator using SignedDocumentValidator.fromDocument(DSSDocument) method, the class name eu.europa.esig.dss.pdfa.validation.PDFADocumentValidatorFactory shall be defined within eu.europa.esig.dss.validation.DocumentValidatorFactory file in the directory src/main/java/resources/META-INF/services/, as following:
eu.europa.esig.dss.pdfa.validation.PDFADocumentValidatorFactoryIt is also possible to enforce verification of a PDF/A profile and its validity during the signature validation process using the customized XML validation policy (see AdES validation constraints/policy). See [PdfaConstraints] for more details.
Since version 6.1 DSS introduces a new interface DocumentAnalyzer with format specific implementations, providing a document reading, validation data (certificates and revocation data) handling and cryptographic validation of extracted tokens functionalities. This class allows execution of a signed document validation without running ETSI EN 319 102-1 (cf. [R09]) validation process and building reports, which implies no JAXB loading.
|
Note
|
DocumentAnalyzer implementations are used in the background of DocumentValidator classes.
|
The configuration of DocumentAnalyzer is similar to a SignedDocumentValidator, with the exception to ETSI EN 319 102-1 validation standard specific parameters.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/DefaultDocumentAnalyzerTest.java[role=include]|
Warning
|
Please note that the validation process with DocumentAnalyzer is not complete, and may lack certain ETSI EN 319 102-1 validation standard checks.
|