1. Generic information1.1. The ProjectThe DSS (Digital Signature Service) project is an open-source software library, aimed at providing implementation of the standards for Advanced Electronic Signature creation, augmentation and validation in line with European legislation and the eIDAS Regulation in particular. Show
This project is available in Java language. 1.2. Purpose of the documentThis document describes some examples of how to develop in Java using the DSS framework. The aim is to show to the developers, in a progressive manner, the different uses of the framework. It will familiarize them with the code step by step. 1.3. Scope of the documentThis document provides examples of code which allow easy handling of digital signatures. The examples are consistent with the Release 5.11.1 of DSS framework which can be downloaded via the webpage. Three main features can be distinguished within the framework :
In a more detailed manner the following concepts and features are addressed in this document:
This is not an exhaustive list of all the possibilities offered by the framework and the proposed examples cover only the most useful features. However, to discover every detail of the operational principles of the framework, the JavaDoc is available within the source code.
1.4. Available demonstrationsWith the framework, some demonstrations are provided:
The requirements and build instructions for DSS demonstrations can be found in the section DSS Demonstrations.
1.5. License1.6. Abbreviations and AcronymsTable 1. Abbreviations and Acronyms
1.7. ReferencesTable 2. References
1.8. Useful links
2. How to start with DSS2.1. Integration instructionsThe section explains the basic steps required to successfully integrate the DSS components to your project. 2.1.1. DSS CoreThis section explains the usage and build requirements for DSS framework. 2.1.1.1. RequirementsThe latest version of DSS framework has the following minimal requirements:
2.1.1.2. Adding as Maven dependency2.1.1.2.1. Using Maven Central (starting from version 5.11.1) The simplest way to include DSS to your project is to use Maven Central repository. To do this you need to define the required modules within a list of dependencies in
See Maven modules to get familiar with the available modules in DSS. Refresh your project in order to download the dependency and you will be able to use all modules of the DSS framework. Your project needs to be refreshed every time you add a new dependency. 2.1.1.2.2. Using Nexus repository (version 5.11 and before) To include DSS artifacts published to Nexus Repository (versions up to and including DSS 5.11), the following configuration is required within
2.1.1.2.3. Integration with Bill of Materials (BOM) module As DSS represents a multi-modules framework that benefits users from a more effective way of using the library (include only what you need), it has a downside that makes it difficult to keep versions of all modules up-to-date. The "bill of materials" (BOM) solution, represented by The root
See Maven modules to get familiar with the available modules in DSS. 2.1.1.3. Maven build and profilesIn order to use a customized bundle of DSS, you may want to build the DSS Core framework modules.
A simple build of the DSS Maven project can be done with the following command:
This installation will run all unit tests present in the modules, which can take more than one hour to do the complete build. In addition to the general build, the framework provides a list of various profiles, allowing a customized behavior:
In order to run a build with a specific profile, the following command must be executed: mvn clean install -P *profile_name* 2.1.1.4. Documentation generationIn order to generate HTML and PDF documentation for the DSS project, the mvn clean install -P asciidoctor 2.1.1.5. Javadoc generationIn order to generate HTML Javadoc, you will need to build the DSS Core completely. 2.1.2. DSS Demonstrations2.1.2.1. RequirementsThe minimal requirements to build/run DSS Demonstrations:
2.1.2.2. Ready to use solutions2.1.2.2.1. DSS Web Application The ready to use webapp allows testing the different functionalities offered in DSS without needing to dive into the implementation. The DSS demo is also available as a ready to use downloadable webapp. To use it, you need to complete the following steps:
2.1.2.3. Maven build instructionsThe build of the project can be done similarly to the DSS Core framework build with the command
2.1.2.3.1. DSS Web Application build To build the DSS Web Application the following modules are required:
After a successful build, in the directory If during TL/LOTL loading you experience problems with some particular Trusted Lists, please refer the Java Keystore Management chapter for a resolution. The documentation and javadoc will be copied automatically from the built DSS Core and made available on the following addresses respectively:
In order to build a
bundle for JDK 18, the following profile can be used from the mvn clean install -P java18 This will create a bundle with Tomcat 9. 2.1.2.3.2. Integration tests The mvn clean install -P run-integration-test 2.1.2.3.3. DSS Standalone Application build In order to build the standalone application, the following modules are required:
If the build is successful, you will be able to find out the following containers in the directory
In order to launch the application, you will need to extract the archive and run the file 2.2. DSS framework structureDSS framework is a Maven multi-module project. See below the specifications about provided modules within the DSS core. 2.2.1. Maven modules2.2.1.1. Shared modulesdss-enumerations Contains a list of all used enumerations in the DSS project. dss-alertsAllows configuration of triggers and handlers for arbitrary defined events. dss-jaxb-parsersContains a list of all classes used to transform JAXB objects/strings to Java objects and vice versa. 2.2.1.2. JAXB model modulesspecs-xmldsig W3C XSD schema for signatures http://www.w3.org/2000/09/xmldsig specs-xadesETSI EN 319 132-1 XSD schema for XAdES. specs-trusted-listETSI TS 119 612 XSD schema for parsing Trusted Lists. specs-validation-reportETSI TS 119 102-2 XSD schema for the Validation report. specs-asic-manifestETSI EN 319 162 schema for ASiCManifest. specs-saml-assertionOASIS schema for SAML Assertions. dss-policy-jaxb JAXB model of the validation policy. dss-diagnostic-jaxbJAXB model of the diagnostic data. dss-detailed-report-jaxbJAXB model of the detailed report. dss-simple-report-jaxbJAXB model of the simple report. dss-simple-certificate-report-jaxbJAXB model of the simple report for certificates. 2.2.1.3. JSON validation modulesspecs-jws JSON Schemas based on the RFC 7515 specifications ([R05]). specs-jadesETSI TS 119 182-1 JSON Schemas for JAdES ([R20]). 2.2.1.4. Utils modulesdss-utils API with utility methods for String, Collection, I/O,… dss-utils-apache-commonsImplementation of dss-utils with Apache Commons libraries. dss-utils-google-guavaImplementation of dss-utils with Google Guava. 2.2.1.5. i18ndss-i18n a module allowing internationalization of generated reports. 2.2.1.6. Core modulesdss-model Data model used in almost every module. dss-crl-parserAPI to validate CRLs and retrieve revocation data dss-crl-parser-streamImplementation of dss-crl-parser which streams the CRL. dss-crl-parser-x509crlImplementation of dss-crl-parser which uses the java object X509CRL. dss-spiInterfaces and util classes to process ASN.1 structure, compute digests, etc. dss-documentCommon module to sign and validate document. This module doen’t contain any implementation. dss-serviceImplementations to communicate with online resources (TSP, CRL, OCSP). dss-tokenToken definitions and implementations for MS CAPI, MacOS Keychain, PKCS#11, PKCS#12. validation-policyBusiness of the signature’s validation (ETSI EN 319 102 / TS 119 172-4). dss-xadesImplementation of the XAdES signature, augmentation and validation. dss-cadesImplementation of the CAdES signature, augmentation and validation. dss-jadesImplementation of the JAdES signature, augmentation and validation. dss-padesCommon code which is shared between dss-pades-pdfbox and dss-pades-openpdf. dss-pades-pdfboxImplementation of the PAdES signature, augmentation and validation with PDFBox. dss-pades-openpdfImplementation of the PAdES signature, augmentation and validation with OpenPDF (fork of iText). dss-asic-commonCommon code which is shared between dss-asic-xades and dss-asic-cades. dss-asic-cadesImplementation of the ASiC-S and ASiC-E signature, augmentation and validation based on CAdES signatures. dss-asic-xadesImplementation of the ASiC-S and ASiC-E signature, augmentation and validation based on XAdES signatures. dss-tsl-validationModule which allows loading / parsing / validating of LOTL and TSLs. 2.2.1.7. WebServicesdss-common-remote-dto Common classes between all remote services (REST and SOAP). dss-common-remote-converterClasses which convert the DTO to DSS Objects. dss-signature-dto Data Transfer Objects used for signature creation/augmentation (REST and SOAP). dss-signature-remoteCommon classes between dss-signature-rest and dss-signature-soap. dss-signature-rest-clientClient for the REST webservices. dss-signature-restREST webservices to sign (getDataToSign, signDocument methods), counter-sign and augment a signature. dss-signature-soap-clientClient for the SOAP webservices. dss-signature-soapSOAP webservices to sign (getDataToSign, signDocument methods), counter-sign and augment a signature. dss-server-signing-dto Data Transfer Objects used for the server signing module (REST and SOAP). dss-server-signing-commonCommon classes for server signing. dss-server-signing-restREST webservice for server signing. dss-server-signing-rest-clientREST client for server signing (sign method). dss-server-signing-soapSOAP webservice for server signing. dss-server-signing-soap-clientSOAP client for server signing (sign method). dss-validation-dto Data Transfer Objects used for signature validation (REST and SOAP). dss-validation-commonCommon classes between dss-validation-rest and dss-validation-soap. dss-validation-rest-clientClient for the REST signature-validation webservices. dss-validation-soap-clientClient for the SOAP signature-validation webservices. dss-validation-restREST webservices to validate a signature. dss-validation-soapSOAP webservices to validate a signature. dss-certificate-validation-dto Data Transfer Objects used for certificate validation (REST and SOAP). dss-certificate-validation-commonCommon classes between dss-certificate-validation-rest and dss-certificate-validation-soap. dss-certificate-validation-rest-clientClient for the REST certificate-validation webservice. dss-certificate-validation-soap-clientClient for the SOAP certificate-validation webservice. dss-certificate-validation-restREST webservice to validate a certificate. dss-certificate-validation-soapSOAP webservice to validate a certificate. dss-timestamp-dto Data Transfer Objects used for timestamp creation. dss-timestamp-remote-commonCommon classes between dss-timestamp-remote-rest and dss-timestamp-remote-soap. dss-timestamp-remote-rest-clientClient for the REST timestamp webservice. dss-timestamp-remote-soap-clientClient for the SOAP timestamp webservice. dss-timestamp-remote-restREST webservice to create a timestamp. dss-timestamp-remote-soapSOAP webservice to create a timestamp. 2.2.1.8. Other modulesdss-test Mock and util classes for unit tests. dss-cookbookSamples and documentation of DSS used to generate this documentation. dss-jacoco-coverageModule which is used to collect a test coverage for all modules. dss-bomModule which helps the integration with all DSS modules and the version. 2.2.2. Specific modulesSome modules of the DSS framework have a specific behavior and has to be handled accordingly. DSS contains a bundle of JAXB-based modules, generating Java classes at runtime based on XSD-schema. When any change is made in the XSD, the classes of the module are being re-generated according to the change. The following modules present this behavior:
Specific modules with JWS and JAdES specifications exist. These modules allow to validate the generated JSON against the related JSON Schema :
Also, as it was explained in the previous section, some modules are required to be built completely in order for their dependent modules to be built when using a quick profile, namely:
The modules contain common interfaces, used in other DSS modules, as well as unit tests to ensure the same behavior between their implementations. 2.2.3. DSS-demonstration modules
3. Electronic signatures and DSS3.1. EU legislationIn the European Union the following legislation have had a considerable impact on the topic of electronic and digital signatures:
The eIDAS Regulation repealed Directive 1999 and became official on July 1, 2016. A Regulation is a law that applies across all EU Member States (MS). eIDAS aims for interoperability between the EU MS, among others in the field of the electronic signature, by building compatible trust service frameworks. One of the main aspects of the eIDAS Regulation, is that where the Directive mainly covered Certificate Service Providers, the eIDAS Regulation expands on that concept and introduces the new concepts of trust services and trust service providers which is detailed in the next subsection. 3.1.1. Trust Service ProviderA Trust Service Provider (TSP) is a natural or legal person who provides one or more trust services. A trust service is an electronic service related, among others, to the creation, validation and preservation of electronic signatures, timestamps, and certificates. Given that a TSP can provide a combination of trust services, a TSP can take one or more of the following roles
A TSP can be either a qualified or non-qualified trust service provider. All TSPs no matter if qualified or not have the following obligations and requirements
This ensures the validity and security of the trust services that TSPs provide, such as the integrity of the data that was used for certificate and signature creation as well as the security of the signing keys. A qualified trust service provider (QTSP) is a TSP that provides one or more qualified trust services and is included in a Trusted List (cf. Trusted Lists). Some aspects are specific to QTSPs and follow from the requirements of eIDAS
3.2. Electronic and digital signaturesThe terms “Electronic Signature” and “Digital Signature” are often used interchangeably however they are very distinct concepts as "electronic signature" is a legal concept, whereas "digital signature" is a technical concept that is used to provide a concrete instance of electronic signatures. In the eIDAS Regulation, and electronic signature is defined (legally) as "data in electronic form which is attached to or logically associated with other data in electronic form and which is used by the signatory to sign". An electronic signature does not necessarily guarantee that the signature process is secure nor that it is possible to track the changes that have been brought to the content of a document after it was signed. This depends on the category of the electronic signature. Indeed, beyond the concept of "simple" electronic signatures (SES) the Regulation further defines Advanced Electronic Signatures (AdES) and Qualified Electronic Signatures (QES). A Simple Electronic Signature can cover a very broad range of data, such as a name written at the end of an email or an image added to a document. An Advanced Electronic Signature is an electronic signature that has the following properties:
A Qualified Electronic Signature is an AdES that is based on a qualified certificate for electronic signatures (cf. Digital certificate) and that has been generated by a qualified signature creation device (QSCD). QES have the same legal value as handwritten signatures. When an electronic signature is a QES, there is a reversal of the burden of proof. There is a presumption that a person has signed until a proof is given that the person did not sign. A digital signature is a technical concept that is based on a Public Key Infrastructure (PKI, cf.Simplified PKI model) and involves, among others, public key cryptography and public key certificates (cf. Digital certificate). Digital signatures can be used to ensure the unique identification of the signer, the authenticity of the signature and the integrity of the data. The identification of the signer as well as the authenticity of the signature are guaranteed by decrypting the digital signature value using a public key attested by a public key certificate (cf. Digital certificate). The component of the digital signature that allows detecting whether signed data has been tampered with is a cryptographic function called a hash function. "AdES digital signatures" are digital signature formats that have been developped by ETSI to support the eIDAS Regulation and provide a way to create digital signatures that can meet the legal requirements for AdES and QES. 3.3. Digital signatures conceptsThis section aims to briefly introduce PKI-based digital signature concepts, more specifically concepts related to digital signatures supported by X.509 digital certificates issued by Certification Authorities (CA), and making use of asymmetric cryptography. Such signatures are the kind of signatures that are handled in DSS. For the rest of this section, the creation of a digital signature value is assumed to be the encryption of the digest of a data object using a private key for which there exists a corresponding X.509 public key certificate issued by a CA. For the purpose of introducing those concepts, we will first provide a simplified description of the PKI model in which digital signatures are created. The goal of this model is not to provide an accurate and exhaustive description and definition of a PKI but to provide a basis for introducing the main PKI concepts that are useful to DSS users. Suggestions for improvement are welcomed and can be proposed via PRs in the DSS GitHub. 3.3.1. Simplified PKI modelA (simplified) description of the PKI model and where DSS is involved in that model is given in the figure below. In this simplified model, a PKI is composed of:
In turn, DSS within that model, can be used to implement Signature creation applications (SCA) and/or Signature Validation Applications (SVA) Each of those concepts are further detailed in the next sections. 3.3.2. Digital certificateAs mentioned before, in the present context, digital signatures are supported by public key certificates. Public key certificates are data structures that binds an entity to a public key and that are signed by a third party, they provide a proof of authenticity of the public key. The ITU-T X.509 Recommendation is a standard describing (among others) such a data structure, and public key certificates structured as per the specifications provided in that standard are commonly referred to as “X.509 public key certificates”. Furthermore, the IETF published the RFC 5280 ([R21]) which specifies a profile for X.509 public key certificates (and certificate revocation lists). For the remainder of this document, X.509 public key certificates are assumed to be profiled as per RFC 5280. Certificates can be end-entity certificates or CA certificates:
Certificates have a defined validity period during which the CA having issued the certificate guarantees the correctness of its content. During that validity period, they may however be revoked or suspended, for instance when the entity to which the certificate has been issued has lost control of the corresponding private key. A certificate contains among other things information on:
3.3.3. CRLs and OCSPAs previously mentionned, a certificate can be revoked or suspended. This information is usually provided in the form of a Certificate Revocation List (CRL), or through the Online Certificate Status Protocol (OCSP). A CRL is a list of revoked (and/or suspended) certificates that is digitally signed and published by a CRL issuer. This issuer can be the CA having issued the certificates listed in the CRL, or it can be another CA in which case the CRL is called an “indirect CRL”. RFC 5280 ([R21]) provides a profile for X.509 CRLs. The OCSP is a protocol defined in RFC 6960 ([R22]) that enables the determination of the (revocation) status of a certificate without the use of a CRL. An OCSP request, containing (among other things) information on the certificate for which the (revocation) status is requested, is sent to a server and a response, containing information of that (revocation) status, is provided by an OCSP responder. OCSP responses are signed by the OCSP responder, and the OCSP responder can be the CA having issued the certificate or another CA in which case the OCSP responder is called a “delegated OCSP responder”. RFC 5280 section 6.3 describes an algorithm for the validation of CRLs, while Common PKI v2.0 part 5 section 2.3 ([R23]) describes an algorithm for checking the revocation status of a certificate using CRLs and OCSP responses. 3.3.3.1. Certificate AuthorityCertification Authorities are entities issuing certificates and guaranteeing the correctness of their content. They manage the whole lifecycle of the certificates they issue, including the revocation services. Throughout this document, they will be denominated as:
3.3.3.2. Trust Anchors and Trust StoresWithout going into the details and inner workings of the hierarchical trust model (this document does not intend to discuss the soundness of this model, the soundness of transitivity of trust, etc.), when a user is looking to validate a certificate, that is the user’s need to decide whether they can trust the binding between the public key and the subject of that certificate, they will make use of so called “trust anchors”. A trust anchor, in the context of certificate validation, is a CA that is trusted by the user in such a way that if there exists a valid chain of certificate from that CA to a certificate, the user trusts the correctness of the information contained in that certificate taking into consideration the (revocation) status of that certificate. The wording “valid chain of certificate” used above is voluntarily informal, but it can be more formally defined as meaning that there exists a prospective certification path such that the output of the certification validation path algorithm (see Certificate Chain and Certification Path Validation) provided with, as inputs, that prospective certification path, the trust anchor information and possibly other inputs, is a success indication. Trust anchor information can be, and is often, provided as a (potentially self-signed) public key certificate. A trust store is, in turn, a list of trust anchor information that can be, and is often, a list of directly trusted public key certificates. 3.3.4. Trusted List (TL)3.3.4.1. EU MS Trusted ListTrusted lists, as they are used in the EU/EEA, are a legal instrument used to provide, among other things, information on the qualified status of trust services. Technically, they take the form of an XML structure formatted as specified in the standard ETSI TS 119 612 ([R11]). Trusted lists can be used in a similar way to trust stores in that one can use, for instance, the public key certificates that are listed as the digital identity of qualified trust services issuing qualified certificates as trust anchors for the purpose of validating certificates, however there are significant differences between the usage of trusted lists and the usage of classic trust stores. Below is a non-exhaustive list of such differences:
3.3.4.2. List of Trusted Lists (LOTL)A List of Trusted Lists (LOTL) is a list that contains:
In the EU/EEA context, a LOTL is published by the European Commission at a secure location that is made publicly available on the Official Journal of the European Commission (OJEU). It is available in an XML format which is suitable for automated processing. This format of the LOTL is digitally signed/sealed, which allows to assure authenticity and integrity of the LOTL. The signing certificates of the LOTL are also made publicly available in the OJEU. The LOTL is used to authenticate EU MS Trusted Lists and to provide an easy and trustworthy way to access these TLs. When the LOTL-signing certificates or the location of the LOTL changes, the modification needs to be published by the Commission. The update is done in the form of a “pivot LOTL”, which is a specific instance of a LOTL. Each new modification will create a new pivot LOTL. The pivot LOTLs are grouped in the current LOTL itself, under the < SchemeInformationURI> field. Consulting all the pivot LOTL from the most recent to the oldest gives a trace of all the signing certificates and locations of the LOTL back to the initial ones. 3.3.5. Certificate Chain and Certification Path ValidationThe certificate path validation is an algorithm that seeks to verify the binding between the public key and the subject of a certificate, using trust anchor information. The complete processing is described in RFC 5280 section 6.1, and as stated there, it verifies among other things that a prospective certification path (a sequence of n certificates) satisfies the following conditions:
Although RFC 5280 states that procedures performed to obtain the sequence of certificate that is provided to the certification path validation is outside its scope, Common PKI v2.0 part 5 section 2.1 ([R23]) provides one such possible procedure. An intuitive approach to build a prospective certification path is to start by looking at the “Authority Information Access” (AIA) extension of the target certificate (see RFC 5280 section 4.2.2.1) which, if present, frequently includes information on how to retrieve the certificate of the issuer of that certificate. Repeating this action on the certificate retrieved can then allow to build a prospective certification path. The wording "certificate chain" is often used interchangeably with "certification path". In ETSI EN 319 102-1 ([R09]) however, a prospective certificate chain is defined as a sequence of certificate that satisfies the conditions a. to c. above and for which the trust anchor is trusted according the validation policy in use. An illustration of different certificate chains/certification paths is provided in the figure below. 3.3.6. Signature creation3.3.6.1. Signature creation processAlthough other schemes exist, we assume here that creating a digital signature value consists in the encryption of a hash computed on the signed data. The standard ETSI EN 319 102-1 clause 4 ([R09]) provides a complete conceptual model for the creation of “AdES digital signatures”, but for the sake of simplicity we can extract from this model the following steps:
As mentioned above, the activation of the private key and the operation of creating the signature value is assumed to be performed by a specific device. It is in general desirable that this device is a secure (e.g. tamper-proof) device that requires authentication for the activation of the key (e.g. using PIN codes). When the private key contained in that device is controlled by an end-entity, this device is usually called a “signature creation device” or SCDev. This can be a local SCDev such as a smartcard, but it can also be a remote SCDev managed by a CA or TSP. When the private key is used by a CA for signing certificates, this device is usually called a “hardware security module” or HSM. Frequently, when the private key is under the control of a legal entity (such as when the key is used to create electronic seals) the device is also called an HSM. 3.3.7. Signature validation (introduction)Taking a very (or over) simplified model, validating a digital signature can be seen as:
We’ll see that even such a simplified model is useful for the purpose of introducing common concepts in digital signature validation. Let’s imagine that we want to validate a digital signature and the time when this validation occur is denoted as Tval. If the signing certificate successfully passes the certification path validation at Tval, and the digital signature value is cryptographically valid, one can then say that the digital signature is valid at Tval. Now, if computing the hash of the signed data does not yield the same value as the decryption of the signature value, one can then say that the digital signature is invalid. Beyond valid and invalid digital signature however, there are a lot of cases when one cannot determine the validity of a digital signature. Below are some examples where one cannot conclude that a digital signature is valid or invalid, in which case the validity status of the signature is indeterminate. Let’s imagine that at Tval, when we are trying to access the certification status information, that information is unavailable (e.g. the CRL cannot be downloaded, the OCSP responder is unavailable). Then it is not possible, at Tval, to determine whether the signing certificate is valid or not because at that time we are lacking information to conclude on that validity status. Because the validity of the signing certificate cannot be determined, the validity of the overall signature cannot be determined either and the validity of the signature is indeterminate. However, this status is only indeterminate because we do not have the information that would allow us to conclude, retrying to validate the signature with more information (e.g. at a time when the CRLs can be downloaded) could result in a definite valid or invalid status. A more complex example is when, at Tval, revocation information indicates that the signing certificate is revoked since a time indicated as Trev (which is thus < Tval). Then at Tval, we can only conclude that the signing certificate is revoked and thus the signature cannot be determined as valid at Tval. However, this does not mean necessarily that the signature was created when the signing certificate was revoked, it may very well be that the signature was created at a time prior to Trev and that, should we have validated the signature at that time, the validation would have been successful. Therefore, we cannot conclude that the signature is invalid because we do not know in a definite manner if the signature was created before the revocation of the signing certificate. For instance, if we had a proof that the signature existed before Trev, such as a signature timestamp indicating a time Tpoe < Trev, then using that proof of existence (POE) we can conclude that the signature was created before the signing certificate was revoked and this could allow us to produce a definite conclusion. On the other hand, if we had a proof that the signature could not have existed before Trev, such as a content timestamp indicating a time Tcnt > Trev (a content timestamp is necessarily created before the digital signature value), then we could definitely conclude that the signing certificate was revoked when the digital signature was created and thus that the digital signature is invalid. Another issue that can be illustrated here is when one creates a digital signature using cryptographic algorithms that are not considered secure: In such a case, it may be possible for an malicious actor to create counterfeited signed documents. When validating a signature, it is therefore necessary to verify that the signature was created using cryptographic algorithms and parameters that are considered as secure. This is usually done by comparing a POE of the digital signature value with a sunset date for the cryptographic algorithms and parameters involved. A sunset date for a cryptographic algorithm and/or parameter is called a cryptographic constraint, and the application validating the signature usually keeps a set of such dates and cryptographic algorithms and parameters; this set is what is called the set of cryptographic constraints. In general, the validation of a signature is made against a set of constraints, which the cryptographic constraints are a part of, that is also sometimes referred to as a signature validation policy. The standard ETSI EN 319 102-1 specifies a complete validation model and procedures for the validation of “AdES digital signatures”, which are implemented in DSS. The result of a validation process performed according to those procedures is a validation report and an indication which can be:
For each of the validation checks/constraint (e.g. signature format, signing certificate validity), the validation process must provide information justifying the reasons for the resulting status indication as a result of the check against the applicable constraints. In addition, the ETSI standard defines a consistent and accurate way for justifying statuses under a set of sub-indications. This allows the user to determine whether the signature validation has succeeded and the reason in case of a failure. The following table presents the indications and sub-indications that can be encountered at completion of a signature validation process. For a detailed description of their meaning, refer to ETSI EN 319 102-1 ([R09]). Table 3. Signature validation indications and sub-indications
3.3.8. TimestampingAs illustrated in Signature validation (introduction), validating a signature sometimes require a proof of existence of that signature at a given time. Such proof of existence can be given in the form of a timestamp. A digital timestamp is an assertion of proof that a data object existed at particular time. This usually takes the form of a binding between a hash of a data object and a date and time issued and signed by a trustworthy timestamping authority. When signing digitally, a date and time can be already included into the signature, but it corresponds to the signer computer’s local time. The latter can easily be modified prior to signing so that the time of signing is not the actual one. Thus, this signing time cannot be trusted. A trustworthy digital timestamp shall be used to prove existence of the signature (and its associated data) at a certain point in time. This principle exists for handwritten signatures too. When a document is signed manually, it is done in the presence of a trustworthy notary, who verifies not only the identity of the signer but also the date and time of the signature. Before explaining the timestamping process, let us define some concepts that are involved in this process
Furthermore, in the context of digital signatures, we usually distinguish timestamps depending on the data for which they provide a proof of existence:
Timestamping, the process of adding a timestamp to a signature, can be broken down into the following steps:
An illustration of that process for the creation of a signature timestamp is provided below: The timestamp token created by a TSA can be considered as trustworthy because
3.3.9. Multiple signaturesUp until now, only creation of a single signature have been covered. However, in most cases multiple signatures need to be created (e.g. a contract signing by multiple parties). In such cases, it is useful to note that multiple signatures can be created in parallel or in a sequential order. 3.3.9.1. Parallel signaturesParallel signatures are stand-alone, mutually independent signatures where the ordering of the signatures is not important. All the involved parties can receive the data at the same time and sign in any order. The computation of these signatures is performed on exactly the same hash data but using different private keys associated to the different signers. Parallel signatures can be validated independently to verify whether the associated data is validly signed. The following schema illustrates the creation of parallel signatures: 3.3.9.2. Sequential signaturesSequential signatures are mutually dependent signatures where the ordering of the signatures is important. A fixed signing order is defined and the next signer in the chain shall not sign before the preceding signers have signed the data. The computation of these signatures is not performed on the same data. A signer that is further in the signing chain will sign the initial data previously signed by the signers preceding him in the chain. Each signer uses his own private key to sign. The following schema illustrates the creation of sequential signatures: 3.3.9.3. Counter signaturesA counter signature is an additional signature applied on data that has already been signed previously. This type of signature is used to show approval of the data and signature, to confirm the authenticity of the data. The computation of a counter signature is performed on the signed data, and it is added to the signature as an unsigned attribute, i.e. after initial signature creation. Counter signatures are often created by trustworthy entities such as notaries, doctors or attorneys. Possible use cases are rental and mortgage applications, health documents, passports and visas. The following schema illustrates the creation of counter signatures: 3.3.10. Signature Applicability Rules / Signature PolicyThe term "signature policy" is often used to refer to "Signature Applicability Rules", that is, a set of rules for the creation, validation and long-term management of one (or more) electronic signature(s). A Signature Policy, in that meaning, contains general information such as:
A Signature Policy is composed of three main parts that define technical and procedural requirements:
A signature policy is a way of expressing:
The exact information contained in a signature policy will depend on the use cases of the signature and on the involved parties as the signature policy can be negotiated between them. Therefore, it is not possible to define a single template policy to cover all use cases. Having a signature policy and thus all the above-mentioned information, available in a signature, has several advantages:
Parties involved in a signature policy are:
ETSI ESI has developped several standards to express signature applicability rules or "signature policy" in two forms:
3.3.10.1. Signature policy at creation and validationDuring signature creation, a signature creation policy can be added to the signature as a signed attributes of the signature. Signed attributes are information that can only be included upon signature creation and that cannot be added, modified or removed at a later point in the life of the signature. The signature creation policy can be added to the signature indirectly as a reference which is composed of the hash value of the policy and the hash algorithm that was used to hash the policy, or directly when it is in a machine processable form. During signature validation, a mapping between acceptable signature creation policies and their corresponding signature validation policies can be provided to the signature validation application (SVA). If the signature contains one signature creation policy identifier, which is part of the list of mappings, the SVA can then apply the corresponding validation policy during validation. 3.4. ResourcesCertain resources have been developed to improve the adoption of the eIDAS Regulation as well as improve information sharing about the eIDAS Regulation and related concepts. The EU Trust Services Dashboard (EU TSD) is such a resource. It "proposes a centralized platform that enables interested parties and Digital Single Market players to easily and transparently access information and tools related to the trust services chapter of eIDAS". It contains among others a Trusted List Browser to browse through the trusted lists of the different EU Member States.
ETSI has developed standards that can be followed to be compliant with the eIDAS Regulation. 3.5. Digital signatures in DSS3.5.1. Tokens in DSSThe Token class is the base class for the different types of tokens used in the process of signature validation which are certificates, OCSPs, CRLs and timestamps. These tokens can be described as follows:
3.5.2. Compliance to ETSI standardsDSS implements the following ETSI standards for various signature forms:
but also claims:
3.5.3. Out of the EU contextDSS is not limited to EU contexts. It can be used in non-EU contexts with all its basic functions, i.e. signing, augmentation, validation, etc. An example would be the configuration of trust anchors (see section Trust anchor configuration from a certificate store). The certificate sources can be configured from a TrustStore (kind of keystore which only contains certificates), a trusted list and/or a list of trusted lists. In case of an EU context you could use any of these three trust anchors. For a non-EU context you could use a trust store or a non-EU trusted list. However, non-EU TLs are supported by DSS only if they have the same XML structure as EU TLs, i.e. if they are compliant with the XSD schema. Another constraint is that there is no guarantee for a proper qualification determination as the non-EU TL shall also be compliant with EU regulations. 4. Signature creation4.1. AdES specificities4.1.1. Existing formatsThe different digital signature formats make it possible to cover a wide range of real life use cases of this technique. Thus, we distinguish the following formats:
4.1.2. Signature profilesThe eIDAS Regulation (910/2014) sets the legal framework for electronic signatures in the European Union. It defines who can use electronic signatures and in what context. To ensure that electronic signatures can be created and validated anywhere in Europe, a number of standards were identified for their implementation. To ensure cross-border interoperability the eIDAS Regulation through the Commission Implementing Decision (EU) 2015/1506 (cf. [R16]) specifies minimum formats of advanced electronic signatures and advanced seals to be recognised by member states. It defines a number of baseline profiles:
The baseline profile for a certain signature format provides the basic features required to assure interoperability in the EU for that format. Each baseline profile defines four different levels that correspond to the four signature classes described in the ETSI standard EN 319 102-1 (cf. [R09]) and which are described in the following section. Before the introduction of the baseline profiles, old extended profiles were used. Below is a comparative table of old extended profiles and new baseline profiles for each signature format: Table 4. Signature supported profiles
The DSS framework is compatible with the baseline profiles. However, it is not possible to use the extended profiles for signing purpose except for XAdES-E-A/C/X/XL. The validation of the signature has a basic support of old profiles. 4.1.3. Signature classes/levelsThe ETSI standard EN 319 102-1 (cf. [R09]) defines four conformance classes to address the need to protect the validity of the signature in time. Henceforth, to denote the class of the signature the word "level" will be used. Follows the list of profiles implementing the four classes defined in the standard:
The following schema from the ETSI standard EN 319 102-1 (cf. [R09]) illustrates the different classes. 4.1.4. Signature packagingWhen signing data, the resulting signature needs to be linked with the data to which it applies. This can be done either by creating a data set which combines the signature and the data (e.g. by enveloping the data with the signature or including a signature element in the data set) or placing the signature in a separate resource and having some external means for associating the signature with the data. The choice is not obvious, because in one case the signature will alter the signed document and in the other case it is possible to lose the association between the signed document and its signature. The following types of packaging can be defined for various signature formats:
More information about packaging use in combination with available formats can be found in the Signature profile guide. 4.1.4.1. Signature profile guideBelow you can find a table specifying various signature possibilities with available in DSS signature’s profiles/formats. The vertical column specifies available signature profiles and their extensions. The horizontal row specifies types of documents to be signed with the formats. Table 5. File formats and Signature types conformance
4.1.5. Signature algorithmsDSS supports several signature algorithms (combination of an encryption algorithm and a digest algorithm). Below, you can find the supported combinations. The support of the algorithms depends on the registered OID (ASN1) or URI (XML). In the next table, XAdES also applies to ASiC with embedded XAdES signatures and CAdES also concerns PAdES and ASiC with embedded CAdES signatures.
4.2. Representation of documents in DSSDSS allows creation of different kinds of DSSDocument :
InMemoryDocument
FileDocument
DigestDocument
CMSDocument
HTTPHeader and HTTPHeaderDigest
ContainerEntryDocument
4.3. Signature tokensThe DSS framework is able to create signatures using different keystores: PKCS#11, PKCS#12, JKS, MS CAPI and Apple Keystore. To be independent of the signing media, the DSS framework uses an
interface named This design also allows other card providers/adopters to create their own implementations. For example, this can be used for a direct connection to the Smartcard through Java PC/SC. 4.3.1. PKCS#11PKCS#11 is widely used to access smart cards and HSMs. Most commercial software uses PKCS#11 to access the signature key of the CA or to enrol user certificates. In the DSS framework, this standard is encapsulated in the class Pkcs11SignatureToken usage
4.3.2. PKCS#12This standard defines a file format commonly used to store the private key and corresponding public key certificate protecting them with a password. It allows signing with a PKCS#12 keystore (.p12 file). In order to use this format with the DSS framework you
have to go through the class Pkcs12SignatureToken usage
4.3.3. MS CAPIIf the middleware for communicating with an SCDev provides a CSP based on MS CAPI (the Microsoft interface to communicate with SmartCards) specification, then you can use the MSCAPISignatureToken usage
4.3.4. Apple KeystoreSince DSS 5.10 a new class
AppleSignatureToken usage
4.3.5. Java Key StoreThe JKSSignatureToken usage
4.3.6. Other Implementations
As you can see, it is easy to add another implementation of the 4.4. Signature creation in DSSIn the DSS framework, there are two alternatives for signing a document which are illustrated in the following schema. The first path consists in 3 atomic steps:
The alternative is to use the following 4 steps:
4.4.1. Signature creation in 3 stateless methodsUsually, the signature creation is done using the 3 stateless methods approach. DSS fully manages the first and last steps of the document signature process. The
signature operation (signing the DTBS) needs to be specified. DSS offers some implementations in the The following code presents the three stateless steps. Three stateless steps
The first step uses the
This step returns the DTBS. In the case of a XAdES, it corresponds to the SignedInfo XMLDSig element. Usually the DTBS is composed of the digest of the original document and the signed attributes (i.e. XAdES or CAdES). The second step is a call to the function
The third and last step of this process is the integration of the signature value in the signature and linking of that one to the signed document based on the selected packaging method. This is done using the method
This separation into three steps allows use cases where different environments have their precise responsibilities: specifically the distinction between communicating with the token and executing the business logic. 4.4.2. Signature creation in 4 stateless methodsThe main difference in this approach is that the digest of DTBS (i.e. DTBSR) is computed separately from a SignatureValue creation. The following code presents the alternative with four stateless steps. Four stateless steps
The first and last steps, which compute the DTBS and sign the document, are the same as for the alternative with three steps. The second step uses the
It returns the data to be signed representation (DTBSR) of a DTBS, i.e. it computes the digest. The step that signs the digest with a raw signature (eg: NONEwithECDSA) and returns the signature value uses the method
4.5. Creating a Baseline B-level signatureThe simplest way to address the digital signature passes through the XAdES format. Indeed, it allows visualization of the signature content with a simple text editor. Thus, it becomes much easier to make the connection between theoretical concepts and their implementation. Before embarking on the use of the DSS framework, it is advisable to read the following documents:
The referenced specifications define the following:
To start, let’s take a simple XML document: xml_example.xml
To instantiate a document from a file in DSS, refer to the section about DSSDocuments. Since this is an XML document, we will use the XAdES signature and more particularly the XAdES-BASELINE-B level. For our example, we will use the ENVELOPED packaging. To write our Java code, we still need to specify the type of KeyStore to use for signing our document. In other words, we need to specify where the private key can be found. To know more about the use of the different signature tokens, please consult the Signature tokens section. In this example the class This is the complete code example that allows you to sign an XML document: Create a XAdES-BASELINE-B signature
To summarize, signing a document in DSS requires to:
The encryption algorithm is determined by the private key and therefore shall not be compelled by the setter of the signature parameters object. It would cause an inconsistency in the signature making its validation impossible. This setter can be used in a particular context where the signing process is distributed on different machines and the private key is known only to the signature value creation process. Setting the signing certificate and the certificate chain should always be done. They can be set even if the private key is only known to the signature value creation process and there is no access to the private key at DTBS preparation. However, of course, the signing certificate shall be associated to the private key that will be used at the signature value creation step. Integrating the certificate chain in the signature simplifies the build of a prospective certificate chain during the validation process. When the specific service is instantiated a certificate verifier must be set. It is recommended to read section CertificateVerifier configuration for information on the configuration of a The code above produces the signature that can be found here. 4.6. Configuration of attributes in DSS4.6.1. Signed and unsigned attributesA signature is composed of signed and unsigned attributes. Signed attributes shall be included in a signature. These are BASELINE-B attributes that are set upon signature creation. They cannot be changed after the signature has been created. Unsigned attributes are not obligatory and can be added after the signature creation during signature augmentation. 4.6.1.1. Table with all attributes per format and classTable 7. File formats and Signature types conformance
4.6.2. Signed attributesAdditional signed attributes can be added to the basic signature configuration as presented in the following example of a XAdES-BASELINE-B signature. XAdES signature with additional signed attributes
In the XAdES format the following types of Content Timestamp can be used:
By default, the AllDataObjectsTimeStamp is used. The IndividualDataObjectsTimeStamp can be configured manually.
Concerning the signing date, the framework uses the current date time by default. In the case where it is necessary to indicate a different time it is possible to use the setter
The code above produces the signature that can be found here. 4.6.2.1. Signature PolicyThe signature policy is a BASELINE-B signed attribute that is set upon signature creation. Thus, this attribute cannot be changed after the signature has been created. The DSS framework allows you to reference a signature policy, which is a set of rules for the creation and validation of an electronic signature. For more information on the signature policy refer to section Signature Applicability Rules / Signature Policy. The signer may reference the policy either implicitly or explicitly.
This example demonstrates an implicit policy identifier. To implement this alternative, you must set XAdES with implicit policy
The following XML segment will be added to the signature’s qualifying and signed properties (<QualifyingProperties><SignedProperties>):
The next example demonstrates the use of an explicit policy identifier. This is obtained by setting the BASELINE-B profile signature policy and assigning values to the policy parameters. The Signature Policy Identifier is a URI or OID that uniquely identifies the version of the policy document. The signature will contain the identifier of the hash algorithm and the hash value of the policy document. The DSS framework does not automatically calculate the hash value; it is up to the developer to proceed with the computation. It is important to keep the policy file intact in order to keep the hash constant. It would be wise to make the policy file read-only. XAdES with explicit policy
The following XML segment will be added to the signature qualifying and signed properties (<QualifyingProperties><SignedProperties>): XAdES Signature Policy element
4.6.2.2. Signature Policy StoreDSS provides a possibility of incorporation of a Signature Policy Store element as an unsigned property to the existing signature file. The following signature formats support the Signature Policy Store addition:
Before incorporating of a Signature Policy Store, you need to ensure the target signature contains the matching Signature Policy Identifier element (see section Signature Policy). An example of a Signature Policy Store creation is available below: Add SignaturePolicyStore
4.6.3. Trust Anchor Inclusion PolicyIn DSS, it is possible to indicate whether to include or not the certificate related to the trust anchor in the signature. Refer to section Trust Anchors and Trust Stores for information on trust anchors. By default, when a It is possible to indicate to the framework that the certificate
related to the trust anchor should be included to the signature even at the By default, the argument Use of Trust Anchor Inclusion Policy parameter
4.6.4. Other parameters4.6.4.1. XAdES4.6.4.1.1. Canonicalization parameters Before computing digests on an XML element, a canonicalization should be performed. DSS allows defining canonicalization algorithms to be used on signature or timestamp creation: Use of canonicalization algorithm parameters
4.6.4.1.2. References In order to compute digest for original document(s) in a custom way, a class DSSReference definition
For more information about 4.6.4.2. PAdESThe framework allows creation of PDF files with visible signature as specified in ETSI EN 319 142 (cf. [R03]) and allows the insertion of a visible signature to an existing field. For more information on the possible parameters see section PAdES Visible Signature. 4.7. Multiple signatures4.7.1. Parallel signaturesParallel signatures, described in section Parallel signatures, can be created in DSS according to the corresponding AdES formats. Parallel signatures creation
4.7.2. Sequential signaturesDSS allows creation of sequential signatures according to the PAdES formats (cf. Sequential signatures). Sequential signatures creation
4.8. Counter signaturesDSS allows creation of counter signatures in accordance with corresponding AdES formats (cf. Counter signatures).
The following formats are supported for the counter signature creation:
In order to create a counter signature, the DSS Identifier (or XML Id for XAdES) of the target signature you want to sign shall be provided within the parameters. The example below presents a counter signature creation: Counter signature creation
DSS is able to retrieve the original data from a valid signature. Retrieve the original data from a signed document
5. Specificities of signature creation in different signature formats5.1. XAdES (XML)5.1.1. Versions supportDSS supports the following XAdES formats : Table 8. Supported XAdES versions
The XAdES Profile, as well as a customizable prefixes can be set with following methods : XAdES formats and prefixes
5.1.2. Reference TransformationsIn case of 'Enveloping', 'Enveloped' and 'Internally Detached' signatures, it is possible to apply custom transformations for signing references in order to compute a proper digest result. You can find an example of definition reference transformations below: Custom transformations definition
Current version of DSS supports the following transformations:
5.1.3. Specific schema versionSome signatures may have been created with an older version of the XAdES format using different schema definition. To take into account the validation of such signatures the
By default, all XAdES are supported and DSS loads/parses all versions of XAdES. It is possible to restrict to only one version of XAdES with the following code : Customize the supported XAdES version(s) at the validation
5.2. CAdES signature (CMS)To familiarize yourself with this type of signature it is advisable to read the following document:
To implement this form of signature you can use the XAdES examples. You only need to instantiate the CAdES object service and change the SignatureLevel parameter value. For an extensive example see section CAdES of the Annex. 5.3. PAdES signature (PDF)The standard ISO 32000-1 (cf. [R06]) allows defining a file format for portable electronic documents (PDF). The standard defines the PDF version 1.7 of Adobe Systems. Concerning the advanced electronic signature, the PAdES standard is used (cf. [R03]). The DSS implementation supports main operations for PAdES signatures:
To familiarize yourself with this type of signature it is advisable to read the documents referenced above. An example of code to perform a 5.3.1. PAdES Visible SignatureThe framework also allows creation of PDF files with visible signatures as specified in ETSI EN 319 142 (cf. [R03]). In the Additionally, DSS also allows you to insert a visible signature to an existing field. This is illustrated in section PAdES Visible Signature of the Annex. In case of placing an image or text to an existing field, the visible signature will fill out the whole available area of the field. 5.3.1.1. Visible signature parameters (image and text)This chapter introduces existing parameters for creation of visible signatures with DSS. DSS has three implementations for visible signature drawing:
5.3.1.1.1. Positioning DSS provides a set of functions allowing to place the signature field on a specific place in the PDF page. For an illustrative example see section Positioning in the Annex. 5.3.1.1.2. Dimensions DSS framework provides a set of functions to manage the signature field size. See section Dimensions in the Annex for a concrete example. 5.3.1.1.3. Text Parameters The available implementation allows placing of a visible text in a signature field. See section Text Parameters in the Annex for a concrete example. 5.3.1.1.4. Text and image combination DSS provides a set of functions to align a text with respect to an image. The parameters must be applied to a 'SignatureImageTextParameters' object. See section Text and image combination in the Annex for a concrete example. 5.3.1.2. Fonts usageTo customize a text representation a custom font can be defined. The font must be added as an instance of the DSS provides the following common implementations for the
Additionally, there are implementation-dependent classes:
You can find an example of how to create a custom font for a physical font, for a logical font and for a native font in section Fonts usage. By default, DSS uses a Google font : 'PT Serif Regular' (its physical implementation).
5.4. ISO 32000-1 PDF signature (PKCS#7)The ISO 32000-1 standard gives a specification for the creation of electronic signatures in the PDF format. However, these signatures are not in the AdES format defined by ETSI. The Public Key Cryptographic Standard Number 7 (PKCS#7) is a common format of a signature included in a PDF which has been created by Adobe PDF Reader. The PKCS#7 signature format is described in the ISO 32000-1 standard (cf. [R06]) and must conform to the RFC 2315 (cf. [R15]). To familiarize yourself with this type of signature you can read these documents. DSS only supports AdES formats (e.g. PAdES for PDF) and thus does not support signature creation for PKCS#7. DSS only provides a limited support for the augmentation and validation of PKCS#7 signatures. There is no specific validation standard for PKCS#7 nor any augmentation formats in the ISO 32000-1 standard. Thus, DSS validates and augments PKCS#7 according to rules defined in ETSI standards. It validates PKCS#7 signatures according to the AdES validation algorithm, and it adds the same components as when augmenting PADES-BASELINE-B to PAdES-BASELINE-T. 5.5. JAdES signature (JWS)DSS includes a possibility of creation and validation of JSON Advanced signatures (JAdES). The JSON format for AdES Signatures (cf. [R05]) represents an extension of JSON Web Signatures (JWS) as specified in IETF RFC 7515. A typical example of a JAdES signature creation can be found in section JAdES of the Annex. The specific parameters for JAdES signature are described in the next sections. 5.5.1. JWS Serialization typeA JWS signature can be represented in different forms which are supported by the JAdES standard as well:
JWS Serialization type usage
JAdES signatures allow two types of JWS Payload (signed data) inclusion: 5.5.2.1. Enveloping packagingWith 5.5.2.2. Detached packagingA simple JWS signature allows a To create such a signature, the parameter The JAdES standard [R05] provides a possibility for signing multiple documents within one signature in a detached way. The following mechanisms are possible:
Configuration for signing with detached mechanism HttpHeaders
Configuration for signing with detached mechanism ObjectIdByURIHash
5.5.3. Base64Url encodingThe
JAdES signatures (as well as JWS) force some values to be Base64Url-encoded, while providing a possibility to customize the format for some of them. DSS provides options to configure encoding for the following elements:
Use unencoded JWS Payload
Represent EtsiU components as clear JSON instances
5.6. ASiC signature (containers)The ETSI EN 319 162 standard (cf. [R04]) offers a standardized use of container forms to establish a common way for associating data objects with advanced signatures or time-stamp tokens. It is an alternative to the packaging types presented in section Signature packaging. A number of application environments use ZIP-based container formats to package sets of files together with meta-information. ASiC technical specification is designed to operate with a range of such ZIP-based application environments. Rather than enforcing a single packaging structure, ASiC describes how these package formats can be used to associate advanced electronic signatures with any data objects. The standard defines two types of containers:
DSS framework has some restrictions on the containers you can generate, depending on the input file. If the input file is already an ASiC container, the output container must be the same type of container based on the same type of signature. If the input is any other file, the output does not have any restriction. Table 9. ASiC containers
Typical examples of the source code for signing a document using You need to pass only few
parameters to the service. Other parameters, although they are positioned, will be overwritten by the internal implementation of the service. Therefore, the obtained signature is always based on the It is also possible with the DSS framework to make an augmentation of an ASiC container to the levels 6. Revocation data managementRevocation data management is an essential part in the lifecycle of a digital certificate and thus of a digital signature too. 6.1. Tokens and sourcesDSS provides utilities for processing and validation of both CRL and OCSP tokens, containing a revocation information about a certificate (see CRLs and OCSP 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 The interface CRLSource usage
The interface OCSPSource usage
We use these classes during the certificate validation process through In general, we can distinguish three main sources:
As well as a list of sources ( 6.2. CachingThe
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. List of cached Revocation sources implemented in DSS:
6.2.1. CRLAn example for JdbcCacheCRLSource : JdbcCacheCRLSource usage
6.2.2. OCSPAn example for JdbcCacheOCSPSource : JdbcCacheOCSPSource usage
6.3. Online fetchingDSS provides utilities for online fetching of revocation data from remote sources, during the signature augmentation and validation processes.
6.3.1. CRLThis 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
6.3.2. OCSPThis 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
6.4. Other implementations of CRL and OCSP SourcesOther 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:
6.5. Revocation data loading strategySince version 5.9, DSS allows the use of a
See section CertificateVerifier configuration for an example of how to customize a used Using an OCSP first (i.e.
6.5.1. Revocation fallbackSince 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:
To configure the revocation fallback behavior, the property should be configured within 6.6. Revocation data verifierSince version 5.11, DSS provides a way to configure a revocation data checking algorithm within
An example of RevocationDataVerifier usage
7. Signature Validation7.1. Validation of a certificateThe signature validation starts from a validation of a certificate chain (cf. Certificate Chain and Certification Path Validation). 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. Validate a certificate and retrieve its qualification level
7.1.1. Trust anchor configuration from a certificate storeTrust anchors are an essential part of the validation process of a signature as described in section Trust Anchors and Trust Stores. 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. 7.1.1.1. Trust store initializationIf 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). Trust anchor initialization from a Trust Store
To generate the trust store, there’s an utility class CreateKeyStoreApp in
the 7.1.1.2. Trusted List Certificate SourceIn 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 Trusted List Certificate Source
7.1.1.3. Multiple Trusted Sources usageDSS provides a possibility to use multiple trusted certificate sources at one time. An example of the configuration is provided below: Multiple trusted certificate sources usage
7.1.2. Certificate chain in DSSThe 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:
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:
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:
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:
This is the superclass of almost of the certificate sources. It stores the extracted certificates and implements the common methods from the It also exposes the method
The
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.).
Certificates coming from the list of Trusted Lists. This class inherits of
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. 7.1.2.1. Retrieving certificates by AIAIn 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 Certificate Chain and Certification Path Validation). To use AIA URLs DSS provides the interface
An example of DefaultAIASource usage
7.1.3. Revocation data handling7.1.3.1. Revocation freshnessThe 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: 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 In case of a According to the ETSI TS 119 172-4 (cf. [R10]) standard, the RFC shall be set to 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
For example applying of
With the following policy, the 7.1.4. CertificateVerifier configurationThe
In the current implementation this object is only used when profiles
CertificateVerifier usage
7.2. AdES validation constraints/policyThe 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 Custom validation policy
7.2.1. XML policy structureThe validation policy allows defining different behavior for various token types or signature formats. The following groups are considered:
7.2.2. ConstraintsEach constraint defined in the policy forces an execution of a relevant check in the validation process.
The following constraint types are supported:
7.2.3. LevelThe
7.2.4. Multi Values ConstraintWhen using the
7.2.5. Cryptographic constraintsCryptographic constraints define a list of acceptable cryptographic algorithms and their expiration dates when needed. The following settings are possible:
7.2.6. The default XML policyThe default XML validation policy is present below. constraint.xml
7.3. Signature validation and reportsGenerally, a signature validation process outputs an indication status and a validation report as described in section Signature validation (introduction). In DSS, the result of the validation process consists of four elements:
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. 7.3.1. Validating an AdES signatureThe 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. Figure 1. Signature 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 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 Validation of a signature
7.3.1.1. SignedDocumentValidatorFor execution of the validation process, DSS uses the
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. SignedDocumentValidator usage
7.3.2. Simple reportThe 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. 7.3.3. Detailed reportThe 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:
For example the Basic Building Blocks are divided into seven elements:
The following additional elements also can be executed in case of validation in the past:
To process the revocation data, DSS performs the following additional checks:
Past certificate/signature validation is used when basic validation of a certificate/signature fails at the current time with an
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 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 Language of reports. 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 Interpreting a detailed report 7.3.4. Diagnostic dataDiagnostic 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.
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. 7.3.5. ETSI validation reportThe 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. 7.3.6. Stylesheets for validation reports and diagnostic dataThe 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 Report stylesheets 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. Diagnostic data stylesheets) 7.4. Various DSS validation options7.4.1. Validation levelWhile there exist four signature levels:
For configuration examples please see AdES validation section. 7.4.2. Signing CertificateDSS 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. Provide signing-certificate to the validation
7.4.3. Trusted CertificatesTo 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 Configuration of TL validation job for more information). Provide trusted certificate source to a CertificateVerifier
7.4.4. Adjunct CertificatesDSS 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. Provide adjunct certificate source to a CertificateVerifier
7.4.5. CertificatesIn DSS, it is possible to return the certificates, included in the signature, as output of the validation process. Extract certificate tokens
7.4.6. TimestampsDSS allows returning the timestamps, included in the signature, as output of the validation process. Extract timestamp tokens
7.4.7. Revocation dataIn DSS, it is possible to return the revocation data (CRLs and OCSPs), included in the signature, as output of the validation process. Extract revocation data tokens
7.4.8. User-friendly identifiersDSS 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. Configure token identifier provider
7.4.9. SemanticsWith DSS, it is possible to add a "Semantics" section at the end of the reports explaining the meaning of the result indications, i.e. Configure token identifier provider
7.5. DocumentValidator implementationsFor signature document or a signature policy validation, DSS is able to load a corresponding implementation of validator for the given document format at runtime using a DSS is able to choose the required implementation for the following interfaces:
For more information about 7.5.1. Document Validation FactoryThis factory
is used to create a required instance of a The following implementations are present in DSS:
7.5.2. Signature Policy ValidatorDuring 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 The signature policy document can be retrieved from the signature itself when a The interface
7.6. Format specificities7.6.1. PAdES7.6.1.1. Shadow attack detection"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:
The verification of points introduced above may be configured within an instance of PdfDifferencesFinder customization
7.6.1.2. Object modification detectionAs 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:
The following constraints are available to verify the validity of a signature based on encountered object modifications:
The search of the object differences may be configured within an instance of PdfObjectModificationsFinder customization
7.6.1.3. Password-protected documentsPDF 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 Sign password-protected document
To validate a password-protected PDF, a password string shall be provided within an instance of Validate password-protected document
8. Requesting a timestamp token in DSSTimestamping is essential when creating digital signatures that need to be preserved. Refer to section Timestamping for information about the general principles of the timestamping process. The following sections present how a timestamp token can be requested in DSS. 8.1. Configuring timestamp sourcesThe DSS framework proposes a The following snippet of Java code illustrates how you might use this class: OnlineTSPSource use
8.1.1. Timestamp policyA time-stamp policy is a "named set of rules that indicates the applicability of a time-stamp token to a particular community and/or class of application with common security requirements". A TSA may define its own policy which enhances the policy defined in RFC 3628. Such a policy shall incorporate or further constrain the requirements identified in RFC 3628. The user may request the TSA to issue a timestamp under a specific time-stamp policy that is supported by the TSA. Timestamp policy
8.1.2. Composite TSP sourcesSometimes timestamping servers may encounter interruptions (e.g. restart, configuration issues, etc.). To avoid failing signature augmentation, DSS allows a user to configure several TSP Sources. DSS will try one source after the other until getting a usable timestamp token. Configuration of a CompositeTSPSource
9. Standalone timestampingThe DSS framework allows an independent document timestamping (without a signature). These are standalone time assertions, i.e. that no augmentation to the level The following Document Signature Services support the standalone timestamping :
DSS also provides a validation service for timestamped documents. 9.1. Timestamping a PDFWhen timestamping a PDF document, a standalone timestamp can be used, creating a new revision. This algorithm ensures that no existing signature nor timestamp will not be broken, for example because of adding the timestamp to the existing CMS signature (as it can be done in CAdES or XAdES, for instance). The same timestamping procedure is used for timestamping a PDF document without embedded signatures. The code below illustrates a time-stamping process for a PDF document. PDF timestamping
9.2. Timestamping with a container (ASiC)Standalone time assertions can be used in both A typical example illustrating a time-stamping process that encapsulates the provided documents and the generated time-stamp to an ASiC-E container can be found below ASIC-E time assertion
In order to create an ASIC-S time assertion
9.3. Standalone timestamps repetitionIt is also worth noting that time assertions can cover each other, i.e. that a timestamp can be added over previously created timestamps. In this case, the validation data for a timestamp is incorporated within the previous (last) time assertion and the digest of that timestamp is added to the new created ArchiveManifest XML file, which is covered by a new timestamp. This is a procedure similar to the augmentation of ASiC with CAdES with multiple LTA levels. LTA timestamps are created in different time-assertion files instead of an archive-time-stamp attribute like it is the case in a CAdES signature. This concept is illustrated in the following schema using the ASiC format as an example 9.4. Standalone timestamp validationAs well as a single timestamp creation, DSS provides a validation service for timestamped documents. The timestamp validation process represents the one described in section "5.4 Time-stamp validation building block" of [R09]. The validation process is similar to the signature validation process. An appropriate validator will be selected automatically. In total, DSS supports timestamp-alone validation for the following file formats:
The validation process can be run with the following inputs: Timestamped document validation
You can find an example of a produced timestamp Detailed Report here. 10. Signature augmentationSignature augmentation is a process of adding material to go from one signature class to another. Signature augmentation is used for extending the validity of a signature in order to allow its long-term validation. 10.1. Configuration of the augmentation process10.1.1. What are the needed external resources10.1.1.1. TSATo augment a signature to levels 10.1.1.2. Revocation sourcesTo augment a signature to level 10.1.2. CertificateVerifier propertiesThe 10.2. Augmenting an AdES baseline B signatureThe The augmentation of the signature is incremental, i.e. when augmenting the signature to the The whole augmentation process is implemented by reusing components from signature creation. To augment a signature we proceed in the same way as in the case of a signature creation, except that you have to call the function "extendDocument" instead of the "sign" function.
10.2.1. To baseline T
The The framework adds the timestamp only if there is no timestamp yet or there is one but the creation of a new augmentation of the level Below is the source code that creates a Augment a XAdES signature
Here is the result of adding a new extension of type XAdES Unsigned Signature Properties
10.2.2. To baseline LTThe
In order to find a list of all the certificates and the list of all revocation data, an automatic process of signature validation is executed. To carry out this process an object called The code below shows how to use the default parameters with the SignXmlXadesLTTest.java
The following XML segment will be added to the signature qualified and unsigned properties (for XAdES): Validation data values
In the previous code example, the 10.2.3. To baseline LTA.The E.g. Below is an example of the implementation of this level of signature: Signature level setting
The following XML segment will be added to the signature qualified and unsigned properties (for XAdES): XAdES Archive Timestamp
The time-stamping process may be repeated every time the protection used becomes weak. A new time-stamp needs to be affixed before either the signing certificate of the TSA is expired or the algorithms used by the TSA of the previous time-stamp have become obsolete. The new timestamp and validation material are added into the existing This concept of 10.3. Creating a baseline T signatureThe common process is a
creation of a Let’s see an example of signing with the level Create a XAdES-BASELINE-T with an OnlineTSPSource
The XAdES Signature Timestamp
10.4. Best practices regarding baseline levelsFor signature creation, it is
recommended to use a It is not recommended using The
After the revocation data update, satisfying the revocation freshness constraint, the 11. Trusted Lists11.1. Configuration of TL validation jobThe 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. 11.1.1. TLSource and LOTLSourceSeveral TLSources and several LOTLSources can be injected in a Multiple TLSources and multiple LOTLSources configuration
11.1.1.1. Trusted List Source (TLSource)A TLSource configuration
11.1.1.2. List Of Trusted Lists Source (LOTLSource)A similar configuration is possible for Lists Of Trusted Lists (LOTL) with
a LOTLSource configuration
11.1.2. DSSFileLoaderThe
Offline and Online refresh configuration
11.1.3. The SynchronizationStrategyThe DSS provides two implementations within the framework:
The use of the strategies is demonstrated within the example below: Example of a custom SynchronizationStrategy
An example of a custom implementation of Example of a custom SynchronizationStrategy
11.1.4. The CacheCleanerThe CacheCleaner Configuration
11.1.5. Alerting from TL LoadingDSS 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). Examples of Alerting
11.1.6. LOTL/TL filter predicatesTSL 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:
Examples of TSL Loading Predicates configuration
11.1.7. Trust Service Provider predicatesDefined within 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:
Below you may find an example of Examples of Trust Service Provider Predicate configuration
It is also possible to create a custom Custom Trust Service Provider Predicate
11.1.8. TSP Service predicatesDefined within 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
Below you may find an example of Examples of Trust Service Predicate configuration
11.1.9. Executor ServiceAn 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. Executor Service
11.1.10. Complete configuration for the European LOTLBelow, you can find a complete configuration for the European List Of Trusted Lists. The URLs need to be externalized. European LOTL Configuration
11.1.11. The TL / LOTL refreshThe TL / LOTL loading in DSS works as below :
The refresh can be called with the offline or the online loader and run exactly the same code: How to refresh the Trusted List(s) and Lists of Trusted Lists
11.1.11.1. Java Keystore ManagementGenerally (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
The
Certificate import
The default password for a Java keystore is
After these steps the
11.1.12. TLValidationJobSummaryThe class How to retrieve the information about the TLValidationJob process
11.2. Validation policy for trusted listsAn eIDAS XML node linked to the status of the Trusted List is included in the DSS validation policy (see AdES validation constraints/policy for more information). The following elements are contained in that node:
11.3. Using non-EU trusted listsNon-EU trusted lists are supported by DSS. However, there are a few limitations:
11.3.1. Trust Service Equivalence MappingStarting 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:
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 Sign a Trusted List with the TrustedListSignatureParametersBuilder
11.4. Signing a trusted listThe
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 Sign a Trusted List with the TrustedListSignatureParametersBuilder
12. eIDAS12.1. Overview of certificates12.1.1. Qualified status of certificateThe qualification status determination is based on ETSI TS 119 615 standard (cf. [R14]), that requires extraction of information from a certificate (i.e. QcStatements, see [R24]) and from a Trusted List (under TSPService corresponding to the certificate). For more information about how to verify a certificate qualification status using DSS, please see the section Validation of a certificate. 12.1.2. Type of certificateA certificate can be for electronic signature, for electronic seal or for website authentication. A qualified certificate shall comply with the eIDAS regulation [R12], for each type:
The certificate type determination is based on ETSI TS 119 615 standard (cf. [R14]). The validation process takes into account the following factors but not limited to:
For more information about the validation process please see the ETSI TS 119 615 standard (cf. [R14]). 12.2. How certificate type and qualification are represented in DSS12.2.1. Certificate Qualification determinationIn order to determine a type and qualification of certificate, the An example of a qualification data extraction for a certificate, can be found below: Certificate qualification validation
12.2.2. Qualified certificate for WebSite Authentication (QWAC)With DSS, it is possible to validate a SSL certificate against the EUMS TL and the ETSI TS 119 615 (cf. [R14]) to determine if it is a Qualified certificate for WebSite Authentication (QWAC). DSS provides a special class Validate an SSL certificate and retrieve its qualification level
12.3. Overview of AdES signatures12.3.1. Type of AdESeIDAS Regulation (cf. [R12]) defines the following types of an electronic signature:
12.3.2. Qualified status of AdES signatureTo have a qualified status an electronic signature/seal shall satisfy the following requirements but not limited to:
12.4. How signature type and qualification are represented in DSS12.4.1. Signature Qualification determinationIn order to determine a type and qualification of a signature, an instance of An example of a qualification data extraction for a signature, can be found below: Signature qualification validation
12.5. Verifying the qualified status of timestampETSI TS 119 615 ([R14]) specifies standardized procedures for the determination of the qualification of a timestamp. DSS is able to determine a qualification level of a timestamp if a relative information about TrustServiceProviders is provided to a certificate verifier (loaded automatically to a trusted certificate source with Configuration of TL validation job). Three qualification levels are supported by DSS and can be obtained :
In order to determine a type and qualification of signature, an instance of
The following example verifies the qualification level of a timestamp: Validate a timestamp and retrieve its qualification level
13. WebservicesDSS offers REST and SOAP web services. The different webservices are :
The data structure in webservices is similar in both REST and SOAP modules. The documentation will cover the REST calls. All the REST services present in DSS are compliant with OpenAPI Specification. Additionally, we also provide a SOAP-UI
and Postman samples in the 13.1. REST13.1.1. REST signature serviceThis service is composed by two modules:
This service exposes several methods taking as input one or more document and having as output a signed data object (possibly a timestamped document): Rest signature service
13.1.1.1. Single document signingA document signing assumes a signature creation in three (or four) consecutive steps (see Signature creation in DSS for more information). Two of the steps, namely "get data to sign" and "sign document" are available within the current module. Below you can find examples for processing these steps when signing a single document. 13.1.1.1.1. Get data to sign The method allows retrieving the data to be signed. The user sends the document to be signed, the parameters (signature level, etc.) and the certificate chain.
Samples:
13.1.1.1.2. Sign document The method allows generation of the signed document with the received signature value.
Samples:
13.1.1.2. Multiple document signingSimilarly to Single document signing, the service exposes methods which allow signing of multiple documents with one signature (format dependent). 13.1.1.2.1. Get data to sign The method allows retrieving the data to be signed. The user sends the documents to be signed, the parameters (signature level, etc.) and the certificate chain.
Samples:
13.1.1.2.2. Sign document The method allows generation of the signed document with the received signature value.
Samples:
13.1.1.4. Timestamp documentThe method allows timestamping of a provided document. Available for PDF, ASiC-E and ASiC-S container formats. Samples:
13.1.1.5. Counter-signatureSimilarly to Single document signing, the counter-signature creation requires execution of three (or four) consecutive steps, with the difference requiring a signed document to be provided as an input and Id of the signature to be counter-signed. 13.1.1.5.1. Get data to be counter-signed This method returns the data to be signed in order to create a counter signature. The user should provide a document containing a signature to be counter-signed, id of the signature, and other parameters similarly to the method 'getDataToSign()'.
Samples:
13.1.1.5.2. Counter-Sign Signature This method incorporates a created counter signature to unsigned properties of the master signature with this specified id.
Samples:
13.1.1.6. Trusted List signingSpecial methods have been exposed (since DSS 5.10) allowing to sign a Trusted List (TL) or a List of Trusted Lists (LOTL) using a simplified interface with a pre-configured set of parameters. The key difference with
Single document signing methods is the use of the 13.1.1.6.1. Get data to sign The method allows retrieving the data to be signed. The user sends the Trusted List to be signed and the parameters (signing certificate, signing date, etc.).
Samples:
13.1.1.6.2. Sign document The method allows generation of the signed Trusted List with the received signature value.
Samples:
13.1.2. REST server signing serviceThis service also exposes some methods for server signing operations: Rest server signing service
13.1.2.1. Get keysThis method allows retrieving of all available keys on the server side (PKCS#11, PKCS#12, HSM, etc.). All keys will have an alias, a signing certificate and its chain. The alias will be used in following steps. Samples:
13.1.3. REST validation serviceDSS provides also a module for documents validation. Rest validation service
13.1.4. REST certificate validation serviceThe certificate validation service is used for validation of a certificate with the respective certificate chain. Rest certificate validation service
13.1.5. REST timestamp serviceThis service implements a timestamp creation. Rest timestamp service
13.1.5.1. Get Timestamp ResponseThis service allows a remote timestamp creation. The method takes as an input the digest to be timestamped and digest algorithm that has been used for the digest value computation. The output of the method is the generated timestamp’s binaries. Samples:
13.2. SOAPThe use of SOAP webServices is very similar to the REST implementation explained above. The main difference is the used implementation of the service. All methods, used parameters and output objects are aligned between both REST and SOAP implementations. 13.2.1. SOAP signature serviceSOAP signature service’s client is initialized using Soap signature service
13.2.2. SOAP server signing serviceSOAP server signing service’s client is initialized using Soap server signing service
13.2.3. SOAP validation serviceSOAP validation service’s client is initialized using Soap validation service
13.2.4. SOAP certificate validation serviceSOAP validation service’s client is initialized using Soap certificate validation service
13.2.5. SOAP timestamp serviceSOAP validation service’s client is initialized using Soap timestamp service
14. Internationalization (i18n)14.1. Language of reportsDSS provides a module allowing changing a language for generated reports.
A target language of the report can be set with the following code: Language customization
In case if no language is specified, the framework will use a default As a default configuration DSS provides English translation. In order to provide a custom translation, a new file must be created inside
For example, for a French language a file with a name 15. ExceptionsThis section provides an overview of runtime Exceptions which are being thrown by various modules of DSS framework. The following Exceptions can be obtained by the upper level:
16. Privacy16.1. Use of digested documentsDigested documents can be used during signature creation instead of the original documents to keep the latter private. In that case, the signature is created in a detached way, using the digest of the original document only. 16.2. Original document in the Data To Be SignedThe data to be signed (DTBS) for CAdES, XAdES and PAdES does not contain the original document on which the signature value is computed. JAdES DTBS however, when not the DTBS of a detached JAdES signature making use of the ObjectIdByURIHash referencing mechanism, does contain the whole original content. 16.3. Private information in logsFive log levels are used in DSS:
When setting a log execution level to Since the logs are hardcoded it is not possible to modify the behavior. Therefore, to avoid disclosing private information, users should not use the For example, when an error occurs on a certificate reading, DSS only Sometimes, DSS uses mixing rules for logging, such as it displays more information within a 16.4. Client-side signature creation with server-side remote key activationWith DSS, it is possible to sign a document without needing to send it to the signing server. This is useful for users who do not want signing servers to have access to the information contained in their documents. Such a process is possible because DSS decomposes the signature of a document in three or four atomic steps. See section Signature creation in 3 stateless methods and Signature creation in 4 stateless methods for an extensive description of these steps.
The following schema illustrates the different steps 17. Advanced DSS java concepts17.1. ServiceLoaderDSS incorporates modules that are loaded in the run time based on the chosen configuration and the input data via a ServiceLoader. This provides a flexibility for an end-user to work only with selected modules and a possibility to expand DSS with custom implementations. In order to provide a chosen implementation(s) to It is also possible to customize the order of the used implementation, but creating a corresponding file in
The following modules are provided with independent implementations:
17.1.1. DSS UtilsThe module
If your integration includes pom.xml
17.1.2. DSS CRL ParserDSS contains two ways to parse/validate a CRL and to retrieve revocation data. An alternative to the
If your integration requires pom.xml
17.1.3. DSS PAdESDSS
allows generation, augmentation and validation of PAdES signatures with two different frameworks: PDFBox and OpenPDF (fork of iText). The
DSS permits to override the visible signature generation with these interfaces:
A new instance of the 17.1.3.1. DSS PDFBoxDSS allows switching between two implementations of the PDFBox framework: default (original) and native.
By default, DSS uses the "Native Drawer" as the PDFBox implementation. In order to switch the implementation, that allowed at runtime, you have to set a new instance for PdfObjFactory as following: Runtime PDF Object Factory changing
Or create a new file 17.1.3.2. DSS OpenPDFThis implementation is based on the OpenPDF framework. DSS provides two drawers using the implementation:
17.2. MultithreadingDSS can be used in multi-threaded environments but some points need to be considered like resources sharing and caching. All operations are stateless and this fact requires to be maintained. Some resources can be shared, others are proper to an operation. For
each provided operation, DSS requires a 17.2.1. Resource sharingThe trusted certificates can be shared between multiple threads because these certificates are static. This means they don’t require more analysis. Their status won’t evolve. For these certificates, DSS doesn’t need to collect issuer certificate and/or their revocation data. In opposition, the adjunct certificates cannot be shared. These certificates concern a specific signature/validation operation. This parameter is used to provide missing certificate(s). When DSS is unable to build the complete certificate path with the provided certificates (as signature parameters or embedded within a signature), it is possible to inject certificates that are not present. These certificates are not necessarily trusted and may require future "modifications" like revocation data collection, etc. 17.2.2. CachingIn case of multi-threading usage, we strongly recommend caching of external resources. All external resources can be cached (AIA, CRL, OCSP) to improve performances and to avoid requesting too much time the same resources. FileCacheDataLoader and JdbcCacheCRLSource can help you in this way. See section Caching use cases of the Annex for complete examples of caching revocation data, certificates and trusted lists. 17.3. JAXB modules17.3.1. GeneralDSS provides the following JAXB modules with a harmonized structure :
All modules share the same logic and have the following structure (where *** is a model name):
/src/main/resources
/xslt
In the main classes, a DetailedReportFacade usage
An DetailedReportXmlDefiner usage
17.3.2. Creating a trusted listIt is possible to programmatically create or/and edit an XML Trusted List using the JAXB module. Below is an example of how to use JAXB modules to create a trusted list (not complete solution): Creation of a trusted list
And an example how to modify an existing Trusted List (e.g. change its version): Edit a trusted list
17.3.3. Validating XSD conformityYou can also use JAXB modules not only for the content creation or changing, but also in order to verify the conformity of an XML document against its XSD schema. For example,
in order to validate a XAdES signature conformance against 1.3.2 XSD schema, you can use the corresponding class Validating XSD conformity
17.3.4. Report stylesheetsThe report modules (namely:
In order to generate a report with a selected style sheet you need to call a relevant method in a Facade class (see classes definition above): HTML report generation
Otherwise, in case you need to customize the transformer, you can create a report by using an Custom report generation
17.3.5. Diagnostic data stylesheetsThe SVG generation
17.4. XML securitiesThe framework allows custom configuration of XML-related modules for enabling/disabling of XML securities (e.g. in order to use Xalan or Xerces).
The configuration is available for the following classes:
All
the classes can be configured with the following methods (example for XMLSecurities configuration
The
DocumentBuilderFactory configuration
The class 17.5. DSS Resources HandlerSince version 5.11, DSS provides a possibility to configure a way temporary objects are created within the core code.
The
The In order to create a
To define the resources handler, the corresponding PAdES signing using temporary files
17.6. ZIP UtilsFor parsing and creation of ZIP archives a special class By default, an instance of Below you can find the configuration available in SecureContainerHandler for ZipUtils configuration
18. DSS upgrades and change history18.1. Release notesTable 10. Release notes
* October 2015: Implementing Acts Art. 27 & 37 (eSig formats) 18.2. Version upgradeTo upgrade version of DSS, locate to the pom.xml
18.3. Migration guideThis chapter covers the most significant changes in DSS code occurred between different versions, requiring review and possible changes from code implementors. Table 11. Code changes from version 5.10/5.10.1/5.10.2 to 5.11
18.4. Validation policy migration guideTable 14. Policy changes from version 5.10 to 5.11
18.5. Frequently asked questions and implementation issuesThis chapter covers the most frequently asked questions and issues occurring in implementations using DSS. Table 17. Possible problems and solutions
19. Annex19.1. Use of Alerts throughout the frameworkThe framework includes an extended possibility to execute custom processes in case of arbitrary defined events. The
In its basic module, framework provides a few alerts based on a
The usage of alerts is available in the following classes:
19.2. Configuration of validation policy in different use cases19.2.1. GeneralA Signature validation policy is a set of rules/constraints that need to be fulfilled to validate a signature. When checking a constraints fails, this leads to a sub-indication in the validation report. 19.2.2. Validation policy constraintsThis chapter describes available constraints within the XML Validation Policy used in DSS and their applicability rules. This document is completed with conformance to the policy.xsd schema of the latest version of DSS. 19.2.2.1. Container constraintsThe ContainerConstraints element definition
Default: Example of AcceptableContainerTypes usage (with FAIL validation level)
Default: not executed Example of ZipCommentPresent usage (with WARN validation level)
Default: not executed Example of AcceptableZipComment usage (with WARN validation level)
Default: Example of MimeTypeFilePresent usage (with INFORM validation level)
Default: Example of AcceptableMimeTypeFileContent usage (with WARN validation level)
Default: Example of ManifestFilePresent usage (with FAIL validation level)
Default: Example of SignedFilesPresent usage (with FAIL validation level)
Default: Example of AllFilesSigned usage (with WARN validation level)
19.2.2.2. Signature constraintsThe SignatureConstraints element definition
Default: Example of StructuralValidation usage (with WARN validation level)
The constraint allows definition of acceptable signature policy identifiers (e.g. OID) or one of the special values:
Default: Example of AcceptablePolicies usage (with FAIL validation level)
Default: Example of PolicyAvailable usage (with FAIL validation level)
Default: not executed Example of SignaturePolicyStorePresent usage (with FAIL validation level)
Default: Example of PolicyHashMatch usage (with FAIL validation level)
Default: Example of AcceptableFormats usage (with FAIL validation level)
Default: not executed Example of FullScope usage (with FAIL validation level)
19.2.2.2.1. Basic Signature Constraints The BasicSignatureConstraints element definition
Default: Example of ReferenceDataExistence usage (with FAIL validation level)
Default:
Example of ReferenceDataIntact usage (with FAIL validation level)
Default: Example of ManifestEntryObjectExistence usage (with WARN validation level)
Default: Example of SignatureIntact usage (with FAIL validation level)
Default: Example of SignatureValid usage (with FAIL validation level)
Default: Example of SignatureDuplicated usage (with FAIL validation level)
Default: Example of ProspectiveCertificateChain usage (with FAIL validation level)
Default:
Note: executed for PAdES only Example of SignerInformationStore usage (with FAIL validation level)
Default:
Note: executed for PAdES only Example of PdfPageDifference usage (with FAIL validation level)
Default: Note: executed for PAdES only Example of PdfAnnotationOverlap usage (with WARN validation level)
Default: Note: executed for PAdES only Example of PdfVisualDifference usage (with WARN validation level)
Default: Note: executed for PAdES only Example of DocMDP usage (with WARN validation level)
Default: Note: executed for PAdES only Example of FieldMDP usage (with WARN validation level)
Default: Note: executed for PAdES only Example of SigFieldLock usage (with WARN validation level)
Default: Note: executed for PAdES only Example of UndefinedChanges usage (with WARN validation level)
Default: not executed Example of TrustedServiceTypeIdentifier usage (with WARN validation level)
Default: not executed Example of TrustedServiceStatus usage (with FAIL validation level)
======= Certificate Constraints The block of Certificate constraints element definition
Default: Example of Recognition usage (with FAIL validation level)
Default: Example of Signature usage (with FAIL validation level)
Default: Example of NotExpired usage (with FAIL validation level)
Default: Example of AuthorityInfoAccessPresent usage (with WARN validation level)
Default: Example of RevocationInfoAccessPresent usage (with WARN validation level)
Default: Example of RevocationDataAvailable usage (with FAIL validation level)
Default: Example of AcceptableRevocationDataFound usage (with FAIL validation level)
Default: Note: applicable only for CRLs Example of CRLNextUpdatePresent usage (with WARN validation level)
Default: not executed Note: applicable only for CRLs Example of OCSPNextUpdatePresent usage (with WARN validation level)
Default: Example of RevocationFreshness usage (with IGNORE validation level)
Default: not executed Example of RevocationFreshnessNextUpdate usage (with FAIL validation level)
Default: Example of KeyUsage usage (with WARN validation level)
Default: not executed Example of ExtendedKeyUsage usage (with WARN validation level)
Default: not executed Example of Surname usage (with WARN validation level)
Default: not executed Example of GivenName usage (with WARN validation level)
Default: not executed Example of CommonName usage (with WARN validation level)
Default: not executed Example of Pseudonym usage (with WARN validation level)
Default: not executed Example of OrganizationUnit usage (with WARN validation level)
Default: not executed Example of OrganizationName usage (with WARN validation level)
Default: not executed Example of Country usage (with WARN validation level)
Default: Example of SerialNumberPresent usage (with WARN validation level)
Default: Example of NotRevoked usage (with FAIL validation level)
Default: Example of NotOnHold usage (with FAIL validation level)
Default: Example of RevocationIssuerNotExpired usage (with FAIL validation level)
Default: not executed Example of SelfSigned usage (with FAIL validation level)
Default: Example of NotSelfSigned usage (with WARN validation level)
Default: not executed Example of PolicyIds usage (with WARN validation level)
Default: not executed Example of PolicyQualificationIds usage (with WARN validation level)
Default: not executed Example of PolicyQualificationIds usage (with WARN validation level)
Default: not executed Example of QcCompliance usage (with WARN validation level)
Default: not executed Example of QcEuLimitValueCurrency usage (with WARN validation level)
Default: not executed Example of MinQcEuLimitValue usage (with WARN validation level)
Default: not executed Example of MinQcEuRetentionPeriod usage (with WARN validation level)
Default: not executed Example of QcSSCD usage (with WARN validation level)
Default: not executed Example of QcEuPDSLocation usage (with WARN validation level)
Default: not executed Example of QcType usage (with WARN validation level)
Default: not executed Example of QcLegislationCountryCodes usage (with WARN validation level)
Default: not executed Example of IssuedToNaturalPerson usage (with WARN validation level)
Default: not executed Example of IssuedToLegalPerson usage (with WARN validation level)
Default: not executed Example of SemanticsIdentifier usage (with WARN validation level)
Default: not executed Example of PSD2QcTypeRolesOfPSP usage (with WARN validation level)
Default: not executed Example of PSD2QcCompetentAuthorityName usage (with WARN validation level)
Default: not executed Example of PSD2QcCompetentAuthorityId usage (with WARN validation level)
Default: Example of UsePseudonym usage (with INFORM validation level)
19.2.2.2.2. Signed attribute constraints The SignedAttributes element definition
Default: Example of SigningCertificatePresent usage (with WARN validation level)
Default: Example of UnicitySigningCertificate usage (with WARN validation level)
Default: Example of SigningCertificateRefersCertificateChain usage (with WARN validation level)
Default: not executed Example of ReferencesToAllCertificateChainPresent usage (with WARN validation level)
Default: Example of SigningCertificateDigestAlgorithm usage (with WARN validation level)
Default:
Example of CertDigestPresent usage (with FAIL validation level)
Default: Example of CertDigestMatch usage (with FAIL validation level)
Default: Example of IssuerSerialMatch usage (with FAIL validation level)
Default: not executed Note: the check is executed only for JAdES Example of KeyIdentifierPresent usage (with WARN validation level)
Default: Note: the check is executed only for JAdES Example of KeyIdentifierMatch usage (with WARN validation level)
Default: Note: the check is executed only for JAdES Example of SigningTime usage (with FAIL validation level)
Default: not executed Example of ContentType usage (with FAIL validation level)
Default: not executed Note: executed for CAdES only Example of ContentHints usage (with FAIL validation level)
Default: not executed Note: executed for CAdES only Example of ContentIdentifier usage (with FAIL validation level)
Default: Note: executed for XAdES, CAdES, PAdES Example of MessageDigestOrSignedPropertiesPresent usage (with FAIL validation level)
Default: Note: executed for JAdES only Example of EllipticCurveKeySize usage (with WARN validation level)
Default: not executed Example of CommitmentTypeIndication usage (with WARN validation level)
Default: not executed Example of SignerLocation usage (with WARN validation level)
Default: not executed Example of ClaimedRoles usage (with WARN validation level)
Default: not executed Example of CertifiedRoles usage (with WARN validation level)
Default: not executed Example of ContentTimeStamp usage (with WARN validation level)
Default: not executed Example of ContentTimeStampMessageImprint usage (with WARN validation level)
19.2.2.2.3. Unsigned attribute constraints The SignedAttributes element definition
Default: not executed Example of CounterSignature usage (with WARN validation level)
19.2.2.3. Timestamp constraintsThe TimestampConstraints element definition
Default: Example of TimestampDelay usage (with IGNORE validation level)
Default: Example of RevocationTimeAgainstBestSignatureTime usage (with FAIL validation level)
Default: Example of BestSignatureTimeBeforeExpirationDateOfSigningCertificate usage (with FAIL validation level)
Default: Example of Coherence usage (with WARN validation level)
Default: not executed Example of TSAGeneralNamePresent usage (with WARN validation level)
Default: Example of TSAGeneralNameContentMatch usage (with WARN validation level)
Default: not executed Example of TSAGeneralNameOrderMatch usage (with WARN validation level)
19.2.2.4. Revocation constraintsThe TimestampConstraints element definition
Default: Example of UnknownStatus usage (with FAIL validation level)
Default: not executed Example of OCSPCertHashPresent usage (with FAIL validation level)
Default: not executed Example of OCSPCertHashMatch usage (with FAIL validation level)
Default: Example of SelfIssuedOCSP usage (with WARN validation level)
19.2.2.5. Cryptographic ConstraintsThe
Default: Example of AcceptableEncryptionAlgo usage (with FAIL validation level)
Default: Example of MiniPublicKeySize usage (with FAIL validation level)
Default:
Example of AcceptableDigestAlgo usage (with FAIL validation level)
Default: Example of AcceptableDigestAlgo usage (with FAIL validation level)
19.2.2.6. Model constraintThe Model may have one of the following values:
Model element definition
19.2.2.7. eIDAS constraintThe eIDAS element definition
Default: Example of TLFreshness usage (with WARN validation level)
Default: Example of TLNotExpired usage (with WARN validation level)
Default: Example of TLWellSigned usage (with WARN validation level)
Default: Example of TLVersion usage (with WARN validation level)
19.2.3. Validation results correspondence tableThis table defines the correspondence between the enforced validation policy constraints and the final validation results in case the related check fails. Table 18. Validation policy constraints
19.2.4. AdES validationAccording to ETSI EN 319 102-1 (cf. [R09]), the signature validation process can be separated to different levels:
DSS allows the user to choose the validation level when performing a signature validation, i.e. to specify the validation process to be used for validation (cf. [R09]). By default, the highest level (with LTA enabled) is used. 19.2.4.1. Basic AdES validationBelow you can find a signature validation example with a basic signature validation level: B-level AdES validation
19.2.4.2. Long Term AdES validationLTV-level AdES validation
19.2.4.3. Long Term Availability AdES validationLTA-level AdES validation
19.2.5. Trusted list validationA validation of a Trusted List is similar to a signature validation, with the only difference that the validation of a Trusted List can be done in offline mode. Additionally, a validation against the XSD schema should be performed. Validation of a trusted list
19.3. Caching use cases19.3.1. Caching revocation data (CRL, OCSP)19.3.1.1. CRLAn example for JdbcCacheCRLSource: JdbcCacheCRLSource usage
19.3.1.2. OCSPAn example for JdbcCacheOCSPSource: JdbcCacheOCSPSource usage
19.3.2. Caching certificates (AIA certificates)An example for JdbcCacheOCSPSource: Caching of certificates
19.3.3. Caching trusted listsTrusted Lists and List(s) of Trusted Lists are cached automatically as a part if To load Trusted Lists from a cache, the offline loader shall be configured, and the action can be performed with the method:
Trusted Lists update from a cache
19.4. Complete examples of Signature creation19.4.1. XAdESBelow is an example of the Create a XAdES-BASELINE-B signature
19.4.2. CAdESBelow is an example of the Signing a file with CAdES
19.4.3. PAdESBelow is an example of code to perform a Signing a PDF file with PAdES
19.4.3.1. PAdES Visible SignatureDSS provides a large set of utilities for PDF visible signature creation (see PAdES Visible Signature for more information). Below there is an example of code to perform a Add a visible signature to a PDF document
Additionally, DSS also allows you to insert a visible signature to an existing field : Add a visible signature to an existing field
The following sections present examples of existing parameters for creation of visible signatures with DSS. 19.4.3.1.1. Positioning DSS provides a set of functions allowing to place the signature field on a specific place in the PDF page : Visible signature positioning
19.4.3.1.2. Dimensions DSS framework provides a set of functions to manage the signature field size : Visible signature dimensions
19.4.3.1.3. Text Parameters The available implementations allow placing of a visible text to a signature field : List of available visible text parameters
19.4.3.1.4. Text and image combination DSS provides a set of functions to align a text respectively to an image. The parameters must be applied to a Combination of text and image parameters
The result of applying the foregoing transformations is provided on the image below: 19.4.3.1.5. Fonts usage You can create a custom font as following, for a physical font: Add a custom font as a file
For a logical font: Java font usage
For a native font: Native font usage
19.4.4. JAdESA typical example of a Signing a file with JAdES
19.4.5. ASiC19.4.5.1. ASiC-SThis is an example of the source code for signing a document using Sign a file within an ASiC-S container
19.4.5.2. ASiC-EThis is another example of the source code for signing multiple documents using Sign multiple files within an ASiC-E container
19.5. Examples of SCA and SCDev Topology and Workflows19.5.1. Hash computationIn order to avoid transfer of original or sensitive information, and also to reduce the amount of data by online protocols, a hash of a document or data to be signed can be computed. Hash computation
19.5.2. Detached signature based on digested documentWhen you want to keep your original documents private, a signature can be created in a detached way, by providing the digest of an original document only. You can find an example of a use case below: Detached signature based on digested document
19.5.3. Client-side signature creation with server-side remote key activationWhen a private key signing is operated remotely, i.e. on an external server, then the document preparation and the actual signing can be separated. The signature document is created on client’s side and the actual signature is made remotely. Refer to section Client-side signature creation with server-side remote key activation for a detailed description and visual illustration of the steps that take place in such a situation. See the code below for a code illustration: Creation of the signature envelope on client side and signature value on server side
19.6. Interpreting a detailed reportWe will illustrate here how to read a detailed validation report where the validation succeeds even though the signing certificate has been revoked. This will illustrate how to look up at which check failed and how the overall validation process can succeed even when a sub-process failed. First, as explained in Detailed report the structure of the detailed validation report is based on ETSI EN 319 102-1 ([R09]). This means that the detailed report is structured in terms of:
There are three validation processes specified in ETSI EN 319 102-1:
Those validation processes in turn rely on building blocks, which are denoted in ETSI EN 319 102-1 as:
DSS groups the basic building blocks and the additional building blocks related to the validation of a particular signature together. However, it separates the time-stamp validation builiding block from the rest and present it alongside the validation processes because this building block essentially consists in applying the validation process for basic signatures to a timestamp token taken as a CMS object. Now let’s see how this looks in a validation report (we use here the HTML representation provided by the demonstration). First, as mentioned, are the validation processes and the time-stamp validation building block, which are numbered in the figure below with:
As further illustrated in the figure above:
Additionally, each process has an associated indication, here:
Each of those indications is determined using the result of the associated building blocks, and applying additional checks. Here we can see that the Now delving into the building blocks themselves, we can see in the figure below that the building blocks are grouped by the signed objects to which they relate:
We saw previously that the "validation process for basic signature" resulted in the To check what went wrong, we must therefore look at the "X.509 Certificate Validation" building block associated to the signature, that is the "X.509 Certificate Validation" building block that is in BBB SIG. We see there that the check "Is the certificate validation conclusive?" has failed. Therefore, we now need to look at the "Certificate" sub-block of BBB SIG. In the "Certificate" sub-block
we can see that all checks succeeded except for "Is the certificate not revoked?". We can thus conclude that the validation process for basic signature resulted in the indication That being said, we saw before that although the validation process for basic signature failed with To understand why that is so, we need to look back at the signature validation processes. There we can see in the "validation process for Signatures with Time and Signatures with Long-Term Validation Material" that specific checks differing from the building blocks are executed. Which checks are executed depends on the indication determined during the "validation process for basic signatures". In the present case, because the indication was As mentioned before, best-signature-time is determined, for that validation process, using the signature timestamp. Because here the validation of the signature timestamp succeeded, the time indicated in the timestamp is used as best-signature-time, and because this time is indeed before the time of revocation of the signing certificate, the check succeeds, and the whole "validation process for Signatures with Time and Signatures with Long-Term Validation Material" succeeds. Now to understand why the overall result of the validation is
The overall validation result is then provided as the indication returned by the validation process against which the validation was performed. Although it is possible to only run the validation process for basic signature, in our case the process that was run was the "validation process for Signatures providing Long Term Availability and Integrity of Validation Material" which required to run the other two validation processes. Therefore, because that validation process returned Finally, the report contains information on the determination of the qualification of the signature. This determination is not specified in ETSI EN 319 102-1 ([R09]), but rather in ETSI TS 119 172-4 ([R10]). Essentially, a signature can be determined as qualified if:
We discussed above the validation processes defined in ETSI EN 319 102-1. The determinations of point 2 and 3 on the other hand rely on the procedures specified in ETSI TS 119 615 ([R14]). Without going into details, ETSI TS 119 615 specifies procedures for interpreting the content of EUMS trusted lists, including procedures for validating EUMS trusted lists. Illustrated in the figure above are the results of the main steps defined in that standard. 19.7. ASiC MergerSince DSS v5.11 the framework provides a possibility to merge ASiC containers of the same type (e.g. The possibility is provided with introduction of Sign multiple files within an ASiC-E container
The following implementations of
In order to use a selected class, the corresponding module shall be loaded within the project. When using provided implementations of the 19.8. ASiC Filename FactoryIn order to customize file naming within ASiC containers, DSS introduces For each container entry being created, the underlying service is making a call to the factory providing the current content of an ASiC container using an The following implementations are provided within DSS framework:
Below you can find an example of a SimpleASiCWithXAdESFilenameFactory use for a a custom signature filename
What approach to staffing has the following advantages 1 uses human resources effectively 2 helps build strong culture and informal management network?A geocentric staffing policy seeks the best people for key jobs throughout the organization, regardless of nationality. The advantages of a geocentric approach are: (1) Uses human resources efficiently, (2) Helps build strong culture and informal management network.
Is the term used to describe a company's activities that include compensation performance evaluations staffing and labor relations?Human Resource Management (HRM) is the term used to describe formal systems devised for the management of people within an organization. The responsibilities of a human resource manager fall into three major areas: staffing, employee compensation and benefits, and defining/designing work.
What are the three types of staffing policies that international companies can choose to implement?Research has identified three types of staffing policies in international businesses: the ethnocentric approach, the polycentric approach, and the geocentric approach.
Is a citizen of one country who is working in another country on an international assignment?An expatriate, or expat, is an individual living and/or working in a country other than their country of citizenship, often temporarily and for work reasons. An expatriate can also be an individual who has relinquished citizenship in their home country to become a citizen of another.
|