DSS-2468 - JDK 16 support - update documentation

:toc: left
:icons: font
:icon-set: far
= Digital Signature Service
:description: Documentation of the open source project DSS (Digital Signature Service). This project allows producing/validation of Advanced electronic signatures (AdES).
:keywords: electronic signature, XAdES, CAdES, PAdES, ASiC, open source, validation
version : {dssVersion} - {docdate}

== Introduction

=== Purpose of the document

This 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.

=== Scope of the document

This document provides examples of code which allow easy handling of digital signatures. The examples are consistent with the Release {dssVersion} of DSS framework which can be downloaded via https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/DSS+releases

Three main features can be distinguished within the framework :

 * The digital signature;
 * The extension of a digital signature and;
 * The validation of a digital signature.

On a more detailed manner the following concepts and features are addressed in this document:

 * Formats of the signed documents: XML, JSON, PDF, DOC, TXT, ZIP...;
 * Packaging structures: enveloping, enveloped, detached and internally-detached;
 * Forms of digital signatures: XAdES, CAdES, PAdES, JAdES and ASiC-S/ASiC-E;
 * Profiles associated to each form of the digital signature;
 * Trust management;
 * Revocation data handling (OCSP and CRL sources);
 * Certificate chain building;
 * Signature validation and validation policy;
 * Signature qualification;
 * Validation reports (Simple, Detailed, ETSI Validation report);
 * Management of signature tokens;
 * Validation of the signing certificate;
 * Timestamp creation;
 * Timestamp validation and qualification;
 * REST and SOAP webservices.

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.

Please note that the DSS framework is still under maintenance and new features will be released in the future.

=== Abbreviations and Acronyms

[cols=2]
.Abbreviations and Acronyms
|=======================
|Code			|Description
|AdES			|Advanced Electronic Signature
|API			|Application Programming Interface
|ASiC			|Associated Signature Containers
|BB				|Building Block (CEF)
|CA				|Certificate authority
|CAdES			|CMS Advanced Electronic Signatures
|CD				|Commission Decision
|CEF			|Connecting Europe Facility
|CMS			|Cryptographic Message Syntax
|CRL			|Certificate Revocation List
|CSP			|Core Service Platform (CEF)
|CSP			|Cryptographic Service Provider
|DER			|Distinguished Encoding Rules
|DSA			|Digital Signature Algorithm - an algorithm for public-key cryptography
|DSI			|Digital Service Infrastructure (CEF)
|DSS			|Digital Signature Service
|EC				|European Commission
|eID			|Electronic Identity Card
|ESI			|Electronic Signatures and Infrastructures
|ETSI			|European Telecommunications Standards Institute
|EUPL			|European Union Public License
|FSF			|Free Software Foundation
|GS				|Generic Service (CEF)
|GUI			|Graphical User Interface
|HSM			|Hardware Security Modules
|HTTP			|Hypertext Transfer Protocol
|I18N			|Internationalization
|JAdES          |JSON Advanced Electronic Signatures
|Java EE		|Java Enterprise Edition
|JavaDoc		|JavaDoc is developed by Sun Microsystems to create API documentation in HTML format from the comments in the source code. JavaDoc is an industrial standard for documenting Java classes.
|JAXB			|Java Architecture for XML Binding
|JCA			|Java Cryptographic Architecture
|JCE			|Java Cryptography Extension
|JDBC			|Java DataBase Connectivity
|JWS			|JSON Web Signatures
|LGPL			|Lesser General Public License
|LOTL			|List of Trusted List or List of the Lists
|LSP			|Large Scale Pilot
|MIT			|Massachusetts Institute of Technology
|MOCCA			|Austrian Modular Open Citizen Card Architecture; implemented in Java
|MS / EUMS		|Member State
|MS CAPI		|Microsoft Cryptographic Application Programming Interface
|OCF			|OEBPS Container Format
|OCSP			|Online Certificate Status Protocol
|ODF			|Open Document Format
|ODT			|Open Document Text
|OEBPS			|Open eBook Publication Structure
|OID			|Object Identifier
|OOXML			|Office Open XML
|OSI			|Open Source Initiative
|OSS			|Open Source Software
|PAdES			|PDF Advanced Electronic Signatures
|PC/SC			|Personal computer/Smart Card
|PDF			|Portable Document Format
|PDFBox			|Apache PDFBox - A Java PDF Library: http://pdfbox.apache.org/
|PKCS			|Public Key Cryptographic Standards
|PKCS#12		|It defines a file format commonly used to store X.509 private key accompanying public key certificates, protected by symmetrical password
|PKIX			|Internet X.509 Public Key Infrastructure
|RSA			|Rivest Shamir Adleman - an algorithm for public-key cryptography
|SCA			|Signature Creation Application
|SCD			|Signature Creation Device
|SME			|Subject Matter Expert
|SMO			|Stakeholder Management Office (CEF)
|SOAP			|Simple Object Access Protocol
|SSCD			|Secure Signature-Creation Device
|SVA			|Signature Validation Application
|TL				|Trusted List
|TLManager		|Application for managing trusted lists.
|TSA			|Time Stamping Authority
|TSL			|Trust-service Status List
|TSP			|Time Stamp Protocol
|TSP			|Trusted Service Provider
|TST			|Time-Stamp Token
|UCF			|Universal Container Format
|URI			|Uniform Resource Identifier
|WSDL			|Web Services Description Language
|WYSIWYS		|What you see is what you sign
|XAdES			|XML Advanced Electronic Signatures
|XML			|Extensible Markup Language
|ZIP			|File format used for data compression and archiving
|=======================

=== References

[%header,cols=4]
.References
|=======================
|Ref.			|Title																			|Reference					|Version
|[[R01]]	R01	|ESI - XAdES digital signatures													|ETSI EN 319 132 part 1-2	|1.1.1
|[[R02]]	R02	|ESI - CAdES digital signatures													|ETSI EN 319 122 part 1-2	|1.1.1
|[[R03]]	R03	|ESI - PAdES digital signatures													|ETSI EN 319 142 part 1-2	|1.1.1
|[[R04]]	R04	|ESI - Associated Signature Containers (ASiC)									|ETSI EN 319 162 part 1-2	|1.1.1
|[[R05]]	R05	|ESI - JAdES digital signatures													|ETSI TS 119 182 part 1 	|draft 0.0.6
|[[R06]]	R06	|Document management - Portable document format - Part 1: PDF 1.7				|ISO 32000-1				|1
|[[R07]]	R07	|Directive 1999/93/EC of the European Parliament and of the Council of 13 December 1999 on a Community framework for electronic signatures.	|DIRECTIVE 1999/93/EC	|
|[[R08]]	R08	|Internet X.509 Public Key Infrastructure - Time-Stamp Protocol (TSP)			|RFC 3161					|
|[[R09]]	R09	|ESI - Procedures for Creation and Validation of AdES Digital Signatures		|ETSI EN 319 102-1			|1.1.1
|[[R10]]	R10	|ESI - Signature validation policy for European qualified electronic signatures/seals using trusted lists   |ETSI TS 119 172-4			|draft
|[[R11]]	R11	|ESI - Trusted Lists															|ETSI TS 119 612		    |2.1.1
|[[R12]]	R12	|eIDAS Regulation No 910/2014													|910/2014/EU			    |
|[[R13]]	R13	|ESI - Procedures for Creation and Validation of AdES Digital Signatures		|ETSI TS 119 102-2		    |1.2.1
|[[R14]]	R14	|ESI - Procedures for using and interpreting EU Member States national trusted lists						|ETSI TS 119 615		    |draft

|=======================

=== Useful links

 * https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/eSignature[CEF Digital]
 * https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/eSignature+FAQ[eSignature FAQ]
 * https://webgate.ec.europa.eu/tl-browser/#/[TL Browser]
 * https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/eSignature+validation+tests[eSignature validation tests]
 * https://ec.europa.eu/cefdigital/wiki/display/TLSO/Trusted+List+Manager+non-EU[Trusted List Manager non-EU]
 * https://github.com/esig/dss[Source code (GitHub)]
 * https://ec.europa.eu/cefdigital/code/projects/ESIG/repos/dss/browse[Source code (EC Bitbucket)]
 * https://ec.europa.eu/cefdigital/code/projects/ESIG/repos/dss-demos/browse[Source code demonstrations (EC Bitbucket)]
 * https://ec.europa.eu/cefdigital/tracker/projects/DSS/issues[Report an issue (EC Jira)]
 * https://esig-dss.atlassian.net/projects/DSS[Old Jira]

== Build instructions

The section explains the basic steps required to successfully build the DSS components.

=== DSS Core

This section explains the build and usage requirements for https://github.com/esig/dss[DSS framework].

==== Requirements

The latest version of DSS framework has the following minimal requirements:

 * Java 9 and higher (tested up to Java 16) for the build is required. For usage Java 8 is a mimimum requirement;
 * Maven 3.6 and higher;
 * Memory and Disk: see minimal requirements for the used JVM. In general the higher available is better;
 * Operating system: no specific requirements (tested on Windows and Linux).

NOTE: We strongly recommend using the latest available version of JDK, in order to have the latest security fixes and cryptographical algorithm updates.

WARNING: Before processing the build steps, please, ensure you have successfully installed Maven and JVM with a required version.

==== Adding as Maven dependency

The simplest way to include DSS to your Maven project is to add a repository into pom.xml file in the root directory of your project as following:

[source,xml]
----
<repositories>
	...

	<repository>
	  <id>cefdigital</id>
	  <name>cefdigital</name>
	  <url>https://ec.europa.eu/cefdigital/artifact/content/repositories/esignaturedss/</url>
	</repository>
</repositories>
----

After that specify a list of dependencies required for your project.

Refresh your project, in order to download the dependency and after you will be able to use all modules of DSS framework.

==== Maven build and profiles

In order to use a customized bundle of DSS, you may want to build the DSS Core framework modules.

NOTE: If you have implemented a new feature or fixed a bug issue, your pull requests are welcome at our https://github.com/esig/dss[GitHub Repository]

A simple build of the DSS Maven project can be done with the following command:

----
mvn clean install
----

NOTE: All listed commands must be executed from the project directory via a Command Line Interface (CLI).

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 custom profiles, allowing a customized behavior:

 * quick - disables unit tests and java-doc check, in order to process the build as quick as possible (takes 2-3 minutes).
 * slow-tests - executes all tests, including time-consuming unit tests.
 * owasp - runs validation of the project and using dependencies according to the https://nvd.nist.gov[National Vulnerability Database (NVD)].
 * jdk19-plus - executed automatically for JDK version 9 and higher. Provides a support of JDK 8 with newer versions.
 * spotless - used to add a licence header into project files.

WARNING: Some modules (e.g. `dss-utils`, `dss-crl-parser`, etc., see below) still have to be built completely when using the `quick` profile.

In order to run a build with a specific profile, the following command must be executed:

----
mvn clean install -P *profile_name*
----

==== Specific modules

Some modules of DSS framework have a specific behavior and need to be handled accordingly.

DSS contains a bundle of JAXB-based modules, generation Java classes in 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 represent this behavior:

 * specs-xmldsig;
 * specs-xades;
 * specs-trusted-list;
 * specs-validation-report;
 * specs-asic-manifest;
 * specs-saml-assertion;
 * dss-policy-jaxb;
 * dss-diagnostic-jaxb;
 * dss-detailed-report-jaxb;
 * dss-simple-report-jaxb;
 * dss-simple-certificate-report-jaxb.

Specific modules with JWS and JAdES specifications exist. These modules allow to validate the generated JSON against the related JSON Schema :

 * specs-jws;
 * specs-jades.

Also, as it was explained in the previous section, some modules are required to be built completely for a building of their dependent modules when using a quick profile, namely:

 * dss-utils;
 * dss-crl-parser;
 * dss-test;
 * dss-pades;
 * dss-asic-common.

The modules contain common interfaces, used in other DSS modules, as well as unit tests to ensure the equal behavior between their implementations.

==== Documentation generation

In order to generate HTML and PDF documentation for DSS project, the module `dss-cookbook` of DSS Core must be build with the following command (please, ensure that you are located in the `/dss-cookbook` directory):

----
mvn clean install -P asciidoctor
----

==== Javadoc generation

In order to generate https://ec.europa.eu/cefdigital/DSS/webapp-demo/apidocs/index.html[HTML Javadoc], you will need to build completely the DSS Core.

[[DSSDemo]]
=== DSS Demonstrations

This section explains the build and usage requirements for https://github.com/esig/dss-demonstrations[DSS Demonstration Applications].

==== Requirements

The minimal requirements to build/run DSS Demonstrations:

 * Java 8 and higher (tested up to Java 16) is required;
 * Maven 3.6 and higher (if build required);
 * Tomcat 8.5+ for Java 8 and Tomcat 9+ for Java 9 and higher (for Web-application);
 * Memory and Disk: see minimal requirements for the used JVM. In general the higher available is better;
 * Operating system: no specific requirements (tested on Windows and Linux).

==== Maven build

The build of the project can be done similarly to DSS Core framework build with the command `mvn clean install`.

Please, ensure, that you build modules what you really need. Ignore, build failures for non-required modules.

===== DSS Standalone Application

In order to build the standalone application, the following modules are required:

 * dss-mock-tsa;
 * dss-standalone-app;
 * dss-standalone-package.

If the build is successfull, you will be able to find out the following containers in the directory `/dss-standalone-app-package/target/`:

 * dss-standalone-app-package-minimal.zip - contains the application code. Requires JDK ad JavaFX installed on a target machine in order to run the application;
 * dss-standalone-app-package-complete.zip - contains the application code, as well as JDK and JavaFX library code. Can be run on a machine whithout pre-installed libraries.

In order to launch the application, you will need to extract the archive and run the file `dss-run.bat`.

===== DSS Web Application

To build the DSS Web Application the following modules are required:

 * dss-mock-tsa;
 * dss-demo-webapp;
 * dss-demo-bundle.

After a successful build, in the directory `/dss-demo-bundle/target/` you will be able to find out two containers: `dss-demo-bundle.zip` and `dss-demo-bundle.tar.gz`. Despite the container type, the content of both files is the same. After extracting the content, you will need to run the file `Webapp-Startup.bat` in order to launch the server and the file `Webapp-Shutdown.bat` to stop the server. After running the server, the web-application will be availble at the address `http://localhost:8080/`.

If during TL/LOTL loading you experience problems with some particular Trusted Lists, please refer the chapter <<KeyStore>> for a resolution.

The documentation and javadoc will be copied automatically from built DSS Core and available on the following addresses respectively:

 * HTML documentation : `http://localhost:8080/doc/dss-documentation.html`;
 * PDF documentation :  `http://localhost:8080/doc/dss-documentation.pdf`;
 * Javadoc : `http://localhost:8080/apidocs/index.html`.

In order to build a bundle for JDK 16, the following profile can be used from `dss-demo-bundle` module:

----
mvn clean install -P java16
----

This will create a bundle with Tomcat 9.

===== Integration tests

The `dss-demo-webapp` module provides a collection of integration tests in order to test the behavior of REST/SOAP web-services. In order to run the tests, a web-server with DSS Web Application shall be launched and the following profile need to be executed from the module:

----
mvn clean install -P run-integration-test
----

== General framework structure

DSS framework is a multi-modules project which can be built with Maven.

=== Maven modules

==== Shared modules

dss-enumerations:: Contains a list of all used enumerations in the DSS project.
dss-alerts:: Allows configuration of triggers and handers for arbitrary defined events.
dss-jaxb-parsers:: Contains a list of all classes used to transform JAXB objects/strings to Java objects and vice versa.

==== JAXB model modules

specs-xmldsig:: W3C XSD schema for signatures http://www.w3.org/2000/09/xmldsig
specs-xades:: ETSI EN 319 132-1 XSD schema for XAdES.
specs-trusted-list:: ETSI TS 119 612 XSD schema for parsing Trusted Lists.
specs-validation-report:: ETSI TS 119 102-2 XSD schema for the Validation report.
specs-asic-manifest:: ETSI EN 319 162 schema for ASiCManifest.
specs-saml-assertion:: OASIS schema for SAML Assertions.

'''
dss-policy-jaxb:: JAXB model of the validation policy.
dss-diagnostic-jaxb:: JAXB model of the diagnostic data.
dss-detailed-report-jaxb:: JAXB model of the detailed report.
dss-simple-report-jaxb:: JAXB model of the simple report.
dss-simple-certificate-report-jaxb:: JAXB model of the simple report for certificates.

==== JSON validation modules

specs-jws:: JSON Schemas based on the RFC 7515 specifications (not official)
specs-jades:: ETSI TS 119 182-1 v.0.0.6 JSON Schemas for JAdES

==== Utils modules

dss-utils:: API with utility methods for String, Collection, I/O,...
dss-utils-apache-commons:: Implementation of dss-utils with Apache Commons libraries.
dss-utils-google-guava:: Implementation of dss-utils with Google Guava.

==== i18n

dss-i18n:: a module allowing internationalization of generated reports.

==== Core modules

dss-model:: Data model used in almost every module.
dss-crl-parser:: API to validate CRLs and retrieve revocation data
dss-crl-parser-stream:: Implementation of dss-crl-parser which streams the CRL.
dss-crl-parser-x509crl:: Implementation of dss-crl-parser which uses the java object X509CRL.
dss-spi:: Interfaces, util classes to manipulate ASN1, compute digests,...
dss-document:: Common module to sign and validate document. This module doen't contain any implementation.
dss-service:: Implementations to communicate with online resources (TSP, CRL, OCSP).
dss-token:: Token definitions and implementations for MS CAPI, PKCS#11, PKCS#12.
validation-policy:: Business of the signature's validation (ETSI EN 319 102 / TS 119 172-4).
dss-xades:: Implementation of the XAdES signature, extension and validation.
dss-cades:: Implementation of the CAdES signature, extension and validation.
dss-jades:: Implementation of the JAdES signature, extension and validation.
dss-pades:: Common code which is shared between dss-pades-pdfbox and dss-pades-openpdf.
dss-pades-pdfbox:: Implementation of the PAdES signature, extension and validation with https://pdfbox.apache.org/[PDFBox].
dss-pades-openpdf:: Implementation of the PAdES signature, extension and validation with https://github.com/LibrePDF/OpenPDF[OpenPDF (fork of iText)].
dss-asic-common:: Common code which is shared between dss-asic-xades and dss-asic-cades.
dss-asic-cades:: Implementation of the ASiC-S and ASiC-E signature, extension and validation based on CAdES signatures.
dss-asic-xades:: Implementation of the ASiC-S and ASiC-E signature, extension and validation based on XAdES signatures.
dss-tsl-validation:: Module which allows loading / parsing / validating of LOTL and TSLs.

==== WebServices

dss-common-remote-dto:: Common classes between all remote services (REST and SOAP).
dss-common-remote-converter:: Classes which convert the DTO to DSS Objects.

'''
dss-signature-dto:: Data Transfer Objects used for signature creation/extension (REST and SOAP).
dss-signature-remote:: Common classes between dss-signature-rest and dss-signature-soap.
dss-signature-rest-client:: Client for the REST webservices.
dss-signature-rest:: REST webservices to sign (getDataToSign, signDocument methods), counter-sign and extend a signature.
dss-signature-soap-client:: Client for the SOAP webservices.
dss-signature-soap:: SOAP webservices to sign (getDataToSign, signDocument methods), counter-sign and extend a signature.

'''
dss-server-signing-dto:: Data Transfer Objects used for the server signing module (REST and SOAP).
dss-server-signing-common:: Common classes for server signing.
dss-server-signing-rest:: REST webservice for server signing.
dss-server-signing-rest-client:: REST client for server signing (sign method).
dss-server-signing-soap:: SOAP webservice for server signing.
dss-server-signing-soap-client:: SOAP client for server signing (sign method).

'''
dss-validation-dto:: Data Transfer Objects used for signature validation (REST and SOAP).
dss-validation-common:: Common classes between dss-validation-rest and dss-validation-soap.
dss-validation-rest-client:: Client for the REST signature-validation webservices.
dss-validation-soap-client:: Client for the SOAP signature-validation webservices.
dss-validation-rest:: REST webservices to validate a signature.
dss-validation-soap:: SOAP webservices to validate a signature.

'''
dss-certificate-validation-dto:: Data Transfer Objects used for certificate validation (REST and SOAP).
dss-certificate-validation-common:: Common classes between dss-certificate-validation-rest and dss-certificate-validation-soap.
dss-certificate-validation-rest-client:: Client for the REST certificate-validation webservice.
dss-certificate-validation-soap-client:: Client for the SOAP certificate-validation webservice.
dss-certificate-validation-rest:: REST webservice to validate a certificate.
dss-certificate-validation-soap:: SOAP webservice to validate a certificate.

'''
dss-timestamp-dto:: Data Transfer Objects used for timestamp creation.
dss-timestamp-remote-common:: Common classes between dss-timestamp-remote-rest and dss-timestamp-remote-soap.
dss-timestamp-remote-rest-client:: Client for the REST timestamp webservice.
dss-timestamp-remote-soap-client:: Client for the SOAP timestamp webservice.
dss-timestamp-remote-rest:: REST webservice to create a timestamp.
dss-timestamp-remote-soap:: SOAP webservice to create a timestamp.

==== Other modules

dss-test:: Mocks and util classes for unit tests.
dss-cookbook:: Samples and documentation of DSS used to generate this documentation.

[[dssUtils]]
=== DSS Utils

The module dss-utils offers an interface with utility methods to operate on String, Collection, I/O,... DSS framework provides two different implementations with the same behaviour :

 * dss-utils-apache-commons : this module uses Apache Commons libraries (commons-lang3, commons-collection4, commons-io and commons-codec).
 * dss-utils-google-guava : this module only requires Google Guava (recommended on Android).

If your integration include dss-utils, you will need to select an implementation.

[[dssCrlParser]]
=== DSS CRL Parser

DSS contains two ways to parse/validate a CRL and to retrieve revocation data. An alternative to the X509CRL java object was developed to face memory issues in case of large CRLs. The X509CRL object fully loads the CRL in memory and can cause OutOfMemoryError.

 * dss-crl-parser-x509crl : this module uses the X509CRL java object.
 * dss-crl-parser-streams : this module offers an alternative with a CRL streaming (experimental).

If your integration require dss-crl-parser, you will need to choose your implementation.

[[dssPades]]
=== DSS PAdES

Since the version 5.4, DSS allows generation/extension/validation PAdES signatures with two different frameworks : PDFBox and OpenPDF (fork of iText). The dss-pades module only contains the common code and requires an underlying implementation :

 * dss-pades-pdfbox : Supports drawing of custom text, images, as well as text+image, in a signature field.
 * dss-pades-openpdf : Supports drawing of custom text OR images in a signature field.

DSS permits to override the visible signature generation with these interfaces :

 * eu.europa.esig.dss.pdf.IPdfObjFactory
 * eu.europa.esig.dss.pdf.visible.SignatureDrawerFactory (selects the SignatureDrawer depending on the SignatureImageParameters content)
 * eu.europa.esig.dss.pdf.visible.SignatureDrawer

A new instance of the IPdfObjFactory can be created with its own SignatureDrawerFactory and injected in the padesService.setPdfObjFactory(IPdfObjFactory). By default, DSS uses an instance of ServiceLoaderPdfObjFactory. This instance checks for any registered implementation in the classpath with the ServiceLoader (potentially a service from dss-pades-pdfbox, dss-pades-openpdf or your own(s)).

==== DSS PDFBox

Since the version 5.5, DSS allows switching between two implementations of the framework PDFBox : default (original) and native.

 * Default Drawer : The original drawer implemented on the PDFBox framework, supports displaying of custom text, images, text+image combination in a signature field. The implementation does not include the provided custom text to the inner PDF structure, instead of it, the drawer creates an image representation of the provided text, which is added to the signature field (i.e. the text is not selectable and not searchable).
 * Native Drawer : Since the version 5.5, DSS includes a new implementation of PDFBox Drawer, that allows a user to add a real custom text, image or combination of text and image to a visible signature field. The native implementation embeds the provided custom text to the inner PDF structure, that makes the text selectable and searchable, and also clearer and smoother in comparison with the original implementation.

By default, DSS uses "Default Drawer" as the PDFBox implementation. In order to switch the implementation, that allowed in runtime, you have to set a new instance for PdfObjFactory as following:

[source,java,indent=0]
.Runtime PDF Object Factory changing
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java[tags=custom-factory]
----

== Available demonstrations

With the framework, some demonstrations are provided.

[horizontal]
dss-mock-tsa:: The class which generate false timestamps from a self-signed certificate.
sscd-mocca-adapter:: Adapter for the MOCCA connection.
dss-standalone-app:: Standalone application which allows signing a document with different formats and tokens (JavaFX).
dss-standalone-app-package:: Packaging module for dss-standalone-app.
dss-demo-webapp:: Demonstration web application which presents a part of the DSS possibilities.
dss-demo-bundle:: Packaging module for dss-demo-webapp.

WARNING: The demonstrations use a simulated timestamp service (Mock) so that is not recommended for a production usage.

The requirements and build instructions for DSS demonstrations can be found in the chapter <<DSSDemo>>.

== Signature's profile simplification

The different formats of the digital signature make possible to cover a wide range of real live cases of use of this technique. Thus we distinguish the following formats: XAdES, CAdES, PAdES, JAdES and ASIC. To each one of them a specific standard is dedicated. The wide variety of options, settings and versions of the standards makes their interoperability very difficult. This is the main reason for which new standards commonly called "baseline profiles" were published. Their goal is to limit the number of options and variants thereby making possible a better interoperability between different actors.

In general can be said that for each format of the digital signature the number of security levels defined in the new standards has been reduced. Below is a comparative table of old and new levels for each format of the signature:

[%header,cols=7*^.^]
.Signature supported profiles
|=======================
2+|XAdES				       2+|CAdES				             2+|PAdES                           |JAdES
|*STANDARD* 	   |*BASELINE*	 |*STANDARD*       |*BASELINE* 	   |*STANDARD*	    |*BASELINE*     |*BASELINE*
|XAdES-BES 		.2+|XAdES-B	     |CAdES-BES 	.2+|CAdES-B 	   |PAdES-BES    .2+|PAdES-B     .2+|JAdES-B
|XAdES-EPES					     |CAdES-EPES	 			       |PAdES-EPES
|XAdES-T 		   |XAdES-T      |CAdES-T 	       |CAdES-T   	   |PAdES-T 	    |PAdES-T        |JAdES-T
|XAdES-XL 		   |XAdES-LT  	 |CAdES-XL         |CAdES-LT 	   |PAdES-XL 	    |PAdES-LT       |JAdES-LT
|XAdES-A 		   |XAdES-LTA	 |CAdES-A 	       |CAdES-LTA 	   |PAdES-LTV 	    |PAdES-LTA      |JAdES-LTA
|=======================

Note that the new version (v4) of the DSS framework is compatible with the baseline profiles, it is no longer possible to use the standard profiles for signing purpose. The validation of the signature still takes into account the old profiles.

[.landscape]
<<<

=== Signature profile guide

Below 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.

.File formats and Signature types conformance
[%header,cols="12*^.^"]
|===
  3+|Signature profiles                                        |XML                            |JSON                           |PDF                            |Binary                         |Digest                         |Multiple files                 |Multiple signatures            |Counter signature              |Stand-alone timestamp
.10+|XAdES   .4+|Enveloping  |Base64 encoded                   |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |Embed XML                        |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |XML only                       |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |Manifest                         |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |Canonicalization                 |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |XML only                       |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
             .4+|Enveloped   |enveloped transformation         |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |based on XPath                   |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |based on Filter2                 |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |Canonicalization                 |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |XML only                       |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
              2+|Detached                                      |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
              2+|Internally Detached                           |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |XML only                       |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
.2+|CAdES     2+|Enveloping                                    |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
              2+|Detached                                      |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
|PAdES        2+|Enveloped                                     |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"]
.6+|JAdES    .3+|Enveloping  |Compact Serialization            |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]
                             |Flattened JSON Serialization     |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |JSON Serialization               |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
             .3+|Detached    |Compact Serialization            |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |SigD only                      |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]
                             |Flattened JSON Serialization     |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |SigD only                      |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |JSON Serialization               |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |SigD only                      |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
.2+|ASiC        |ASiCS       |CAdES / XAdES                    |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"]
                |ASiCE       |CAdES / XAdES                    |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"]
|===

[.portrait]
<<<

== The XML Signature (XAdES)

The 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:

 * XAdES Specifications (cf. <<R01>>)

After reading these documents, it is clear that:

 * To electronically sign a document, a signing certificate (that proves the signer's identity) and the access to its associated private key is needed.
 * To electronically validate a signed document the signer's certificate containing the public key is needed. To give a more colourful example: when a digitally signed document is sent to a given person or organization in order to be validated, the certificate with the public key used to create the signature must also be provided.

===	XAdES Profiles

The new ETSI standard defines four conformance levels to address the growing need to protect the validity of the signature in time. Henceforth to denote the level of the signature the word "level" will be used. Follows the list of levels defined in the standard:

 * XAdES-BASELINE-*B*: _Basic Electronic Signature_
The lowest and simplest version just containing the SignedInfo, SignatureValue, KeyInfo and SignedProperties. This level combines the old -BES and -EPES levels.
This form extends the definition of an electronic signature to conform to the identified signature policy.
 * XAdES-BASELINE-*T*: _Signature with a timestamp_
A timestamp regarding the time of signing is added to protect against repudiation.
 * XAdES-BASELINE-*LT*: _Signature with Long Term Data_
Certificates and revocation data are embedded to allow verification in future even if their original source is not available. This level is equivalent to the old -XL level.
 * XAdES-BASELINE-*LTA*: _Signature with Long Term Data and Archive timestamp_
By using periodical timestamping (e.g. each year) compromising is prevented which could be caused by weakening previous signatures during a long-time storage period. This level is equivalent to the old -A level.

NOTE: Old levels: -BES, -EPES, -C, -X, -XL, -A are not supported any more when signing.

==== XAdES-BASELINE-B

To start, let's take a simple XML document:

[[xml_example.xml]]
[source,xml]
.xml_example.xml
----
<?xml version="1.0"?>
<test>Hello World !</test>
----

Since this is an XML document, we will use the XAdES signature and more particularly XAdES-BASELINE-B level, which is the lowest level of protection: just satisfying Directive (cf. <<R07>>) legal requirements for advanced signature. The normal process of signing wants to sign first with the level -B or level-T, and then later when it becomes necessary to complete the signature with superior levels. However, the framework allows signing directly with any level.
When 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. So, we need to define the packaging of the signature, namely ENVELOPED, ENVELOPING, DETACHED or INTERNALLY-DETACHED. More information about supported reference transformations for each signature packaging (except 'Detached'), can be found in the section <<Reference Transformations>>

 * *ENVELOPED :* when the signature applies to data that surround the rest of the document;
 * *ENVELOPING :* when the signed data form a sub-element of the signature itself;
 ** Base64 encoded binaries;
 ** Embed XML object(s);
 ** Embed https://www.w3.org/TR/xmldsig-core/#sec-o-Manifest[Manifest] object(s).
 * *DETACHED :* when the signature relates to the external resource(s) separated from it.
 * *INTERNALLY-DETACHED :* when the signature and the related signed data are both included in a parent element (only XML).

For our example, we will use ENVELOPED packaging.

The DSS framework uses 3 atomic steps to sign a document :

. Compute the digest to be signed;
. Sign the digest;
. Sign the document (add the signed digest).

The DSS fully manages the steps 1 and 3. We need to specify how to do the signature operation. DSS offers some implementations in the dss-token module

To write our Java code, we still need to specify the type of KeyStore to use for signing our document, more simply, where the private key can be found. In the package "eu.europa.esig.dss.token", we can choose between different connection tokens :

 * *Pkcs11SignatureToken :* allows communicating with SmartCards with the PKCS#11 interface. It requires some installed drivers (dll, sso,...) .
 * *Pkcs12SignatureToken :* allows signing with a PKC#12 keystore (.p12 file).
 * *MSCAPISignatureToken :* handles the signature with MS CAPI (the Microsoft interface to communicate with SmartCards).
 * *JKSSignatureToken :* allows signing with a Java Key Store (.jks file).

NOTE: The DSS also provides the support for MOCCA framework to communicate with the Smartcard with PC/SC, but it involves the installation of the MOCCA and IAIK libraries.

To know more about the use of the different signature tokens, please consult "Management of Signature Tokens" chapter.

In our example the class: "Pkcs12SignatureToken" will be used. A file in PKCS#12 format must be provided to the constructor of the class. It contains an X.509 private key accompanying the public key certificate and protected by symmetrical password. The certification chain can also be included in this file. It is possible to generate dummy certificates and their chains with OpenSSL. Please visit http://www.openssl.org/ for more details.

This is the complete code that allows you to sign our XML document.

[source,java,indent=0]
.Create a XAdES signature
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBTest.java[tags=demo]
----

What you may notice is that to sign a document we need to:

 * Create an object based on SignatureParameters class. The number of specified parameters depends on the type of signature. Generally, the number of specified parameters depends on the profile of signature. This object also defines some default parameters.
 * Choose the profile, packaging, signature digest algorithm.
 * Indicate the private key entry to be used.
 * Instantiate the adequate signature service.
 * Carry out the signature process.

The encryption algorithm is determined by the private key and therefore cannot be compelled by the setter of the signature parameters object. It will 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. See clause "Signing process" for more information.
In the case where the private key entry object is not available, it is possible to choose the signing certificate and its certificate chain as in the following example:

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=demoCertificateChain]
----

Integrating the certificate chain in the signature simplifies the build of a prospective certificate chain during the validation process.

By default the framework uses the current date time to set the signing date, but in the case where it is necessary to indicate the different time it is possible to use the setter "setSigningDate(Date)" as in the example:

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=demoSigningDate]
----

When the specific service is instantiated a certificate verifier must be set. This object is used to provide four different sources of information:

 * the source of trusted certificates (based on the trusted list(s) specific to the context);
 * the source of intermediate certificates used to build the certificate chain till the trust anchor. This source is only needed when these certificates are not included in the signature itself;
 * the source of OCSP;
 * the source of CRL.

In the current implementation this object is only used when profile -LT or -LTA are created.

===== Signing process

Once the parameters of the signature were identified the service object itself must be created. The service used will depend on the type of document to sign. In our case it is an XML file, so we will instantiate a XAdES service. The process of signing takes place in three stages. The first is the `getDataToSign()` method call, passing as a parameter the document to be signed and the previously selected settings. This step returns the data which is going to be digested and encrypted. In our case it corresponds to the SignedInfo XMLDSig element.

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=demoSigningProcessGetDataToSign]
----

The next step is a call to the function `sign()` which is invoked on the object token representing the KeyStore and not on the service. This method takes three parameters. The first is the array of bytes that must be signed. It is obtained by the previous method invocation. The second is the algorithm used to create the digest. You have the choice between SHA1, SHA256, and SHA512 (this list is not exhaustive). And the last one is the private key entry.

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=demoSigningProcessSign]
----

The 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 the method `signDocument()` on the service. We must pass to it three parameters: again the document to sign, the signature parameters and the value of the signature obtained in the previous step.

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.

When the breakdown of this process is not necessary, than a simple call to only one method can be done as in the following example:

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=demoSigningProcessSignDocument]
----

===== Additional attributes

For this type (XAdES-BASELINE-B) of signature it is possible to identify some additional attributes.

[[SignXmlXadesBPropertiesTest.java]]
[source,java,indent=0]
.XAdES signature with additional signed attributes
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBPropertiesTest.java[tags=demo]
----

In XAdES format the following types of a Content Timestamp can be used:

 * AllDataObjectsTimeStamp - each time-stamp token within this property covers the full set of references defined in the Signature's SignedInfo element, excluding references of type "SignedProperties".
 * IndividualDataObjectsTimeStamp - each time-stamp token within this property covers selected signed data objects.

The code above produces the following signature :

.XAdES signature example
include::_samples/xades-b-properties.adoc[]

==== XAdES-BASELINE-T

XAdES-BASELINE-T is a signature for which there exists a trusted time associated to the signature. It provides the initial steps towards providing long term validity and more specifically it provides a protection against repudiation. This extension of the signature can be created as well during the generation process as validation process. However, the case when these validation data are not added during the generation process should no longer occur. The XAdES-BASELINE-T trusted time indications must be created before the signing certificate has been revoked or expired and close to the time that the XAdES signature was produced. The XAdES-BASELINE-T form must be built on a XAdES-BASELINE-B form. The DSS framework allows extending the old -BES and -EPES profiles to the new BASELINE-T profile, indeed there is no difference in the structure of the signature.

To implement this profile of signature you must indicate to the service the TSA source, which delivers from each Timestamp Request a Timestamp Response (RFC 3161 (cf. <<R08>>)) containing tokens. Below is the source code that creates a XAdES-BASELINE-T signature. For our example, we will use the Belgian provider and an instance of OnlineTSPSource (see "TSP Sources" chapter for more details).

[source,java,indent=0]
.Create a XAdES-Baseline-T with an OnlineTSPSource
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesTWithOnlineSourceTest.java[tags=demo]
----

If the timestamp source is not set a NullPointerException is thrown.

The SignatureTimeStamp mandated by the XAdES-T form appears as an unsigned property within the QualifyingProperties:

.XAdES Signature Timestamp
include::_samples/xades-signature-timestamp.adoc[]

==== XAdES-BASELINE-LT

This level has to prove that the certification path was valid, at the time of the validation of the signature, up to a trust point according to the naming constraints and the certificate policy constraints from the "Signature Validation Policy". It will add to the signature the CertificateValues and RevocationValues unsigned properties. The CertificateValues element contains the full set of certificates that have been used to validate the electronic signature, including the signer's certificate. However, it is not necessary to include one of those certificates, if it is already present in the ds:KeyInfo element of the signature. This is like DSS framework behaves. 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 CertificateVerifier must be passed to the service. The implementer must set some of its properties (e.g. a source of trusted certificates). The code below shows how to use the default parameters with this object. Please refer to "The Signature Validation" chapter to have the further information. It also includes an example of how to implement this level of signature:

[[SignXmlXadesLTTest.java]]
[source,java,indent=0]
.SignXmlXadesLTTest.java
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesLTTest.java[tags=demo]
----

The following XML segment will be added to the signature qualified and unsigned properties:

.Validation data values
include::_samples/xades-revocation-data.adoc[]

NOTE: The use of online sources can significantly increase the execution time of the signing process. For testing purpose you can create your own source of data.

In last example the CommonsHttpDataLoader is used to provide the communication layer for HTTP protocol. Each source which need to go through the network to retrieve data need to have this component set.

==== XAdES-BASELINE-LTA

When the cryptographic data becomes weak and the cryptographic functions become vulnerable the auditor should take steps to maintain the validity of the signature. The XAdES-BASELINE-A form uses a simple approach called "archive validation data". It adds additional time-stamps for archiving signatures in a way that they are still protected, but also to be able to prove that the signatures were validated at the time when the used cryptographic algorithms were considered safe. The time-stamping process may be repeated every time the protection used becomes weak. Each time-stamp needs to be affixed before either the signing key or the algorithms used by the TSA are no longer secure. XAdES-A form adds the ArchiveTimestamp element within the UnsignedSignatureProperties and may contain several ArchiveTimestamp elements.

Below is an example of the implementation of this level of signature (but in practice, we will rather extend the signature to this level when there is a risk that the cryptographic functions become vulnerable or when one of certificates arrives to its expiration date):

[source,java,indent=0]
.Signature level setting
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=demoSignatureLevel]
----

The following XML segment will be added to the signature qualified and unsigned properties:

.XAdES Archive Timestamp
include::_samples/xades-archive-timestamp.adoc[]

=== Versions support

DSS supports the following XAdES formats :

[cols="5*^"]
.Supported XAdES versions
|===
| | B-level | T-level | LT-level | LTA-level

| XAdES 1.1.1 | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:times-circle[role="red"]

| XAdES 1.2.2 | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:times-circle[role="red"]

| XAdES 1.3.2 | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"]

| XAdES 1.4.1  4+| The format contains qualifying properties for XAdES 1.3.2 LTA level
|===

The XAdES Profile, as well as a customizable prefixes can be set with following methods :

[source,java,indent=0]
.XAdES formats and prefixes
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[tags=demoPrefixes]
----

=== Reference Transformations

In case of 'Enveloping', 'Enveloped' and 'Internally Detached' signatures, it is possible to apply custom transformations for signing references in order to compute proper digest result. Example of a definition reference transformations, you can find below:

[[SignXmlXadesBWithTransformsTest.java]]
[source,java,indent=0]
.Custom transformations definition
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[tags=demo]
----

Current version of DSS supports the following transformations:

 * Enveloped - removes the current `Signature` element from the digest calculation of the reference.

WARNING: Enveloped Signature Transform does not support parallel signatures!

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[tags=demoEnvelopedTransform]
----

 * Canonicalization - any canonicalization algorithm that can be used for 'CanonicalizationMethod' can be used as a transform:

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[tags=demoCanonicalizationTransform]
----

 * Base64 - the transform is used if application needs to sign a RAW data (binaries, images, audio or other formats). The 'Base64 Transform' is not compatible with following signature parameters:

 ** Reference contains more than one transform (must be a sole element of the reference transforms);
 ** setEmbedXML(true) - embedded setting cannot be used;
 ** setManifestSignature(true) - As is apparent from the previous point, Manifest cannot be used with the Base64 Transform as well since it also must be embedded to the signature.

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[tags=demoBase64Transform]
----

 * XPath - allows signing a custom nodes in a signature or embedded document. DSS contains an additional class `XPathEnvelopedSignatureTransform` allowing to exclude signatures from the digested content (used for Enveloped signatures by default). Additional information about the 'XPath Transform' can be found https://www.w3.org/TR/xpath20/[by the link].

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[tags=demoEnvelopedXPathTransform]
----

 * XPath-2-Filter - an alternative to 'XPath Transform'. Additional information about the 'XPath2Filter Transform' can be found https://www.w3.org/TR/xmldsig-filter2/[by the link]. DSS contains an additional class `XPath2FilterEnvelopedSignatureTransform` allowing to exclude signatures from the digest calculation.

NOTE: Since DSS 5.7 the XPath-2-Filter transform is used by default for ENVELOPED signature packaging.

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[tags=demoEnvelopedXPath2FilterTransform]
----

 * XSLT Transform - This transform requires a 'org.w3.dom.Document' as an input, compatible with the normative https://www.w3.org/TR/xslt-30/[XSLT Specification]. Must be a sole transform.

NOTE: All transformations, except Base64, can be applied only to XML objects.

=== Multiple signatures

In everyday life, there are many examples where it is necessary to have multiple signatures covering the same document, such as a contract to purchase a vehicle. Independent signatures are parallel signatures where the ordering of the signatures is not important. The computation of these signatures is performed on exactly the same input but using different private keys.

=== XAdES and specific schema version

Some signatures may have been created with an older version of XAdES standard using different schema definition. To take into account the validation of such signatures the interface eu.europa.esig.dss.xades.definition.XAdESPaths was created. This interface allows to provide the different needed XPath expressions which are used to explore the elements of the signature. The DSS framework proposes 3 implementations :

 * XAdES132Paths (XAdES 1.3.2 / 1.4.1)
 * XAdES122Paths (XAdES 1.2.2)
 * XAdES111Paths (XAdES 1.1.1)

By default, all XAdES are supported and DSS loads/parses all versions of XAdES. That's possible to restrict to only one version of XAdES with the following code :

[source,java,indent=0]
.Customize the supported XAdES version(s) at the validation
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/validate/XAdES132OnlyTest.java[tags=demo]
----

=== Sign a Trusted List

The standard ETSI TS 119 612 specifies in its annex B the XML structure and the format of the signature (XAdES, enveloped signature, transformation, canonicalization, etc.). With the class `TrustedListSignatureParametersBuilder`, DSS is able to pre-configure the signature parameters to comply with the specifications and simplify the signature creation.

[source,java,indent=0]
.Sign a Trusted List with the TrustedListSignatureParametersBuilder
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignTrustedListTest.java[tags=demo]
----

== Signature Extension

The -B level contains immutable signed properties. Once this level is created, these properties cannot be changed.

The levels -T/-LT/-LTA add unsigned properties to the signature. This means that the properties of these levels could be added afterwards to any AdES signature. This addition helps to make the signature more resistant to cryptographic attacks on a longer period of time. The extension of the signature is incremental, i.e. when you want to extend the signature to the level -LT the lower level (-T) will also be added. The whole extension process is implemented by reusing components from signature production. To extend a signature we proceed in the same way as in the case of a signature, except that you have to call the function "extendDocument" instead of the "sign" function. Note that when the document is signed with several signatures then they are all extended.

=== BASELINE-T

The AdES-BASELINE-T trusted time indications have to be created before a certificate has been revoked or expired and close to the time that the AdES signature was produced. It provides a protection against repudiation. The framework adds the timestamp only if there is no timestamp or there is one but the creation of a new extension of the level-T is deliberate (using another TSA). It is not possible to extend a signature which already incorporates higher level as -LT or -LTA. In the theory it would be possible to add another -T level when the signature has already reached level -LT but the framework prevents this operation. Note that if the signed document contains multiple signatures, then all the signatures will be extended to level -T. It is also possible to sign a document directly at level -T.

Here is an example of creating an extension of type T:

[source,java,indent=0]
.Extend a XAdES signature
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/ExtendSignXmlXadesBToTTest.java[tags=demo]
----

Here is the result of adding a new extension of type-T to an already existing -T level signature:

.XAdES Unsigned Signature Properties
include::_samples/xades-extend-t-to-t.adoc[]

=== BASELINE-LT and -LTA

For these types of extensions, the procedure to follow is the same as the case of the extension of type T. Please refer to the chapter XAdES Profiles to know specific parameters for each level of signature and which must be positioned.

[[signatureValidation]]
== Signature Validation

Generally and following ETSI standard, the validation process of an electronic signature must provide one of these three following statuses: TOTAL-FAILED, TOTAL-PASSED or INDETERMINATE. A TOTAL-PASSED response indicates that the signature has passed verification and it complies with the signature validation policy. A TOTAL_FAILED response indicates that either the signature format is incorrect or that the digital signature value fails the verification. An INDETERMINATE validation response indicates that the format and digital signature verifications have not failed but there is an insufficient information to determine if the electronic signature is valid. For each of the validation checks, 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.

===	Validation Process

Since version 4.7 of the DSS framework the validation process is based on the latest ETSI standard <<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 dependences between these 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.

.Signature Validation Process
image::sig_validation_process.jpg[]

Note that the current version of the framework during the validation process does not indicate what part of a document was signed. However, in a case of XAdES signature XPath transformations presented in the signature will be applied, in the 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 the different detail levels concerning the validation result. They provide four kinds of visions for the validation process: macroscopic, microscopic, input data and ETSI Validation report conformant with the standard <<R09>>. For more information about these reports, please refer to "Simple Report" chapter.

Below is the simplest example of the validation of the signature of a document. The first thing to do is instantiating an object named validator, which orchestrates the verification of the different rules. To perform this it is necessary to invoke a static method fromDocument() on the abstract class `SignedDocumentValidator`. This method returns the object in question whose type is chosen dynamically based on the type of source document.

The next step is to create an object that will check the status of a certificate using the Trusted List model (see "Trusted Lists of Certification Service Provider" for more information). In order to achieve this, an instance of a `CertificateVerifier` must be created with a defined source of trusted certificates. In our example, the trusted source is instantiated with `CommonTrustedCertificateSource` class. As well as a trusted source the CertificateVerifier object needs an OCSP and/or CRL source and a TSL source (which defines how the certificates are retrieved from the Trusted Lists). See chapter "Management of CRL and OCSP Sources" for more information concerning sources.

[source,java,indent=0]
.Validation of a signature
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/validate/ValidateSignedXmlXadesBTest.java[tags=demo]
----

NOTE: When using the TrustedListsCertificateSource class, for performance reasons, consider creating a single instance of this class and initialize it only once.

NOTE: In general, the signature must cover the entire document so that the DSS framework can validate it. However, for example in the case of a XAdES signature, some transformations can be applied on the XML document. They can include operations such as canonicalization, encoding/decoding, XSLT, XPath, XML schema validation, or XInclude. XPath transforms permit the signer to derive an XML document that omits portions of the source document. Consequently those excluded portions can change without affecting signature validity.

[[signedDocumentValidator]]
==== SignedDocumentValidator

For execution of the validation process, DSS uses the 'SignedDocumentValidator' class. The DSS framework provides five implementations of validator:

 * `XMLDocumentValidator` - validates documents in XML format (XAdES format);
 * `CMSDocumentValidator` - validates documents in CMS format (CAdES format);
 * `PDFDocumentValidator` - validates documents in PDF format (PADES format);
 * `JWSCompactDocumentValidator` - validates documents with base64url encoded content (JAdES compact format);
 * `JWSSerializationDocumentValidator` - validates documents in JSON format (JAdES serialization formats);
 * `ASiCContainerWithXAdESValidator` - validates ASiC with XAdES containers;
 * `ASiCContainerWithCAdESValidator` - validates ASiC with CAdES containers;
 * `DetachedTimestampValidator` - validates CMS timestamps provided alone.

DSS initializes a relevant validator based on specific characteristics of an input file (e.g. a PDF file version declaration for a PDF file). It checks the file format and loads the required validator from a classpath. Below you can find a list of settings that can be used for the configuration of the class.

[source,java,indent=0]
.SignedDocumentValidator usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[tags=demo]
----

===	Validation Result Materials

The result of the validation process consists of three elements:

 * the Simple Report,
 * the Detailed Report,
 * the Diagnostic Data and
 * the ETSI Validation Report.

All these reports are encoded using XML, 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 to able to generate PDF or HTML reports (simple and detailed reports).

You will find below a detailed description of each of these elements.

==== Simple Report

This is a sample of the simple validation report:

.Simple Report
include::_samples/simple-report-example.adoc[]

The result of the validation process is based on very complex 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.

==== Detailed Report

This is a sample of the detailed validation report. Its structure is based on the ETSI standard <<R09>> and is built around Basic Building Blocks, Basic Validation Data, Timestamp Validation Data, AdES-T Validation Data and Long Term Validation Data. Some segments were deleted to make reading easier. They are marked by three dots:

.Detailed Report
include::_samples/detailed-report-example.adoc[]

For example the Basic Building Blocks are divided into seven elements:

 * FC - Format Checking
 * ISC - Identification of the Signing Certificate
 * VCI - Validation Context Initialization
 * RFC - Revocation Freshness Checker
 * XCV - X.509 certificate validation
 * CV - Cryptographic Verification
 * SAV - Signature Acceptance Validation

The following additional elements also can be executed in case of validation in the past :

 * PCV - Past Certificate Validation
 * VTS - Validation Time Sliding process
 * POE extraction - Proof Of Existence extraction
 * PSV - Past Signature Validation

Past certificate/signature validation is used when basic validation of a certificate/signature fails at the current time with an INDETERMINATE status such that the provided proofs of existence may help to go to a determined status. The process shall initialize the _best-signature-time_ either to a time indication for a related POE provided, or the current time when this parameter has not been used by the algorithm.

 * *Best-signature-time* is an internal variable for the algorithm denoting the earliest time when it can be trusted by the SVA (either because proven by some POE present in the signature or passed by the DA and for this reason assumed to be trusted) that a signature has existed. <<R09>>

Each block contains a number of rules that are executed sequentially. The rules are driven by the constraints defined in the validation policy. The result of each rule is OK or NOT OK. The process is stopped when the first rule fails. Each block also contains a conclusion. If all rules are met then the conclusion node indicates PASSED. Otherwise FAILED or INDETERMINATE indication is returned depending on the ETSI standard definition.

==== Diagnostic Data

This is a data set constructed from the information contained in the signature itself, but also from information retrieved dynamically as revocation data and information extrapolated as the mathematical validity of a signature. All this information is independent of the applied validation policy. Two different validation policies applied to the same diagnostic data can lead to different results.

This is an example of the diagnostic data for a XAdES signature. Certain fields and certain values were trimmed or deleted to make reading easier:

.Diagnostic Data
include::_samples/diagnostic-data-example.adoc[]

==== ETSI Validation Report

The ETSI Validation Report represents an implementation of TS 119 102-2 (cf. <<R13>>). The report contains a standardized result of an ASiC digital signature validation. It includes the original validation input data, the applied validation policy, as well as the validation result of one or more signature(s) and its(their) constraints.

This is an example of the ETSI validation report:

.ETSI Validation Report (TS 119 102-2)
include::_samples/etsi-validation-report-example.adoc[]

[[validationPolicy]]
=== Validation Policy

The validation process may be 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 https://github.com/esig/dss/blob/master/dss-policy-jaxb/src/main/resources/xsd/policy.xsd[policy.xsd] schema and passed to the relevant `DocumentValidator` as shown below.

[source,java,indent=0]
.Custom validation policy
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=validationPolicy]
----

==== XML policy structure

The validation policy allows to define different behavior for various validating token types or signature formats. The following groups are considered:

 * `ContainerConstraints` - defines rules for processing of ASiC containers validation;
 * `SignatureConstraints` - defines rules for signature basic building blocks processing and the related certificate chain;
 * `CounterSignatureConstraints` - allows to define custom rules for counter signature processing;
 * `Timestamp` - defines rules for timestamp validation;
 * `Revocation` - defines rules for revocation data validation;
 * `Cryptographic` - defines common rules for cryptographic validation of used algorithms. The general constraints are used when no cryptographic constraints are defined for a particular token type;
 * `Model` - defines the way of a certificate chain processing;
 * `eIDAS` - defines rules for validation of Trusted Lists.

==== Constraints

Each constraint defined in the policy forces an execution of a relevant check in the validation process.

NOTE: If a constraint is missing in the policy - the check is not processed.

The following constraint types are supported:

 * `LevelConstraint` - a simple constraint type with a defined processing `Level`;
 * `MultiValuesConstraint` - allows to define a set of accepted values relatively to the using constraint.

==== Level

The `Level` attribute of a constraint defines a validation process behavior in case of a check failure. While used, the following behaviors apply in case of a check failure:

 * `FAIL` - brakes the validation process and returns the relevant indication;
 * `WARN` - continues the validation process and returns a warning message to the validation process output;
 * `INFORM` - continues the validation process and returns an information message to the validation process output;
 * `IGNORE` - processes the check in a silent mode (equivalent to a not defined constraint).

==== Multi Values Constraint

When using the `MultiValuesConstraint`, a list of acceptable values shall be defined in the list of `<Id>...</Id>` elements, one for each accepted value. While doing, the following rules apply:

 * Empty list of values  -> accept only empty values for the item in question, fails otherwise;
 * `"*"` constraint value -> accepts all values, reject empty list of values;
 * Custom values -> accepts only item values matching the constraint.

==== Cryptographic constraints

Cryptographic constraints define a list of acceptable cryptographic algorithms and their expiration dates when needed. The following settings are possible:

 * `AcceptableEncryptionAlgo` - defines a list of acceptable encryption algorithms. All tokens and signatures using other algorithms will be rejected.
 * `MiniPublicKeySize` - defines the minimal allowed public key size to be used with the defined encryption algorithms. An algorithm with a key size less than the defined one will be rejected. The minimal key size if required to be defined for an encryption algorithm, otherwise all used key sizes will be rejected.
 * `AcceptableDigestAlgo` - defines a list of acceptable digest algorithms. All tokens and signatures using other algorithms will be rejected.
 * `AlgoExpirationDate` - defines expiration dates for the algorithms. The algorithm is rejected when it is used after the defined date. If the algorithm expiration date is not defined, or set to null, the algorithm is treated as reliable for an unlimited time.

==== The default XML policy

The default XML validation policy is present below.

.constraint.xml (default policy is provided in dss-policy-jaxb module)
include::_samples/constraint.adoc[]

== CAdES signature (CMS)

To familiarize yourself with this type of signature it is advisable to read the following document:

* CAdES Specifications (cf. <<R02>>)

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. Below is an example of the CAdES-Baseline-B signature:

[source,java,indent=0]
.Signing a file with CAdES
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlCadesBTest.java[tags=demo]
----

== PAdES signature (PDF)

The standard ISO 32000-1 (cf. <<R06>>) allows defining a file format for portable electronic documents. It is based on PDF 1.7 of Adobe Systems. Concerning the digital signature it supports three operations:

 * Adding a digital signature to a document,
 * Providing a placeholder field for signatures,
 * Checking signatures for validity.

PAdES defines eight different profiles to be used with advanced electronic signature in the meaning of European Union Directive 1999/93/EC (cf. <<R07>>):

 * PAdES Basic - PDF signature as specified in ISO 32000-1 (cf. <<R06>>). The profile is specified in ETSI EN 319 142 (cf. <<R03>>).
 * PAdES-BES Profile - based upon CAdES-BES as specified in ETSI EN 319 122 (cf. <<R02>>) with the option of a signature time-stamp (CAdES-T).
 * PAdES-EPES profile - based upon CAdES-EPES as specified in ETSI EN 319 122 (cf. <<R02>>). This profile is the same as the PAdES - BES with the addition of a signature policy identifier and optionally a commitment type indication.
 * PAdES-LTV Profile - This profile supports the long term validation of PDF Signatures and can be used in conjunction with the above-mentioned profiles.
 * Four other PAdES profiles for XML Content.

To familiarize yourself with this type of signature it is advisable to read the documents referenced above.

Below is an example of code to perform a PAdES-BASELINE-B type signature:

[source,java,indent=0]
.Signing a PDF file with PAdES
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBTest.java[tags=demo]
----

In order to add a timestamp to the signature (PAdES-T or LTA), a TSP source must be provided to the service.

To create PAdES-BASELINE-B level with additional options: signature policy identifier and optionally a commitment type indication, please observe the following example in code 5.

All these parameters are optional.

[source,java,indent=0]
.Defining a Signature Policy
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBTest.java[tags=policy]
----

The extension of a signature of the level PAdES-BASELINE-B up to PAdES-BASELINE-LTA profile will add the following features:

 * Addition of validation data to an existing PDF document which may be used to validate earlier signatures within the document (including PDF signatures and time-stamp signatures).
 * Addition of a document time-stamp which protects the existing document and any validation data.
 * Further validation data and document time-stamp may be added to a document over time to maintain its authenticity and integrity.

=== PAdES Visible Signature

The framework also allows creation of PDF files with visible signature as specified in ETSI EN 319 142 (cf. <<R03>>). In the `SignatureParameters` object, there's a special attribute named `SignatureImageParameters`. This parameter allows you customize the visual signature (with text, with image or with image and text).
Below there is an example of code to perform a PADES-BASELINE-B type signature with a visible signature:

[source,java,indent=0]
.Add a visible signature to a PDF document
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java[tags=parameters-configuration;sign]
----

Additionally, DSS also allows you to insert a visible signature to an existing field :

[source,java,indent=0]
.Add a visible signature to an existing field
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=select-pdf-signature-field]
----

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.

==== 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:

 * *OpenPDF (iText)* - supports separate image and text drawing;
 * *PDFBox Default* - supports separate image and text drawing, as well as a joint drawing of image and text together. Transforms text to an image;
 * *PDFBox Native* - supports separate image and text drawing, as well as a joint drawing of image and text together. Prints text in a native way, that increases quality of the produced signature.

===== Positioning

DSS provides a set of functions allowing to place the signature field on a specific place in the PDF page :

[source,java,indent=0]
.Visible signature positioning
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/PAdESVisibleSignatureSnippet.java[tags=positioning]
----

===== Dimensions

DSS framework provides a set of functions to manage the signature field size :

[source,java,indent=0]
.Visible signature dimensions
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/PAdESVisibleSignatureSnippet.java[tags=positioning]
----

===== Text Parameters

The available implementations allow placing of a visible text to a signature field :

[source,java,indent=0]
.List of available visible text parameters
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java[tags=text]
----

===== 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 'SignatureImageTextParameters' object :

[source,java,indent=0]
.Combination of text and image parameters
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java[tags=textImageCombination]
----

The result of applying the foregoing transformations is provided on the image below:

image::visual-sig-text-parameters.jpg[]

==== Fonts usage

Since version 5.5, DSS supports two types of fonts. The custom font must be added as an instance of `DSSFont` interface to a `SignatureImageTextParameters` object.
`DSSFont` interface has following common implementations:

 * `DSSFileFont` for using of physical fonts, which must be embedded to the produced PDF document. To create an instance of the class, you must pass to a `DSSFileFont` constructor an object of `DSSDocument` type or InputStream of the font file;
 * `DSSJavaFont` for using of logical fonts (default Java fonts). The logical Java fonts allow you to significantly reduce the document size, because these fonts cannot be embedded to the final PDF document. Be aware, because of the fact, using of logical fonts does not allow producing PDF documents satisfying the PDF/A standard. To create an instance of this class, you should pass as an input a `java.awt.Font` object or target font parameters (name, style, size).

WARNING: Logical fonts may have different implementations depending on a used PAdES Visible signature service or Operating System (OS). Keep this in mind when switching an implementation or system environment.

As well as classes allowing to define native fonts for used implementations (available since DSS 5.7):

 * `ITextNativeFont` to be used with `ITextSignatureDrawerFactory`;
 * `PdfBoxNativeFont` to be used with `PdfBoxNativeObjectFactory`.

You can create a custom font as following (for a physical font):

[source,java,indent=0]
.Add a custom font as a file
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java[tags=font]
----

For a logical font:

[source,java,indent=0]
.Java font usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleExistingTest.java[tags=font]
----

For a native font:

[source,java,indent=0]
.Native font usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/PAdESVisibleSignatureSnippet.java[tags=nativeFont]
----

By default, DSS uses a Google font : 'PT Serif Regular' (its physical implementation).

NOTE: 'Native PDFBox Drawer' implementation supports only one of the following fonts: SERIF, SANS-SERIF, MONOSPACED, DIALOG and DIALOG_INPUT.

=== 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 are no algorithms to detect the malicious change with 100% guarantee. For more information, please refer to https://pdf-insecurity.org/[the website].

Since v5.8, DSS provides a set of own utils to detect the "shadow attack" on a signed PDF document. The following algorithms have been introduced:

 * `Page amount difference` - the validation tool compares the number of pages between the obtained PDF and signed revision. If the numbers do not match, the validation fail. The validation level can be configured within the <<validationPolicy>> with the constraint `<PdfPageDifference>`.
 * `Annotations overlap` - DSS checks if any annotation overlaps occurred. The overlapping is potentially dangerous, because some annotations can cover a visual content, e.g. forms and signature fields. The validation level can be configured with the constraint `<PdfAnnotationOverlap>`.
 * `Visual difference` - DSS verifies the visual difference between the provided document and signed revision, excluding the newly created annotations (between the validating revisions). The validation level can be configured with the constraint `<PdfVisualDifference>`.

== JAdES signature (JWS)

Since v5.8, DSS includes a possibility of creation and validation of JSON Advanced signatures.

JSON format for AdES Signatures (cf. [R05]) represents an extension of JSON Web Signatures (JWS) as specified in https://tools.ietf.org/html/rfc7515[IETF RFC 7515].

WARNING: The implementation is based on a draft of the standard ETSI TS 119 182-1. Some modifications can occur in future releases.

A typical example of a JAdES signature creation is represented below:

[source,java,indent=0]
.Signing a file with JAdES
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlJadesBTest.java[tags=demo]
----

The specific parameters for JAdES signature are described in the next sections.

=== JWS Serialization type

A JWS signature can be represented in different forms which are supported by the JAdES as well:

 * `COMPACT_SERIALIZATION` represents a compact, URL-safe serialization. It has no JWS Unprotected Header, therefore only JAdES-BASELINE-B level is possible with the format.
 * `JSON_SERIALIZATION` represents a JSON object with a collection of signatures inside the `signatures` header that allows a parallel signing. It allows JAdES-BASELINE-T/-LT/-LTA signature extension levels.
 * `FLATTENED_JSON_SERIALIZATION` represents a JSON object with a single signature container. It allows JAdES-BASELINE-T/-LT/-LTA signature extension levels.

[source,java,indent=0]
.JWS Serialization type usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlJadesBTest.java[tags=serialization]
----

=== JAdES Signature Packaging

JAdES signatures allow two types of JWS Payload (signed data) inclusion: `ENVELOPING` and `DETACHED`.

==== Enveloping packaging

With `ENVELOPING` packaging the JWS Payload is enveloped into the JAdES Signature. The type only allows signing one document.

==== Detached packaging

A simple JWS signature allows a `DETACHED` packaging by omitting the JWS Payload in the created signature. For the validation process the detached content shall be provided and it is treated in the same way as attached.

To create a such signature, the parameter `SigDMechanism.NO_SIG_D` shall be set. The solution allows signing of only one document.

The JAdES standard [R05] provides a possibility for signing of multiple documents withing one signature in a detached way.

The following mechanisms are possible:

 * `HTTP_HEADERS` is used to sign an HTTP request. The signature may explicitly sign several HTTP headers (represented by the class `HTTPHeader`), as well as the HTTP message body (see the `HTTPHeaderDigest` class).

[source,java,indent=0]
.Configuration for signing with detached mechanism HttpHeaders
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignHttpHeadersJadesBTest.java[tags=demo]
----

 * `OBJECT_ID_BY_URI` can be used for signing of multiple documents. The signed files are dereferenced by URIs and their content is concatenated for generation of the JWS Payload.

 * `OBJECT_ID_BY_URI_HASH` similarly provides a possibility to sign multiple documents, by signing the computed digests of the original documents. The JWS Payload for this format stays empty.

[source,java,indent=0]
.Configuration for signing with detached mechanism ObjectIdByURIHash
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignMultipleDocumentsJadesTTest.java[tags=demo]
----

=== Base64Url encoding

The `Base64Url` represents a Base64 encoded format with URI safe alphabet (see https://tools.ietf.org/html/rfc4648[RFC 4648]).

JAdES signatures (as well as JWS) force some values to be Base64Url-encoded, while provides a possibility to customize the format for some of them.

DSS provides options to configure encoding for the following elements:

 * JWS Payload can be represented as Base64Url encoded octets (by default), as well as can be present in its initial form (with the protected header `b64` set to `false`).

[source,java,indent=0]
.Use unencoded JWS Payload
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignHttpHeadersJadesBTest.java[tags=unencodedPayload]
----

 * The components of the unsigned header `etsiU` can occur either as Base64Url encoded strings (by default), or as clear JSON objects.

NOTE: All components inside the `etsiU` header shall be present in the same form (Base64Url encoded or as clear JSON).

WARNING: The current version of DSS does not allow JAdES-BASELINE-LTA level creation for `etsiU` components in their clear JSON representation.

[source,java,indent=0]
.Represent EtsiU components as clear JSON instances
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignMultipleDocumentsJadesTTest.java[tags=clearEtsiU]
----

== ASiC signature (containers)

When creating a digital signature, the user must choose between different packaging elements, namely enveloping, enveloped or detached. This 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. That's where the standard ETSI EN 319 162 (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.

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; the first (ASiC-S) allows you to associate one or more signatures with a single data element. In this case the structure of the signature can be based (in a general way) on a single CAdES signature or on multiple XAdES signatures or finally on a single TST; the second is an extended container (ASiC-E) that includes multiple data objects. Each data object may be signed by one or more signatures which structure is similar to ASiC-S. This second type of container is compatible with OCF, UCF and ODF formats.

For the moment the 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.

.ASiC containers
|===
|Input |Output

|ASiC-S CAdES |ASiC-S CAdES

|ASiC-S XAdES |ASiC-S XAdES

|ASiC-E CAdES |ASiC-E CAdES

|ASiC-E XAdES |ASiC-E XAdES

|Binary |ASiC-S CAdES, ASiC-S XAdES, ASiC-E CAdES, ASiC-E XAdES
|===

This is an example of the source code for signing a document using ASiCS-S based on XAdES-B:

[source,java,indent=0]
.Sign a file within an ASiC-S container
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignOneFileWithASiCSBTest.java[tags=demo]
----

This is another example of the source code for signing multiple documents using ASiCS-E based on CAdES:

[source,java,indent=0]
.Sign multiple files within an ASiC-E container
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignMultipleDocumentsWithASiCSEWithCAdESTest.java[tags=demo]
----

Please note that you need to pass only few parameters to the service. Other parameters, although are positioned, will be overwritten by the internal implementation of the service. Therefore, the obtained signature is always based on CAdES and of DETACHED packaging.

It is also possible with the framework DSS to make an extension of an ASiC container to the level XAdES-BASELINE-T or -LT.

== Counter signatures

Since v5.8 DSS allows producing of counter signatures according to the corresponding AdES formats.

NOTE: Counter signature does not provide a Proof Of Existence for a signed signature! Use signature extension / timestamping for this purpose.

The following formats are supported for the counter signature creation:

 * `XAdES` - multiple, nested and extended counter signatures (up to LTA level) are allowed;
 * `CAdES` - B-level counter signatures are allowed, as well as multiple counter signatures;
 * `JAdES` - multiple, nested and extended signatures (up to LTA level) are allowed;
 * `ASiC` - counter signatures are allowed according to the used format (XAdES or CAdES).

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 represents a counter signature creation:

[source,java,indent=0]
.Counter signature creation
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/CounterSignXadesBTest.java[tags=demo]
----

== Various parameters

[[signaturePolicy]]
=== Signature policy

With the new standards the policy handling is linked to -B level. The old -EPES level is not used anymore by the framework. This does not alter the structure of the old signature but only modifies how to control the process of its creation.

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. It includes two kinds of text:

* In a human readable form:
It can be assessed to meet the requirements of the legal and contractual context in which it is being applied.

* In a machine processable form:
To facilitate its automatic processing using the electronic rules.

If no signature policy is identified then the signature may be assumed to have been generated or verified without any policy constraints, and hence may be given no specific legal or contractual significance through the context of a signature policy.

The signer may reference the policy either implicitly or explicitly. An implied policy means the signer follows the rules of the policy but the signature does not indicate which policy. It is assumed the choice of policy is clear from the context in which the signature is used and SignaturePolicyIdentifier element will be empty. When the policy is not implied, the signature contains an ObjectIdentier that uniquely identifies the version of the policy in use. The signature also contains a hash of the policy document to make sure that the signer and verifier agree on the contents of the policy document.

This example demonstrates an implicit policy identifier. To implement this alternative you must set SignaturePolicyId to empty string.

[source,java,indent=0]
.XAdES with implicit policy
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBImplicitPolicyTest.java[tags=demo]
----

An XML segment will be added to the signature's qualified and signed properties:

include::_samples/xades-implicit-policy.adoc[]

The next example demonstrates an explicit policy identifier. This is obtained by setting -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 to the developer to proceed with the calculation using for example java.security.MessageDigest class (rt.jar). 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. See also chapter 7 for further information.

[source,java,indent=0]
.XAdES with explicit policy
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBExplicitPolicyTest.java[tags=demo]
----

The following XML segment will be added to the signature qualified & signed properties (<QualifyingProperties><SignedProperties>):

.XAdES Signature Policy element
include::_samples/xades-explicit-policy.adoc[]

=== Signature Policy Store

Since v5.8 DSS 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:

* XAdES (as well as ASiC with XAdES);
* CAdES (as well as ASiC with CAdES);
* JAdES.

NOTE: Being an unsigned component the Signature Policy Store is not protected by a digital signature, unlike a Signature Policy Identifier incorporated into the signed properties.

Before incorporating of a Signature Policy Store, you need to ensure the target signature contains the matching Signature Policy Identifier element (see ch. <<signaturePolicy>>).

An example of a Signature Policy Store creation is available below:

[source,java,indent=0]
.Add SignaturePolicyStore
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBExplicitPolicyTest.java[tags=addSPS]
----

=== Trust anchor inclusion policy

It is possible to indicate to the framework if the certificate related to the trust anchor should be included to the signature or not. The setter #setTrustAnchorBPPolicy of the BLevelParameters class should be used for this purpose.

This rule applies as follows: when -B level is constructed the trust anchor is not included, when -LT level is constructed the trust anchor is included.

NOTE: When trust anchor baseline profile policy is defined only the certificates previous to the trust anchor are included when -B level is constructed.

== Timestamps

=== Timestamp creation

Since DSS 5.6 the framework allows an independent document timestamping (without a signature). The following Document Signature Services support the timestamping :

 * `PAdESService` - adds a timestamp to a PDF document;
 * `ASiCWithCAdESService` - creates a timestamped ASiC container with provided documents.

[source,java,indent=0]
.PDF timestamping
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/timestamp/TimestampPDFTest.java[tags=creation]
----

=== Timestamp validation

As well as a single timestamp creation, DSS provides a validation service for timestamped documents. The timestamp validation process represents "5.4 Time-stamp validation building block" (cf. <<R09>>). The validation process is identical to <<signatureValidation>> process. An appropriate validator will be selected automatically. In total, DSS supports timestamp-alone validation for the following file formats:

 * Detached CMS timestamp (`DetachedTimestampValidator`) - a detached signed content must be provided (or its digest);
 * PDF document (`PDFDocumentValidator`);
 * ASiC CAdES container with a timestamp (`ASiCWithCAdESTimestampValidator`).

The validation process can be run with the following inputs :

[source,java,indent=0]
.Timestamped document validation
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/timestamp/TimestampPDFTest.java[tags=validation]
----

The produced reports use the same structure as for <<signatureValidation>>.

==== Timestamp qualification

DSS is also 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 <<tlValidationJob>>) (cf. <<R14>>).

Three qualification levels are supported by DSS and can be obtained :

 * `QTSA` (issued from a granted trust service with TSA/QTST type at the timestamp production time);
 * `TSA` any other from a known trust anchor;
 * `N/A` for others.

An example of a produced Detailed Report you can see below:

.Timestamp Detailed Report
include::_samples/timestamp-detailed-report-example.adoc[]

== Available implementations of DSSDocument

DSS allows creation of different kinds of DSSDocument :

 * `InMemoryDocument` : fully loads in memory. This type of DSSDocument can be instantiated with an array of bytes, an InputStream,...
 * `FileDocument` : refers an existing File
 * `DigestDocument` : only contains pre-computed digest values for a given document. That allows a user to avoid sending the full document (detached signatures).

[source,java,indent=0]
.DigestDocument
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sources/DigestDocumentTest.java[tags=demo]
----

== Management of signature tokens

The DSS framework is able to create signatures from PKCS#11, PKCS#12 and MS CAPI. Java 6 is inherently capable of communicating with these kinds of KeyStores. To be independent of the signing media, DSS framework uses an interface named SignatureTokenConnection to manage different implementations of the signing process. The base implementation is able to sign a stream of the data in one step. That means that all the data to be signed needs to be sent to the SSCD. This is the case for MS CAPI. As to the PKCS#11 and PKCS#12, which give to the developer a finer control in the signature operation, the DSS framework implements the AsyncSignatureTokenConnection abstract class that permits to execute the digest operation and signature operation in two different threads or even two different hardwares.

This design permits also other card providers/adopters to create own implementations. For example, this can be used for a direct connection to the Smartcard through Java 6 PC/SC.

=== PKCS#11

PKCS#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.

[source,java,indent=0]
.Pkcs11SignatureToken usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/PKCS11Snippet.java[tags=demo]
----

=== PKCS#12

This standard defines a file format commonly used to store the private key and corresponding public key certificate protecting them by password.

In order to use this format with the DSS framework you have to go through the class Pkcs12SignatureToken.

[source,java,indent=0]
.Pkcs12SignatureToken usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/PKCS12Snippet.java[tags=demo]
----

=== MS CAPI

If the middleware for communicating with an SSDC provides a CSP based on MS CAPI specification, then to sign the documents you can use MSCAPISignatureToken class.

[source,java,indent=0]
.MSCAPISignatureToken usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/MSCAPISnippet.java[tags=demo]
----

=== Other Implementations

As you can see, it is easy to add another implementation of the SignatureTokenConnection, thus enabling the framework to use other API than the provided three (PKCS#11, PKCS#12 and MS CAPI). For example, it is likely that in the future PC/SC will be the preferred way of accessing a Smartcard. Although PKCS#11 is currently the most used API, DSS framework is extensible and can use PC/SC. For our design example we propose to use PC/SC to communicate with the Smartcard.

== Management of certificates sources

The validation of a certificate requires the access to some other certificates from multiple sources like trusted lists, trust store, the signature itself: certificates can be contained inside or any other source.
Within the framework, an X509 certificate is wrapped through the class:

 * `eu.europa.esig.dss.model.x509.CertificateToken`

This encapsulation helps make certificate handling more suited to the needs of the validation in the context of trust. The framework associates two internal identifiers to the certificate : the DSS Id based on the certificate binary (unique for each certificate) and the Entity Id based on its public key (common to cross-signed certificates).

Certificate tokens are grouped into sources. A certificate token can be declared in several sources. The class that models a source is called:

 * `eu.europa.esig.dss.spi.x509.CertificateSource`

This class stores all extracted/injected certificates for a specific source (Signature, OCSP Response, Trust store, Trusted-list,...). All source types are specified in the enumeration :

 * `eu.europa.esig.dss.enumerations.CertificateSourceType`

This information is used, for example, to distinguish between the certificate from a trusted source and the others. A source has one and only one type, but a certificate token can be found in multiple sources.
The DSS framework supplies some standard implementations, but also gives the possibility to implement owner solutions. Among the standard solutions you can find:

 * `eu.europa.esig.dss.spi.x509.CommonCertificateSource`

This is the superclass of almost of the certificate sources. It stores the extracted certificates and implements the common methods from the `CertificateSource` to retrieve certificate(s) by subject, public key, subject key identifier (ski),...

It also exposes the method CommonCertificateSource#addCertificate which gives the possibility to add manually any CertificateToken as a part of this source.

 * `eu.europa.esig.dss.spi.x509.CommonTrustedCertificateSource`

The CommonTrustedCertificateSource is a certificate source for trusted certificates. All added certificates are marked as trust anchors and no revocation data are required for these certificates.

 * `eu.europa.esig.dss.validation.SignatureCertificateSource`

This class and its sub-classes are used to extract and collect certificates from signatures / timestamps. It also has methods to retrieve certificates / certificate references by their origin (eg : SigningCertificate attribute, DSS Dictionary,...).

 * `eu.europa.esig.dss.spi.tsl.TrustedListsCertificateSource`

Certificates coming from the list of Trusted Lists. This class inherits of `CommonTrustedCertificateSource` and  gives the mechanism to define the set of trusted certificates (trust anchors). They are used in the validation process to decide if the prospective certificate chain has a trust anchor. See chapter <<tlValidationJob>> to get more information about trusted lists loading (e.g. EU Trusted List).

 * `eu.europa.esig.dss.spi.x509.ListCertificateSource`

This class follows the composite design pattern with a list of CertificateSources. That's used in the validation to retrieve all sources from the signatures / timestamps / revocation data / trusted lists /... It contains some methods which check over all sources to retrieve certificates or verify if a certificate is trusted.

== Management of CRL and OCSP sources

A CRL is a time-stamped list identifying revoked certificates. It is signed by a Certificate Authority (CA) and made freely available in a public repository. Each revoked certificate is identified in a CRL by its certificate serial number.

The Online Certificate Status Protocol (OCSP) is an Internet protocol used for obtaining the revocation status of an unique X.509 digital certificate.

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

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

[source,java,indent=0]
.CRLSource usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/CRLSourceSnippet.java[tags=demo]
----

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

[source,java,indent=0]
.OCSPSource usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/OCSPSourceSnippet.java[tags=demo]
----

We use these classes during the certificate validation process through "validationContext" object (based on ValidationContext class) which is a "cache" for one validation request that contains every object retrieved so far. This object in turn instantiates a "verifier" based on `RevocationDataLoadingStrategy` class whose role is to fetch revocation data by querying an OCSP or CRL source in the defined order and return the succeeded result.
In general, we can distinguish three main sources:

 * Offline sources (`OfflineRevocationSource`);
 * Online sources (`OnlineRevocationSource`);
 * Sources with the cache mechanism;
 * List of sources (`ListRevocationSource`) with a collection of several sources.

=== Repository Revocation Source

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

List of cached Revocation sources implemented in DSS:

 * `JdbcRevocationSource`
 ** `JdbcCacheCRLSource`
 ** `JdbcCacheOCSPSource`

The classes allow the following configuration :

[source,java,indent=0]
.JdbcCacheCRLSource usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/CRLSourceSnippet.java[tags=demo-cached]
----

And an example for JdbcCacheOCSPSource :

[source,java,indent=0]
.JdbcCacheOCSPSource usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/OCSPSourceSnippet.java[tags=demo-cached]
----

Be aware that you have to initialize a table before start of working with the cached revocation repository.

=== Other implementations of CRL and OCSP Sources

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

 * CRL sources
 ** `OfflineCRLSource` : This class implements the `OfflineRevocationSource` and retrieves the revocation data from extracted information. The code is common for all signature formats and CRL contents are injected by its sub-classes :
 *** `CMSCRLSource` : Extracts CRLs and CRL references from a CMS Signed Data :
 **** `CAdESCRLSource` : Sub-class of `CMSCRLSource` for a CAdES Signature;
 **** `TimestampCRLSource`: Sub-class of `CMSCRLSource` for a Timestamp token (RFC 3161);
 *** `PAdESCRLSource` : Extracts CRLs and CRL references from a PAdES signature.
 *** `XAdESCRLSource` : Extracts CRLs and CRL references from a XAdES signature.
 *** `ExternalResourcesCRLSource` : A class that can instantiate a list of certificate revocation lists from a directory where should be the individual lists.
 ** `OnlineCRLSource` : Retrieves CRL files from online sources with the CRL Distribution Points information from the certificate.
 ** `JdbcCacheCrlSource` : Implementation of the `JdbcRevocationSource`. This implementation allows storage of valid CRL entries to a defined `DataSource'` and retrieve them locally.

 * OCSP sources
 ** `OfflineOCSPSource` : This class implements the `OfflineRevocationSource` and retrieves the revocation data from extracted information. The code is common for all signature formats and OCSP responses are injected by its sub-classes :
 *** `CMSOCSPSource` : Extracts OCSP responses and OCSP references from a CMS Signed Data :
 **** `CAdESOCSPSource` : Sub-class of `CMSOCSPSource` for a CAdES Signature;
 **** `TimestampOCSPSource`: Sub-class of `CMSOCSPSource` for a Timestamp token (RFC 3161);
 *** `PAdESOCSPSource` : Extracts OCSP responses and OCSP references from a PAdES signature.
 *** `XAdESOCSPSource` : Extracts OCSP responses and OCSP references from a XAdES signature.
 **** `ExternalResourcesOCSPSource` : A class that can instantiate a list of OCSPToken from a directory where should be the individual DER Encoded X509 certificates files.
 ** `OnlineOCSPSource` : Retrieves OCSP responses from online source.
 ** `JdbcCacheOcspSource` : Implementation of the `JdbcRevocationSource`. This implementation allows storage of valid OCSP entries to a defined `DataSource` and retrieve them locally.

==== Online CRL Source

This is a representation of an Online CRL repository. This implementation will contact using HTTP protocol the CRL Responder to download the CRLs from the given URI. Note that certificate"s Authority Information Access (AIA) extension is used to find issuer's resources location like CRL file and/or Online Certificate Status Protocol (OCSP). 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 :

[source,java,indent=0]
.OnlineCRLSource usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/CRLSourceSnippet.java[tags=demo-online]
----

==== Online OCSP Source

This is a representation of an Online OCSP repository. This implementation will contact using HTTP protocol the OCSP Responder to retrieve the OCSP response. Note that certificate's Authority Information Access (AIA) extension is used to find issuer's resources location like CRT file and/or 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 :

[source,java,indent=0]
.OnlineOCSPSource usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/OCSPSourceSnippet.java[tags=demo-online]
----

[[certificateVerifier]]
== CertificateVerifier configuration

The CertificateVerifier and its implementation CommonCertificateVerifier determines how DSS accesses the external resources and how it should react in some occasions. This configuration is used in both extension and validation mode.

[source,java,indent=0]
.CertificateVerifier usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/CertificateVerifierSnippet.java[tags=demo]
----

== Trust Anchor(s) configuration

Trust anchors represent an important part in the signature creation / validation. That defines which are the trusted entities, which signatures can be trusted,... Do I trust certificates/signatures from another company / country / ... ?

Since the version 5.6, DSS allows to configure one or more trusted certificate source(s). These sources can be configured from a TrustStore (kind of keystore which only contains certificates), a trusted list and/or a list of trusted lists.

[source,java,indent=0]
.Multiple trusted certificate sources usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=multi-trusted-certificate-sources]
----

=== Trust store initialization

If you have a collection of certificates to trust, the easier way to provide them to DSS it to use a KeyStore / TrustStore.

[source,java,indent=0]
.Trust anchor initialization from a Trust Store
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=trust-store]
----

To generate the trust store, there's an utility class CreateKeyStoreApp in the dss-cookbook module.

=== Trusted List Certificate Source

In several countries, a list of Trust Service Providers (TSP) is published. This list is usually published in a machine processable format (XML) and sometimes in a human-readable format (PDF). A standard (ETSI TS 119 612) exists with the specifications for the XML format.

DSS contains all needed resources to download, parse, validate and interpret the trusted list contents. Since DSS 5.6, that's possible to configure one or more independent trusted list(s) (aka not linked to a list of trusted lists) and/or one or more list of trusted lists.

If you want to collect your trusted certificates from trusted list(s), the TrustedListsCertificateSource is required. The trusted list(s) loading can require some times (connection time-out, xml parsing, xml validation,...). This process is usually executed in background. An instance of TrustedListsCertificateSource needs to be created. That will be synchronized with the TLValidationJob.

[source,java,indent=0]
.Trusted List Certificate Source
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=trusted-list-source]
----

[[tlValidationJob]]
== TLValidationJob

The TLValidationJob allows to download, parse, validate the Trusted List(s) and Lists Of Trusted Lists (LOTL). Once the task is done, its result is stored in the TrustedListsCertificateSource. The job uses 3 different caches (download, parsing and validation) and a state-machine to be efficient.

Trusted lists are stored on the file system. That offers the possibility to run 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.

=== TLSource and LOTLSource

Several TLSources and several LOTLSources can be injected in a TLValidationJob. The only constraint is the uniqueness of the Trusted List URLs.

[source,java,indent=0]
.Multiple TLSources and multiple LOTLSources configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=job-config-sources]
----

==== Trusted List Source (TLSource)

A TLSource allows to quickly setup a trusted list configuration. The URL and the signing certificates for this TL are mandatory. Optionally, predicates / filters can be configured to retrieve only a part of the trust service providers or trust services.

[source,java,indent=0]
.TLSource configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=french-tl-source]
----

==== List Of Trusted Lists Source (LOTLSource)

A similar configuration is possible for Lists Of Trusted Lists (LOTL). That requires an URL and the possible LOTL signers. Some other parameters are possible. By default, all listed trusted lists are loaded.

[source,java,indent=0]
.LOTLSource configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=european-lotl-source]
----

=== DSSFileLoader

The FileCacheDataLoader is used to download the trusted list contents on the file-system. Two different configurations are needed. Both of them share the same folder :

 * offline refresh : disabled download from Internet and unlimited cache expiration
 * online refresh : enabled download from Internet and limited cache expiration

[source,java,indent=0]
.Offline and Online refresh configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=job-loaders]
----

=== The SynchronizationStrategy

The SynchronizationStrategy defines which are the trusted lists or list of trusted lists to be synchronized. By default, DSS synchronizes all of them. DSS don't reject any expired / invalid /... trusted lists. The content is trusted and a warning is added in a signature / certificate validation.

The strategy is configurable via the interface SynchronizationStrategy :

[source,java,indent=0]
.Example of a custom  SynchronizationStrategy
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=custom-strategy]
----

DSS provides two implementations : ExpirationAndSignatureCheckStrategy and AcceptAllStrategy (default).

=== The CacheCleaner

The CacheCleaner specifies how DSS clear the cache in case of expired URL,... 2 options are available : memory and file-system.

[source,java,indent=0]
.CacheCleaner Configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=cache-cleaner]
----

=== Alerting from TL Loading

DSS allows running of custom alerts in some situations (eg : invalid TL signature, LOTL location change,...). 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).

[source,java,indent=0]
.Examples of Alerting
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=alerting]
----

=== Executor Service

An Executor Service parameter 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.

[source,java,indent=0]
.Executor Service
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=executor-service]
----

=== Complete configuration for the European LOTL

Below, you can find a complete configuration for the European List Of Trusted Lists. The URLs need to be externalized.

[source,java,indent=0]
.European LOTL Configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/EuropeanLOTLSnippets.java[tags=complete-european-lotl-config]
----

=== The TL / LOTL refresh

The TL / LOTL loading in DSS works as below :

 * Download / parse / validate all LOTLSources from the configuration with/without pivot support (multi-threaded)
 * Analyze introduced changes and expire cache entries (new TL URLs, new signing certificates for a TL,...)
 * Create TLSources from the retrieved LOTLs
 * Combine these TLSources with independent TLSources (from the configuration)
 * Download / parse / validate all TLs (multi-threaded)
 * If alerts are configured, test if an alert needs to be launched
 * If the debug is enabled, print in the log the cache status
 * Synchronize the TrustedListCertificateSource
 * If the cache cleaner is configured, execute it
 * If the debug is enabled, print in the log the cache status

The refresh can be called with the offline or the online loader and run exactly the same code

[source,java,indent=0]
.How to refresh the Trusted List(s) and Lists of Trusted Lists
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=refresh]
----

[[KeyStore]]
==== Java Keystore Management

Generally (like in case of European LOTL) DSS downloads Trusted Lists by using the SSL protocol (for resources using HTTPS extension), that requires to have a certificate of a remote source in the Java trust store. The certificates have their own validity period and can expire. If a certificated is expired, it will be replaced on a server by a new one in order to support a secure SSL connection. The easiest way to know if your Java trust store is outdated and new certificates need to be added is to check your logs during a TLValidationJob update :

[source]
--
ERROR 14052 --- [pool-2-thread-30] e.e.e.dss.tsl.runnable.AbstractAnalysis  : Unable to process GET call for url [https://sr.riik.ee/tsl/estonian-tsl.xml]. Reason : [PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target]
--

The `SunCertPathBuilderException` means that the certificate established the secure connection is not trusted by your Java Virtual Machine. In order to add the certificate to the trust store, you need to do the following steps (the example is based on Windows OS and Google Chrome browser):

 . Open the failed URL in your browser. In our case it will be 'https://sr.riik.ee/tsl/estonian-tsl.xml' obtained from the logs.
 . Click on a lock icon next to the URL in the tab you just opened. It will open a window about the current connection status.
 . Click on 'Certificate' button to open the Certificate window.
 . Go to 'Details' tab and choose 'Copy to File...'.
 . Process the 'Certificate Export Wizard', by saving the certificate in one of '.CER' formats. Store the file in your file system. For us it will create a file 'ee.cer'.
 . Run 'Command Prompt' with administrator permissions (right click -> 'Run As Administrator').
 . Execute the following line (ensure that 'keytool' is installed) :

.Certificate import
[source,ruby]
----
keytool -import -alias newCert -file pathToCert\ee.cer -keystore pathToJavaDirectory\lib\security\cacerts -storepass changeit
----

The default password for a Java keystore is "changeit". Ensure that you have a default configuration, or use another password you have configured.

NOTE: In order to apply changes, the application using Java must be rebooted.

After these steps the `TLValidationJob` will successfully download the target Trusted List (i.e. Estonian in our example).

NOTE: This described algorithm is not only one available solution, if you have difficulties with this, you can search in the Internet for another working for you solution.

=== TLValidationJobSummary

The class TLValidationJobSummary contains all processed data about the download (time, error,...), the parsing (extracted information, parsing error,...) and the signature validation (signing certificate, signing time,...).

[source,java,indent=0]
.How to retrieve the information about the TLValidationJob process
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=tl-summary]
----

== TSP Sources

The Time Stamp Authority by creating time-stamp tokens provides independent and irrefutable proof of time for business transactions, e-documents and digital signatures. The TSA must comply with the IETF RFC 3161 specifications (cf. <<R08>>). A time-stamp is obtained by sending the digest value of the given data and digest algorithm to the Time Stamp Authority. The returned time-stamp is a signed data that contains the digest value, the identity of the TSA, and the time of stamping. This proves that the given data existed before the time of stamping.
The DSS framework proposes TSPSource interface to implement the communication with TSA. The class OnlineTSPSource is the default implementation of TSP using HTTP(S) communication layer.
The following bit of Java code illustrates how you might use this class:

[source,java,indent=0]
.OnlineTSPSource usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sources/OnlineTSPSourceTest.java[tags=demo]
----

=== Time-stamp policy

A 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. A time-stamp policy may be defined by the user of times-stamp services.

=== Composite TSP Source

Sometimes, timestamping servers may encounter interruptions (restart,...). To avoid failing signature extension, DSS allows a user to configure several TSP Sources. DSS will try source by source until getting an usable timestamp token.

[source,java,indent=0]
.Configuration of a CompositeTSPSource
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sources/CompositeTSPSourceTest.java[tags=demo]
----

== Supported algorithms

DSS 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.

NOTE: SmartCards/HSMs don't allow signing with all digest algorithms. Please refer to your SmartCard/HSM provider.

[cols="13*^"]
.Supported algorithms
|===
| | SHA-1 | SHA-224 | SHA-256 | SHA-384 | SHA-512 | SHA3-224 | SHA3-256 | SHA3-384 | SHA3-512 | MD2 | MD5 | RIPEMD160

13+|*RSA*

| XAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | | | | | icon:check-circle[role="lime"] | icon:check-circle[role="lime"]

| CAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"]

| JAdES | | | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | | | | | |

13+|*RSA-PSS*

| XAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | |

| CAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | |

| JAdES | | | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | | | | | |

13+|*ECDSA*

| XAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | | | | | | icon:check-circle[role="lime"]

| CAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | |

| JAdES | | | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | | | | | |

13+|*Ed25519*

| XAdES | | | | | | | | | | | |

| CAdES | | | | | icon:check-circle[role="lime"] | | | | | | |

13+|*DSA*

| XAdES | icon:check-circle[role="lime"] | | icon:check-circle[role="lime"] | | | | | | | | |

| CAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | |

| JAdES | | | | | | | | | | | |

13+|*HMAC*

| XAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | | | | | | icon:check-circle[role="lime"]

| CAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | |

| JAdES | | | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | | | | | |
|===

== Implementation management with ServiceLoader

DSS incorporates modules that are loaded in the run time based on the chosen configuration and the input data via a https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html[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 ServiceLoader, a file listing all the desired implementations should be created in the resource directory `META-INF/services` with a name matching the implemented interface. When merging sources (e.g. creating a Fat JAR module), the files can be lost/overwritten, and should be configured manually (all the required implementations shall be listed).

NOTE: If a DSS module(s) implementing a required interface(s) is added to your project's dependency list, the implementation shall be loaded automatically.

The following modules are provided with independent implementations:

 * <<dssUtils>>;
 * <<dssCrlParser>>;
 * <<dssPades>>.

Additionally, DSS is able to choose the required implementation for the following interfaces:

 * `DocumentValidationFactory` - checks a provided signed file's format and loads a relevant validator;
 * `SignaturePolicyValidator` - checks a signature policy file and loads a relevant validator to be able to process the detected format.

WARNING: If no appropriate available implementation is found, an exception will be thrown.

=== Document Validation Factory

This factory is used to create a required instance of a `DocumentValidator` based on the provided file's format (signature or timestamp). An implementation shall process a file format check and load the related <<signedDocumentValidator>> implementation to be used for the file's validation.

The following implementations are present in DSS:

 * CMSDocumentValidatorFactory : loads CMSDocumentValidator, used for a CAdES validation (delivered in dss-cades module);
 * XMLDocumentValidatorFactory : loads XMLDocumentValidator, used for a XAdES validation (delivered in dss-xades module);
 * PDFDocumentValidatorFactory : loads PDFDocumentValidator, used for a PAdES validation (delivered in dss-pades module);
 * JAdESDocumentValidatorFactory : loads JWSCompactDocumentValidator or JWSSerializationDocumentValidator, depending on provided JSON signature type (delivered in dss-jades module);
 * ASiCContainerWithCAdESValidatorFactory : loads ASiCContainerWithCAdESValidator (delivered in dss-asic-cades module);
 * ASiCContainerWithXAdESValidatorFactory : loads ASiCContainerWithXAdESValidator (delivered in dss-asic-xades module);
 * DetachedTimestampValidatorFactory : loads DetachedTimestampValidator, for an indepenedent timestamp validation (delivered in dss-document module).

=== Signature Policy Validator

This interface is used to validate a signature policy reference extracted from a signature. The following implementations are provided:

 * BasicASNSignaturePolicyValidator : validates policy files, which are based on ETSI TR 102 272;
 * XMLSignaturePolicyValidator : validates XML signature policies supporting transformations;
 * NonASN1SignaturePolicyValidator : validates a policy by digest computed on an original file's content;
 * ZeroHashSignaturePolicyValidator : validates a policy if "zero hash" value is defined in a signature (see <<R02>>);
 * EmptySignaturePolicyValidator : is proceeded if a policy file is not found or not accessible.

== Multi-threading

DSS 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 CertificateVerifier object. This object is responsible to provide certificates and accesses to external resources (AIA, CRL, OCSP,...). At the beginning of all operation, CertificateSources and RevocationSources are created for each signature / timestamp / revocation data. Extracted information are combined with the configured sources in the CertificateVerifier. For these reasons, integrators need to be careful about the CertificateVerifier configuration.

=== Resource sharing

The 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 not present certificates. These certificates are not necessarily trusted and may require future "modifications" like revocation data collection,...

=== Caching

In 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.

[[xmlSecurities]]
== XML Securities

Since DSS 5.7, the framework allows custom configuration of XML-related modules for enabling/disabling of XML securities (e.g. in order to use Xalan or Xerces).

WARNING: We strongly do not recommend disabling of security features and usage of deprecated dependencies. Be aware: the feature is designed only for experienced users, and all changes made in the module are at your own risk.

The configuration is available for the following classes:

 * `javax.xml.parsers.DocumentBuilderFactory` with a `DocumentBuilderFactoryBuilder` - builds a DOM document object from the obtained XML file and creates a new Document;
 * `javax.xml.transform.TransformerFactory` with a `TransformerFactoryBuilder` - loads XML templates and builds DOM objects;
 * `javax.xml.validation.SchemaFactory` with a `SchemaFactoryBuilder` - loads XML Schema;
 * `javax.xml.validation.Validator` with a `ValidatorConfigurator` - configures a validator to validate an XML document against an XML Schema.

All the classes can be configured with the following methods (example for `TransformerFactory`):

[source,java,indent=0]
.XMLSecurities configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/XMLSecuritiesConfigTest.java[tags=demo]
----

The `javax.xml.parsers.DocumentBuilderFactory`, that allows XML files parsing and creation of DOM `Document` object, can be configured with the following methods:

NOTE: Since DSS 5.9 the configuration of `javax.xml.parsers.DocumentBuilderFactory` has been moved from `DomUtils` to a new singleton class `DocumentBuilderFactoryBuilder`.

[source,java,indent=0]
.DocumentBuilderFactory configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/XMLSecuritiesConfigTest.java[tags=dbf]
----

The class `XmlDefinerUtils` is a singleton, therefore all changes performed on the instance will have an impact to all calls of the related methods.

== JAXB modules

Since the version 5.5, DSS provides the following JAXB modules with a harmonized structure :

 * `dss-policy-jaxb` - defines validation policy JAXB model
 * `dss-diagnostic-jaxb` - defines Diagnostic Data JAXB model
 * `dss-detailed-report-jaxb` - defines Detailed Report JAXB model
 * `dss-simple-report-jaxb` - defines Simple Report JAXB model
 * `dss-simple-certificate-report-jaxb` - defines Certificate Simple Report JAXB model

All modules share the same logic and have the following structure (where *** is a model name):

`*_dss-***-jaxb_*`::
	`*_src/main/java_*`:::
		`*_eu.europa.esig.dss.***_*`::::
			** `*_***.java_*` - wrapper(s) which eases the JAXB manipulation
			** `*_..._*`
			** `*_***Facade.java_*` - class which allows marshalling/unmarshalling of jaxb objects, generation of HTML/PDF content, etc.
			** `*_***XmlDefiner.java_*` - class which contains the model definition (XSD, XSLT references, ObjectFactory)
			** `*_jaxb_*` - generated on compile time
			 	*** `*_Xml***.java_*` - JAXB model
				*** `*_..._*`
	`*_src/main/resources_*`:::
		`*_xsd_*`::::
			** `*_***.xsd_*` - XML Schema (XSD) for the Detailed Report model
			** `*_binding.xml_*` - XJC instructions to generate the JAXB model from the XSD
		`*_xslt_*`::::
			** `*_html_*`
			*** 	`*_***.xslt_*` - XML Stylesheet for the HTML generation
			** `*_pdf_*`
			***	`*_***.xslt_*` - XML Stylesheet for the PDF generation

In the main classes, a `Facade` is present to quickly operate with the JAXB objects (eg: marshall, unmarshall, generate the HTML/PDF, validate the XML structure,...).

[source,java,indent=0]
.DetailedReportFacade usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[tags=demo-facade]
----

A `XmlDefiner` is also available with the access to the embedded XML Schemas (XSD), the XML Stylesheets (XSLT) to be able to generate the HTML or the PDF content (for DSS specific JAXB) and the JAXB Object Factory.

[source,java,indent=0]
.DetailedReportXmlDefiner usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[tags=demo-xml-definer]
----

=== Report stylesheets

The report modules (namely: `dss-simple-report-jaxb`, `dss-simple-certificate-report-jaxb` and `dss-detailed-report-jaxb`) contain two XSLT style sheets each for final reports generation:

 * Bootstrap 4 XSLT for HTML report;
 * PDF XSLT for PDF report.

NOTE: Since DSS 5.9 only Bootstrap 4 XSLT is provided within the framework for HTML report generation.

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

[source,java,indent=0]
.HTML report generation
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/StylesheetSnippet.java[tags=demo]
----

Otherwise, in case if you need to customize the transformer, you can create a report by using an XmlDefiner:

[source,java,indent=0]
.Custom report generation
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/StylesheetSnippet.java[tags=custom]
----

== Alerts

Since DSS 5.7 the framework includes an extended possibility to execute custom processes in case of arbitrary defined events.

The `Alert` is a basic interface used to trigger a process on a passed object.
DSS provides an `AbstractAlert` implementation of the interface with a clearly defined structure. The class must be instantiated with two attributes:

 * `AlertDetector` - used to detect an event/state of the object and trigger a process;
 * `AlertHandler` - defines a process to be executed on an object.

In its basic module, framework provides a few alerts based on a `Status`:

 * `ExceptionOnStatusAlert` - throws an `AlertException` (RuntimeException) when the status reports an issue;
 * `LogOnStatusAlert` - logs a message with the defined log level;
 * `SilentOnStatusAlert` - ignores the reported issue and does nothing.

The usage of alerts is available in the following classes:

 * <<xmlSecurities>> configurators from `dss-jaxb-parsers` module : `TransformerFactoryBuilder`, `SchemaFactoryBuilder`, `ValidatorConfigurator`;
 * <<certificateVerifier>> - to handle the unexpected situation(s) in a custom way (introduced `AlertException` to re-throw exceptions);
 * <<tlValidationJob>> - to process custom actions on change/state on loading of LOTL/TLs (see `LOTLAlert` and `TLAlert`).

== I18N (Internationalization)

Since DSS 5.6 a new module has been introduced allowing changing of a language for reports generated by DSS. The current version of the framework allows customization of text values only for a  `DetailedReport`.

A target language of the report can be set with the following code:

[source,java,indent=0]
.Language customization
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=i18n]
----

In case if no language is specified, the framework will use a default Locale obtained from OS on a running machine. If a requested language is not found, a default translation will be used.

As a default configuration DSS provides English translation.

In order to provide a custom translation, a new file must be created inside `src\main\resources` directory of your project with a name followed by one of the patterns:

`dss-messages_XX.properties` or
`dss-messages_XX_YY.properties`, where:

 * XX - an abbreviation of a target language;
 * YY - a country code.

For example, for a French language a file with a name `dss-messages_fr.properties` need to be created, or `dss-messages_fr_FR.properties` to use it only in France local.

== Additional features

=== Certificate validation

DSS offers the possibility to validate a certificate. 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 draft standard ETSI TS 119 172-4 (<<R10>>). It analyses the certificate properties (QCStatements, Certificate Policies,...) and applies possible overrules from the related trusted list ("catched" 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 the time, its status is not immutable (eg: a trust service provider lost its granted status). The eIDAS regulation (<<R12>>) clearly defines these different times in the Article 32 and related Annex I.

[source,java,indent=0]
.Validate a certificate and retrieve its qualification level
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/validate/CertificateValidationTest.java[tags=demo]
----

=== SSL Certificate validation (QWAC)

With DSS, that's also possible to validate SSL certificate against the EUMS TL and the ETSI TS 119 615 to determine if it is a Qualified certificate for WebSite Authentication (QWAC).

[source,java,indent=0]
.Validate a SSL certificate and retrieve its qualification level
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/validate/QWACValidationTest.java[tags=demo]
----

=== Extract the signed data from a signature

DSS is able to retrieve the original data from a valid signature.

[source,java,indent=0]
.Retrieve original data from a signed document
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/validate/RetrieveOriginalDocumentTest.java[tags=demo]
----

== REST and SOAP Services

DSS offers REST and SOAP web services. Additionally, we also provide a SOAP-UI project and Postman samples in the `dss-cookbook` module.

The different webservices are :

 * Signature webservices (`dss-signature-soap` / `dss-signature-rest`) and their clients : they expose methods to allow signing and extending or counter-signing a signature from a client.
 * Server-signing webservice (`dss-server-signing-soap` / `dss-server-signing-rest`) and their clients : they expose method to retrieve keys from a server (PKCS#11, PKCS#12, HSM,...) and to sign the digest on the server side.
 * Signature validation webservices (`dss-validation-soap` / `dss-validation-rest`) and their clients : they expose methods to allow signature validation, with an optional detached file and an optional validation policy.
 * Certificate validation webservices (`dss-certificate-validation-soap` / `dss-certificate-validation-rest`) and their clients : they expose methods to allow certificate validation, with an optional provided certificate chain and custom validation time.
 * Timestamp webservices (`dss-timestamp-remote-soap` / `dss-timestamp-remote-rest`) and their clients : they expose methos to allow remote timestamp creation, by providing digest value to be timestamped and a digest algorithm, used for the digets calculation.

The data structure in webservices is similar in both REST and SOAP modules.

The documentation will covers the REST calls. All the REST services present in DSS are compliant with https://www.openapis.org/[OpenAPI Specification].

=== REST signature service

This service exposes 4 methods for one or more document(s) :

[source,java,indent=0]
.Rest signature service
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/RestSignatureServiceSnippet.java[tags=demo]
----

==== 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,...) and the certificate chain.

WARNING: The parameters in getDataToSign and signDocument MUST be the same (especially the signing date).

.Request
include::_restdocs/sign-and-extend-one-document/1/http-request.adoc[]

.Response
include::_restdocs/sign-and-extend-one-document/1/http-response.adoc[]

==== Sign document

The method allows generation of the signed document with the received signature value.

WARNING: The parameters in getDataToSign and signDocument MUST be the same (especially the signing date).

.Request
include::_restdocs/sign-and-extend-one-document/2/http-request.adoc[]

.Response
include::_restdocs/sign-and-extend-one-document/2/http-response.adoc[]

==== Extend document

The method allows extension of an existing signature to a stronger level.

.Request
include::_restdocs/sign-and-extend-one-document/3/http-request.adoc[]

.Response
include::_restdocs/sign-and-extend-one-document/3/http-response.adoc[]

==== Timestamp document

The method allows timestamping of a provided document.
Available for PDF, ASiC-E and ASiC-S container formats.

.Request
include::_restdocs/timestamp-one-document/1/http-request.adoc[]

.Response
include::_restdocs/timestamp-one-document/1/http-response.adoc[]

==== 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()'.

WARNING: The parameters in getDataToBeCounterSigned and counterSignSignature MUST be the same (especially the signing date).

.Request
include::_restdocs/counter-sign-signature/1/http-request.adoc[]

.Response
include::_restdocs/counter-sign-signature/1/http-response.adoc[]

==== Counter Sign Signature

This method incorporates a created counter signature to unsigned properties of the master signature with this specified id.

WARNING: The parameters in getDataToBeCounterSigned and counterSignSignature MUST be the same (especially the signing date).

.Request
include::_restdocs/counter-sign-signature/2/http-request.adoc[]

.Response
include::_restdocs/counter-sign-signature/2/http-response.adoc[]

=== REST server signature service

This service also exposed 4 methods :

[source,java,indent=0]
.Rest server signing service
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/RestServerSigningSnippet.java[tags=demo]
----

==== Get keys

This method allows retrieving of all available keys on the server side (PKCS#11, PKCS#12, HSM,...). All keys will have an alias, a signing certificate and its chain. The alias will be used in following steps.

.Request
include::_restdocs/get-keys/1/http-request.adoc[]

.Response
include::_restdocs/get-keys/1/http-response.adoc[]

==== Get key

This method allows retrieving a key information for a given alias.

.Request
include::_restdocs/get-key/1/http-request.adoc[]

.Response
include::_restdocs/get-key/1/http-response.adoc[]

==== Sign

This method allows signing of given digests with a server side certificate.

.Request
include::_restdocs/sign-digest-document-remotely/3/http-request.adoc[]

.Response
include::_restdocs/sign-digest-document-remotely/3/http-response.adoc[]

=== REST validation service

DSS provides also a module for documents validation.

==== Validate a document

This service allows a signature validation (all formats/types) against a validation policy.

.Request
include::_restdocs/validate-doc/1/http-request.adoc[]

.Response
include::_restdocs/validate-doc/1/http-response.adoc[]

==== Retrieve original document(s)

This service returns the signed data for a given signature.

.Request
include::_restdocs/get-original-documents/1/http-request.adoc[]

.Response
include::_restdocs/get-original-documents/1/http-response.adoc[]

=== REST certificate validation service

==== Validate a certificate

This service allows a certificate validation (provided in a binary format).

.Request
include::_restdocs/validate-cert/1/http-request.adoc[]

.Response
include::_restdocs/validate-cert/1/http-response.adoc[]

=== REST remote timestamp service

==== Get Timestamp Response

This 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.

.Request
include::_restdocs/get-timestamp-response/1/http-request.adoc[]

.Response
include::_restdocs/get-timestamp-response/1/http-response.adoc[]

:toc: left
:icons: font
:icon-set: far
= Digital Signature Service
:description: Documentation of the open source project DSS (Digital Signature Service). This project allows producing/validation of Advanced electronic signatures (AdES).
:keywords: electronic signature, XAdES, CAdES, PAdES, ASiC, open source, validation
version : {dssVersion} - {docdate}

== Introduction

=== Purpose of the document

This 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.

=== Scope of the document

This document provides examples of code which allow easy handling of digital signatures. The examples are consistent with the Release {dssVersion} of DSS framework which can be downloaded via https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/DSS+releases

Three main features can be distinguished within the framework :

 * The digital signature;
 * The extension of a digital signature and;
 * The validation of a digital signature.

On a more detailed manner the following concepts and features are addressed in this document:

 * Formats of the signed documents: XML, JSON, PDF, DOC, TXT, ZIP...;
 * Packaging structures: enveloping, enveloped, detached and internally-detached;
 * Forms of digital signatures: XAdES, CAdES, PAdES, JAdES and ASiC-S/ASiC-E;
 * Profiles associated to each form of the digital signature;
 * Trust management;
 * Revocation data handling (OCSP and CRL sources);
 * Certificate chain building;
 * Signature validation and validation policy;
 * Signature qualification;
 * Validation reports (Simple, Detailed, ETSI Validation report);
 * Management of signature tokens;
 * Validation of the signing certificate;
 * Timestamp creation;
 * Timestamp validation and qualification;
 * REST and SOAP webservices.

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.

Please note that the DSS framework is still under maintenance and new features will be released in the future.

=== Abbreviations and Acronyms

[cols=2]
.Abbreviations and Acronyms
|=======================
|Code			|Description
|AdES			|Advanced Electronic Signature
|API			|Application Programming Interface
|ASiC			|Associated Signature Containers
|BB				|Building Block (CEF)
|CA				|Certificate authority
|CAdES			|CMS Advanced Electronic Signatures
|CD				|Commission Decision
|CEF			|Connecting Europe Facility
|CMS			|Cryptographic Message Syntax
|CRL			|Certificate Revocation List
|CSP			|Core Service Platform (CEF)
|CSP			|Cryptographic Service Provider
|DER			|Distinguished Encoding Rules
|DSA			|Digital Signature Algorithm - an algorithm for public-key cryptography
|DSI			|Digital Service Infrastructure (CEF)
|DSS			|Digital Signature Service
|EC				|European Commission
|eID			|Electronic Identity Card
|ESI			|Electronic Signatures and Infrastructures
|ETSI			|European Telecommunications Standards Institute
|EUPL			|European Union Public License
|FSF			|Free Software Foundation
|GS				|Generic Service (CEF)
|GUI			|Graphical User Interface
|HSM			|Hardware Security Modules
|HTTP			|Hypertext Transfer Protocol
|I18N			|Internationalization
|JAdES          |JSON Advanced Electronic Signatures
|Java EE		|Java Enterprise Edition
|JavaDoc		|JavaDoc is developed by Sun Microsystems to create API documentation in HTML format from the comments in the source code. JavaDoc is an industrial standard for documenting Java classes.
|JAXB			|Java Architecture for XML Binding
|JCA			|Java Cryptographic Architecture
|JCE			|Java Cryptography Extension
|JDBC			|Java DataBase Connectivity
|JWS			|JSON Web Signatures
|LGPL			|Lesser General Public License
|LOTL			|List of Trusted List or List of the Lists
|LSP			|Large Scale Pilot
|MIT			|Massachusetts Institute of Technology
|MOCCA			|Austrian Modular Open Citizen Card Architecture; implemented in Java
|MS / EUMS		|Member State
|MS CAPI		|Microsoft Cryptographic Application Programming Interface
|OCF			|OEBPS Container Format
|OCSP			|Online Certificate Status Protocol
|ODF			|Open Document Format
|ODT			|Open Document Text
|OEBPS			|Open eBook Publication Structure
|OID			|Object Identifier
|OOXML			|Office Open XML
|OSI			|Open Source Initiative
|OSS			|Open Source Software
|PAdES			|PDF Advanced Electronic Signatures
|PC/SC			|Personal computer/Smart Card
|PDF			|Portable Document Format
|PDFBox			|Apache PDFBox - A Java PDF Library: http://pdfbox.apache.org/
|PKCS			|Public Key Cryptographic Standards
|PKCS#12		|It defines a file format commonly used to store X.509 private key accompanying public key certificates, protected by symmetrical password
|PKIX			|Internet X.509 Public Key Infrastructure
|RSA			|Rivest Shamir Adleman - an algorithm for public-key cryptography
|SCA			|Signature Creation Application
|SCD			|Signature Creation Device
|SME			|Subject Matter Expert
|SMO			|Stakeholder Management Office (CEF)
|SOAP			|Simple Object Access Protocol
|SSCD			|Secure Signature-Creation Device
|SVA			|Signature Validation Application
|TL				|Trusted List
|TLManager		|Application for managing trusted lists.
|TSA			|Time Stamping Authority
|TSL			|Trust-service Status List
|TSP			|Time Stamp Protocol
|TSP			|Trusted Service Provider
|TST			|Time-Stamp Token
|UCF			|Universal Container Format
|URI			|Uniform Resource Identifier
|WSDL			|Web Services Description Language
|WYSIWYS		|What you see is what you sign
|XAdES			|XML Advanced Electronic Signatures
|XML			|Extensible Markup Language
|ZIP			|File format used for data compression and archiving
|=======================

=== References

[%header,cols=4]
.References
|=======================
|Ref.			|Title																			|Reference					|Version
|[[R01]]	R01	|ESI - XAdES digital signatures													|ETSI EN 319 132 part 1-2	|1.1.1
|[[R02]]	R02	|ESI - CAdES digital signatures													|ETSI EN 319 122 part 1-2	|1.1.1
|[[R03]]	R03	|ESI - PAdES digital signatures													|ETSI EN 319 142 part 1-2	|1.1.1
|[[R04]]	R04	|ESI - Associated Signature Containers (ASiC)									|ETSI EN 319 162 part 1-2	|1.1.1
|[[R05]]	R05	|ESI - JAdES digital signatures													|ETSI TS 119 182 part 1 	|draft 0.0.6
|[[R06]]	R06	|Document management - Portable document format - Part 1: PDF 1.7				|ISO 32000-1				|1
|[[R07]]	R07	|Directive 1999/93/EC of the European Parliament and of the Council of 13 December 1999 on a Community framework for electronic signatures.	|DIRECTIVE 1999/93/EC	|
|[[R08]]	R08	|Internet X.509 Public Key Infrastructure - Time-Stamp Protocol (TSP)			|RFC 3161					|
|[[R09]]	R09	|ESI - Procedures for Creation and Validation of AdES Digital Signatures		|ETSI EN 319 102-1			|1.1.1
|[[R10]]	R10	|ESI - Signature validation policy for European qualified electronic signatures/seals using trusted lists   |ETSI TS 119 172-4			|draft
|[[R11]]	R11	|ESI - Trusted Lists															|ETSI TS 119 612		    |2.1.1
|[[R12]]	R12	|eIDAS Regulation No 910/2014													|910/2014/EU			    |
|[[R13]]	R13	|ESI - Procedures for Creation and Validation of AdES Digital Signatures		|ETSI TS 119 102-2		    |1.2.1
|[[R14]]	R14	|ESI - Procedures for using and interpreting EU Member States national trusted lists						|ETSI TS 119 615		    |draft

|=======================

=== Useful links

 * https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/eSignature[CEF Digital]
 * https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/eSignature+FAQ[eSignature FAQ]
 * https://webgate.ec.europa.eu/tl-browser/#/[TL Browser]
 * https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/eSignature+validation+tests[eSignature validation tests]
 * https://ec.europa.eu/cefdigital/wiki/display/TLSO/Trusted+List+Manager+non-EU[Trusted List Manager non-EU]
 * https://github.com/esig/dss[Source code (GitHub)]
 * https://ec.europa.eu/cefdigital/code/projects/ESIG/repos/dss/browse[Source code (EC Bitbucket)]
 * https://ec.europa.eu/cefdigital/code/projects/ESIG/repos/dss-demos/browse[Source code demonstrations (EC Bitbucket)]
 * https://ec.europa.eu/cefdigital/tracker/projects/DSS/issues[Report an issue (EC Jira)]
 * https://esig-dss.atlassian.net/projects/DSS[Old Jira]

== Build instructions

The section explains the basic steps required to successfully build the DSS components.

=== DSS Core

This section explains the build and usage requirements for https://github.com/esig/dss[DSS framework].

==== Requirements

The latest version of DSS framework has the following minimal requirements:

 * Java 9 and higher (tested up to Java 15) for the build is required. For usage Java 8 is a mimimum requirement;
 * Maven 3.6 and higher;
 * Memory and Disk: see minimal requirements for the used JVM. In general the higher available is better;
 * Operating system: no specific requirements (tested on Windows and Linux).

NOTE: We strongly recommend using the latest available version of JDK, in order to have the latest security fixes and cryptographical algorithm updates.

WARNING: Before processing the build steps, please, ensure you have successfully installed Maven and JVM with a required version.

==== Adding as Maven dependency

The simplest way to include DSS to your Maven project is to add a repository into pom.xml file in the root directory of your project as following:

[source,xml]
----
<repositories>
	...

	<repository>
	  <id>cefdigital</id>
	  <name>cefdigital</name>
	  <url>https://ec.europa.eu/cefdigital/artifact/content/repositories/esignaturedss/</url>
	</repository>
</repositories>
----

After that specify a list of dependencies required for your project.

Refresh your project, in order to download the dependency and after you will be able to use all modules of DSS framework.

==== Maven build and profiles

In order to use a customized bundle of DSS, you may want to build the DSS Core framework modules.

NOTE: If you have implemented a new feature or fixed a bug issue, your pull requests are welcome at our https://github.com/esig/dss[GitHub Repository]

A simple build of the DSS Maven project can be done with the following command:

----
mvn clean install
----

NOTE: All listed commands must be executed from the project directory via a Command Line Interface (CLI).

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 custom profiles, allowing a customized behavior:

 * quick - disables unit tests and java-doc check, in order to process the build as quick as possible (takes 2-3 minutes).
 * slow-tests - executes all tests, including time-consuming unit tests.
 * owasp - runs validation of the project and using dependencies according to the https://nvd.nist.gov[National Vulnerability Database (NVD)].
 * jdk19-plus - executed automatically for JDK version 9 and higher. Provides a support of JDK 8 with newer versions.
 * spotless - used to add a licence header into project files.

WARNING: Some modules (e.g. `dss-utils`, `dss-crl-parser`, etc., see below) still have to be built completely when using the `quick` profile.

In order to run a build with a specific profile, the following command must be executed:

----
mvn clean install -P *profile_name*
----

==== Specific modules

Some modules of DSS framework have a specific behavior and need to be handled accordingly.

DSS contains a bundle of JAXB-based modules, generation Java classes in 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 represent this behavior:

 * specs-xmldsig;
 * specs-xades;
 * specs-trusted-list;
 * specs-validation-report;
 * specs-asic-manifest;
 * specs-saml-assertion;
 * dss-policy-jaxb;
 * dss-diagnostic-jaxb;
 * dss-detailed-report-jaxb;
 * dss-simple-report-jaxb;
 * dss-simple-certificate-report-jaxb.

Specific modules with JWS and JAdES specifications exist. These modules allow to validate the generated JSON against the related JSON Schema :

 * specs-jws;
 * specs-jades.

Also, as it was explained in the previous section, some modules are required to be built completely for a building of their dependent modules when using a quick profile, namely:

 * dss-utils;
 * dss-crl-parser;
 * dss-test;
 * dss-pades;
 * dss-asic-common.

The modules contain common interfaces, used in other DSS modules, as well as unit tests to ensure the equal behavior between their implementations.

==== Documentation generation

In order to generate HTML and PDF documentation for DSS project, the module `dss-cookbook` of DSS Core must be build with the following command (please, ensure that you are located in the `/dss-cookbook` directory):

----
mvn clean install -P asciidoctor
----

==== Javadoc generation

In order to generate https://ec.europa.eu/cefdigital/DSS/webapp-demo/apidocs/index.html[HTML Javadoc], you will need to build completely the DSS Core.

[[DSSDemo]]
=== DSS Demonstrations

This section explains the build and usage requirements for https://github.com/esig/dss-demonstrations[DSS Demonstration Applications].

==== Requirements

The minimal requirements to build/run DSS Demonstrations:

 * Java 8 and higher (tested up to Java 15) is required;
 * Maven 3.6 and higher (if build required);
 * Tomcat 8.5+ for Java 8 and Tomcat 9+ for Java 9 and higher (for Web-application);
 * Memory and Disk: see minimal requirements for the used JVM. In general the higher available is better;
 * Operating system: no specific requirements (tested on Windows and Linux).

==== Maven build

The build of the project can be done similarly to DSS Core framework build with the command `mvn clean install`.

Please, ensure, that you build modules what you really need. Ignore, build failures for non-required modules.

===== DSS Standalone Application

In order to build the standalone application, the following modules are required:

 * dss-mock-tsa;
 * dss-standalone-app;
 * dss-standalone-package.

If the build is successfull, you will be able to find out the following containers in the directory `/dss-standalone-app-package/target/`:

 * dss-standalone-app-package-minimal.zip - contains the application code. Requires JDK ad JavaFX installed on a target machine in order to run the application;
 * dss-standalone-app-package-complete.zip - contains the application code, as well as JDK and JavaFX library code. Can be run on a machine whithout pre-installed libraries.

In order to launch the application, you will need to extract the archive and run the file `dss-run.bat`.

===== DSS Web Application

To build the DSS Web Application the following modules are required:

 * dss-mock-tsa;
 * dss-demo-webapp;
 * dss-demo-bundle.

After a successful build, in the directory `/dss-demo-bundle/target/` you will be able to find out two containers: `dss-demo-bundle.zip` and `dss-demo-bundle.tar.gz`. Despite the container type, the content of both files is the same. After extracting the content, you will need to run the file `Webapp-Startup.bat` in order to launch the server and the file `Webapp-Shutdown.bat` to stop the server. After running the server, the web-application will be availble at the address `http://localhost:8080/`.

If during TL/LOTL loading you experience problems with some particular Trusted Lists, please refer the chapter <<KeyStore>> for a resolution.

The documentation and javadoc will be copied automatically from built DSS Core and available on the following addresses respectively:

 * HTML documentation : `http://localhost:8080/doc/dss-documentation.html`;
 * PDF documentation :  `http://localhost:8080/doc/dss-documentation.pdf`;
 * Javadoc : `http://localhost:8080/apidocs/index.html`.

In order to build a bundle for JDK 15, the following profile can be used from `dss-demo-bundle` module:

----
mvn clean install -P java15
----

This will create a bundle with Tomcat 9.

===== Integration tests

The `dss-demo-webapp` module provides a collection of integration tests in order to test the behavior of REST/SOAP web-services. In order to run the tests, a web-server with DSS Web Application shall be launched and the following profile need to be executed from the module:

----
mvn clean install -P run-integration-test
----

== General framework structure

DSS framework is a multi-modules project which can be built with Maven.

=== Maven modules

==== Shared modules

dss-enumerations:: Contains a list of all used enumerations in the DSS project.
dss-alerts:: Allows configuration of triggers and handers for arbitrary defined events.
dss-jaxb-parsers:: Contains a list of all classes used to transform JAXB objects/strings to Java objects and vice versa.

==== JAXB model modules

specs-xmldsig:: W3C XSD schema for signatures http://www.w3.org/2000/09/xmldsig
specs-xades:: ETSI EN 319 132-1 XSD schema for XAdES.
specs-trusted-list:: ETSI TS 119 612 XSD schema for parsing Trusted Lists.
specs-validation-report:: ETSI TS 119 102-2 XSD schema for the Validation report.
specs-asic-manifest:: ETSI EN 319 162 schema for ASiCManifest.
specs-saml-assertion:: OASIS schema for SAML Assertions.

'''
dss-policy-jaxb:: JAXB model of the validation policy.
dss-diagnostic-jaxb:: JAXB model of the diagnostic data.
dss-detailed-report-jaxb:: JAXB model of the detailed report.
dss-simple-report-jaxb:: JAXB model of the simple report.
dss-simple-certificate-report-jaxb:: JAXB model of the simple report for certificates.

==== JSON validation modules

specs-jws:: JSON Schemas based on the RFC 7515 specifications (not official)
specs-jades:: ETSI TS 119 182-1 v.0.0.6 JSON Schemas for JAdES

==== Utils modules

dss-utils:: API with utility methods for String, Collection, I/O,...
dss-utils-apache-commons:: Implementation of dss-utils with Apache Commons libraries.
dss-utils-google-guava:: Implementation of dss-utils with Google Guava.

==== i18n

dss-i18n:: a module allowing internationalization of generated reports.

==== Core modules

dss-model:: Data model used in almost every module.
dss-crl-parser:: API to validate CRLs and retrieve revocation data
dss-crl-parser-stream:: Implementation of dss-crl-parser which streams the CRL.
dss-crl-parser-x509crl:: Implementation of dss-crl-parser which uses the java object X509CRL.
dss-spi:: Interfaces, util classes to manipulate ASN1, compute digests,...
dss-document:: Common module to sign and validate document. This module doen't contain any implementation.
dss-service:: Implementations to communicate with online resources (TSP, CRL, OCSP).
dss-token:: Token definitions and implementations for MS CAPI, PKCS#11, PKCS#12.
validation-policy:: Business of the signature's validation (ETSI EN 319 102 / TS 119 172-4).
dss-xades:: Implementation of the XAdES signature, extension and validation.
dss-cades:: Implementation of the CAdES signature, extension and validation.
dss-jades:: Implementation of the JAdES signature, extension and validation.
dss-pades:: Common code which is shared between dss-pades-pdfbox and dss-pades-openpdf.
dss-pades-pdfbox:: Implementation of the PAdES signature, extension and validation with https://pdfbox.apache.org/[PDFBox].
dss-pades-openpdf:: Implementation of the PAdES signature, extension and validation with https://github.com/LibrePDF/OpenPDF[OpenPDF (fork of iText)].
dss-asic-common:: Common code which is shared between dss-asic-xades and dss-asic-cades.
dss-asic-cades:: Implementation of the ASiC-S and ASiC-E signature, extension and validation based on CAdES signatures.
dss-asic-xades:: Implementation of the ASiC-S and ASiC-E signature, extension and validation based on XAdES signatures.
dss-tsl-validation:: Module which allows loading / parsing / validating of LOTL and TSLs.

==== WebServices

dss-common-remote-dto:: Common classes between all remote services (REST and SOAP).
dss-common-remote-converter:: Classes which convert the DTO to DSS Objects.

'''
dss-signature-dto:: Data Transfer Objects used for signature creation/extension (REST and SOAP).
dss-signature-remote:: Common classes between dss-signature-rest and dss-signature-soap.
dss-signature-rest-client:: Client for the REST webservices.
dss-signature-rest:: REST webservices to sign (getDataToSign, signDocument methods), counter-sign and extend a signature.
dss-signature-soap-client:: Client for the SOAP webservices.
dss-signature-soap:: SOAP webservices to sign (getDataToSign, signDocument methods), counter-sign and extend a signature.

'''
dss-server-signing-dto:: Data Transfer Objects used for the server signing module (REST and SOAP).
dss-server-signing-common:: Common classes for server signing.
dss-server-signing-rest:: REST webservice for server signing.
dss-server-signing-rest-client:: REST client for server signing (sign method).
dss-server-signing-soap:: SOAP webservice for server signing.
dss-server-signing-soap-client:: SOAP client for server signing (sign method).

'''
dss-validation-dto:: Data Transfer Objects used for signature validation (REST and SOAP).
dss-validation-common:: Common classes between dss-validation-rest and dss-validation-soap.
dss-validation-rest-client:: Client for the REST signature-validation webservices.
dss-validation-soap-client:: Client for the SOAP signature-validation webservices.
dss-validation-rest:: REST webservices to validate a signature.
dss-validation-soap:: SOAP webservices to validate a signature.

'''
dss-certificate-validation-dto:: Data Transfer Objects used for certificate validation (REST and SOAP).
dss-certificate-validation-common:: Common classes between dss-certificate-validation-rest and dss-certificate-validation-soap.
dss-certificate-validation-rest-client:: Client for the REST certificate-validation webservice.
dss-certificate-validation-soap-client:: Client for the SOAP certificate-validation webservice.
dss-certificate-validation-rest:: REST webservice to validate a certificate.
dss-certificate-validation-soap:: SOAP webservice to validate a certificate.

'''
dss-timestamp-dto:: Data Transfer Objects used for timestamp creation.
dss-timestamp-remote-common:: Common classes between dss-timestamp-remote-rest and dss-timestamp-remote-soap.
dss-timestamp-remote-rest-client:: Client for the REST timestamp webservice.
dss-timestamp-remote-soap-client:: Client for the SOAP timestamp webservice.
dss-timestamp-remote-rest:: REST webservice to create a timestamp.
dss-timestamp-remote-soap:: SOAP webservice to create a timestamp.

==== Other modules

dss-test:: Mocks and util classes for unit tests.
dss-cookbook:: Samples and documentation of DSS used to generate this documentation.

[[dssUtils]]
=== DSS Utils

The module dss-utils offers an interface with utility methods to operate on String, Collection, I/O,... DSS framework provides two different implementations with the same behaviour :

 * dss-utils-apache-commons : this module uses Apache Commons libraries (commons-lang3, commons-collection4, commons-io and commons-codec).
 * dss-utils-google-guava : this module only requires Google Guava (recommended on Android).

If your integration include dss-utils, you will need to select an implementation.

[[dssCrlParser]]
=== DSS CRL Parser

DSS contains two ways to parse/validate a CRL and to retrieve revocation data. An alternative to the X509CRL java object was developed to face memory issues in case of large CRLs. The X509CRL object fully loads the CRL in memory and can cause OutOfMemoryError.

 * dss-crl-parser-x509crl : this module uses the X509CRL java object.
 * dss-crl-parser-streams : this module offers an alternative with a CRL streaming (experimental).

If your integration require dss-crl-parser, you will need to choose your implementation.

[[dssPades]]
=== DSS PAdES

Since the version 5.4, DSS allows generation/extension/validation PAdES signatures with two different frameworks : PDFBox and OpenPDF (fork of iText). The dss-pades module only contains the common code and requires an underlying implementation :

 * dss-pades-pdfbox : Supports drawing of custom text, images, as well as text+image, in a signature field.
 * dss-pades-openpdf : Supports drawing of custom text OR images in a signature field.

DSS permits to override the visible signature generation with these interfaces :

 * eu.europa.esig.dss.pdf.IPdfObjFactory
 * eu.europa.esig.dss.pdf.visible.SignatureDrawerFactory (selects the SignatureDrawer depending on the SignatureImageParameters content)
 * eu.europa.esig.dss.pdf.visible.SignatureDrawer

A new instance of the IPdfObjFactory can be created with its own SignatureDrawerFactory and injected in the padesService.setPdfObjFactory(IPdfObjFactory). By default, DSS uses an instance of ServiceLoaderPdfObjFactory. This instance checks for any registered implementation in the classpath with the ServiceLoader (potentially a service from dss-pades-pdfbox, dss-pades-openpdf or your own(s)).

==== DSS PDFBox

Since the version 5.5, DSS allows switching between two implementations of the framework PDFBox : default (original) and native.

 * Default Drawer : The original drawer implemented on the PDFBox framework, supports displaying of custom text, images, text+image combination in a signature field. The implementation does not include the provided custom text to the inner PDF structure, instead of it, the drawer creates an image representation of the provided text, which is added to the signature field (i.e. the text is not selectable and not searchable).
 * Native Drawer : Since the version 5.5, DSS includes a new implementation of PDFBox Drawer, that allows a user to add a real custom text, image or combination of text and image to a visible signature field. The native implementation embeds the provided custom text to the inner PDF structure, that makes the text selectable and searchable, and also clearer and smoother in comparison with the original implementation.

By default, DSS uses "Default Drawer" as the PDFBox implementation. In order to switch the implementation, that allowed in runtime, you have to set a new instance for PdfObjFactory as following:

[source,java,indent=0]
.Runtime PDF Object Factory changing
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java[tags=custom-factory]
----

== Available demonstrations

With the framework, some demonstrations are provided.

[horizontal]
dss-mock-tsa:: The class which generate false timestamps from a self-signed certificate.
sscd-mocca-adapter:: Adapter for the MOCCA connection.
dss-standalone-app:: Standalone application which allows signing a document with different formats and tokens (JavaFX).
dss-standalone-app-package:: Packaging module for dss-standalone-app.
dss-demo-webapp:: Demonstration web application which presents a part of the DSS possibilities.
dss-demo-bundle:: Packaging module for dss-demo-webapp.

WARNING: The demonstrations use a simulated timestamp service (Mock) so that is not recommended for a production usage.

The requirements and build instructions for DSS demonstrations can be found in the chapter <<DSSDemo>>.

== Signature's profile simplification

The different formats of the digital signature make possible to cover a wide range of real live cases of use of this technique. Thus we distinguish the following formats: XAdES, CAdES, PAdES, JAdES and ASIC. To each one of them a specific standard is dedicated. The wide variety of options, settings and versions of the standards makes their interoperability very difficult. This is the main reason for which new standards commonly called "baseline profiles" were published. Their goal is to limit the number of options and variants thereby making possible a better interoperability between different actors.

In general can be said that for each format of the digital signature the number of security levels defined in the new standards has been reduced. Below is a comparative table of old and new levels for each format of the signature:

[%header,cols=7*^.^]
.Signature supported profiles
|=======================
2+|XAdES				       2+|CAdES				             2+|PAdES                           |JAdES
|*STANDARD* 	   |*BASELINE*	 |*STANDARD*       |*BASELINE* 	   |*STANDARD*	    |*BASELINE*     |*BASELINE*
|XAdES-BES 		.2+|XAdES-B	     |CAdES-BES 	.2+|CAdES-B 	   |PAdES-BES    .2+|PAdES-B     .2+|JAdES-B
|XAdES-EPES					     |CAdES-EPES	 			       |PAdES-EPES
|XAdES-T 		   |XAdES-T      |CAdES-T 	       |CAdES-T   	   |PAdES-T 	    |PAdES-T        |JAdES-T
|XAdES-XL 		   |XAdES-LT  	 |CAdES-XL         |CAdES-LT 	   |PAdES-XL 	    |PAdES-LT       |JAdES-LT
|XAdES-A 		   |XAdES-LTA	 |CAdES-A 	       |CAdES-LTA 	   |PAdES-LTV 	    |PAdES-LTA      |JAdES-LTA
|=======================

Note that the new version (v4) of the DSS framework is compatible with the baseline profiles, it is no longer possible to use the standard profiles for signing purpose. The validation of the signature still takes into account the old profiles.

[.landscape]
<<<

=== Signature profile guide

Below 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.

.File formats and Signature types conformance
[%header,cols="12*^.^"]
|===
  3+|Signature profiles                                        |XML                            |JSON                           |PDF                            |Binary                         |Digest                         |Multiple files                 |Multiple signatures            |Counter signature              |Stand-alone timestamp
.10+|XAdES   .4+|Enveloping  |Base64 encoded                   |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |Embed XML                        |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |XML only                       |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |Manifest                         |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |Canonicalization                 |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |XML only                       |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
             .4+|Enveloped   |enveloped transformation         |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |based on XPath                   |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |based on Filter2                 |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |Canonicalization                 |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |XML only                       |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
              2+|Detached                                      |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
              2+|Internally Detached                           |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |XML only                       |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
.2+|CAdES     2+|Enveloping                                    |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
              2+|Detached                                      |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
|PAdES        2+|Enveloped                                     |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"]
.6+|JAdES    .3+|Enveloping  |Compact Serialization            |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]
                             |Flattened JSON Serialization     |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |JSON Serialization               |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
             .3+|Detached    |Compact Serialization            |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |SigD only                      |icon:times-circle[role="red"]  |icon:times-circle[role="red"]  |icon:times-circle[role="red"]
                             |Flattened JSON Serialization     |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |SigD only                      |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
                             |JSON Serialization               |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |SigD only                      |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]
.2+|ASiC        |ASiCS       |CAdES / XAdES                    |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"]
                |ASiCE       |CAdES / XAdES                    |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:times-circle[role="red"]  |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"] |icon:check-circle[role="lime"]
|===

[.portrait]
<<<

== The XML Signature (XAdES)

The 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:

 * XAdES Specifications (cf. <<R01>>)

After reading these documents, it is clear that:

 * To electronically sign a document, a signing certificate (that proves the signer's identity) and the access to its associated private key is needed.
 * To electronically validate a signed document the signer's certificate containing the public key is needed. To give a more colourful example: when a digitally signed document is sent to a given person or organization in order to be validated, the certificate with the public key used to create the signature must also be provided.

===	XAdES Profiles

The new ETSI standard defines four conformance levels to address the growing need to protect the validity of the signature in time. Henceforth to denote the level of the signature the word "level" will be used. Follows the list of levels defined in the standard:

 * XAdES-BASELINE-*B*: _Basic Electronic Signature_
The lowest and simplest version just containing the SignedInfo, SignatureValue, KeyInfo and SignedProperties. This level combines the old -BES and -EPES levels.
This form extends the definition of an electronic signature to conform to the identified signature policy.
 * XAdES-BASELINE-*T*: _Signature with a timestamp_
A timestamp regarding the time of signing is added to protect against repudiation.
 * XAdES-BASELINE-*LT*: _Signature with Long Term Data_
Certificates and revocation data are embedded to allow verification in future even if their original source is not available. This level is equivalent to the old -XL level.
 * XAdES-BASELINE-*LTA*: _Signature with Long Term Data and Archive timestamp_
By using periodical timestamping (e.g. each year) compromising is prevented which could be caused by weakening previous signatures during a long-time storage period. This level is equivalent to the old -A level.

NOTE: Old levels: -BES, -EPES, -C, -X, -XL, -A are not supported any more when signing.

==== XAdES-BASELINE-B

To start, let's take a simple XML document:

[[xml_example.xml]]
[source,xml]
.xml_example.xml
----
<?xml version="1.0"?>
<test>Hello World !</test>
----

Since this is an XML document, we will use the XAdES signature and more particularly XAdES-BASELINE-B level, which is the lowest level of protection: just satisfying Directive (cf. <<R07>>) legal requirements for advanced signature. The normal process of signing wants to sign first with the level -B or level-T, and then later when it becomes necessary to complete the signature with superior levels. However, the framework allows signing directly with any level.
When 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. So, we need to define the packaging of the signature, namely ENVELOPED, ENVELOPING, DETACHED or INTERNALLY-DETACHED. More information about supported reference transformations for each signature packaging (except 'Detached'), can be found in the section <<Reference Transformations>>

 * *ENVELOPED :* when the signature applies to data that surround the rest of the document;
 * *ENVELOPING :* when the signed data form a sub-element of the signature itself;
 ** Base64 encoded binaries;
 ** Embed XML object(s);
 ** Embed https://www.w3.org/TR/xmldsig-core/#sec-o-Manifest[Manifest] object(s).
 * *DETACHED :* when the signature relates to the external resource(s) separated from it.
 * *INTERNALLY-DETACHED :* when the signature and the related signed data are both included in a parent element (only XML).

For our example, we will use ENVELOPED packaging.

The DSS framework uses 3 atomic steps to sign a document :

. Compute the digest to be signed;
. Sign the digest;
. Sign the document (add the signed digest).

The DSS fully manages the steps 1 and 3. We need to specify how to do the signature operation. DSS offers some implementations in the dss-token module

To write our Java code, we still need to specify the type of KeyStore to use for signing our document, more simply, where the private key can be found. In the package "eu.europa.esig.dss.token", we can choose between different connection tokens :

 * *Pkcs11SignatureToken :* allows communicating with SmartCards with the PKCS#11 interface. It requires some installed drivers (dll, sso,...) .
 * *Pkcs12SignatureToken :* allows signing with a PKC#12 keystore (.p12 file).
 * *MSCAPISignatureToken :* handles the signature with MS CAPI (the Microsoft interface to communicate with SmartCards).
 * *JKSSignatureToken :* allows signing with a Java Key Store (.jks file).

NOTE: The DSS also provides the support for MOCCA framework to communicate with the Smartcard with PC/SC, but it involves the installation of the MOCCA and IAIK libraries.

To know more about the use of the different signature tokens, please consult "Management of Signature Tokens" chapter.

In our example the class: "Pkcs12SignatureToken" will be used. A file in PKCS#12 format must be provided to the constructor of the class. It contains an X.509 private key accompanying the public key certificate and protected by symmetrical password. The certification chain can also be included in this file. It is possible to generate dummy certificates and their chains with OpenSSL. Please visit http://www.openssl.org/ for more details.

This is the complete code that allows you to sign our XML document.

[source,java,indent=0]
.Create a XAdES signature
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBTest.java[tags=demo]
----

What you may notice is that to sign a document we need to:

 * Create an object based on SignatureParameters class. The number of specified parameters depends on the type of signature. Generally, the number of specified parameters depends on the profile of signature. This object also defines some default parameters.
 * Choose the profile, packaging, signature digest algorithm.
 * Indicate the private key entry to be used.
 * Instantiate the adequate signature service.
 * Carry out the signature process.

The encryption algorithm is determined by the private key and therefore cannot be compelled by the setter of the signature parameters object. It will 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. See clause "Signing process" for more information.
In the case where the private key entry object is not available, it is possible to choose the signing certificate and its certificate chain as in the following example:

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=demoCertificateChain]
----

Integrating the certificate chain in the signature simplifies the build of a prospective certificate chain during the validation process.

By default the framework uses the current date time to set the signing date, but in the case where it is necessary to indicate the different time it is possible to use the setter "setSigningDate(Date)" as in the example:

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=demoSigningDate]
----

When the specific service is instantiated a certificate verifier must be set. This object is used to provide four different sources of information:

 * the source of trusted certificates (based on the trusted list(s) specific to the context);
 * the source of intermediate certificates used to build the certificate chain till the trust anchor. This source is only needed when these certificates are not included in the signature itself;
 * the source of OCSP;
 * the source of CRL.

In the current implementation this object is only used when profile -LT or -LTA are created.

===== Signing process

Once the parameters of the signature were identified the service object itself must be created. The service used will depend on the type of document to sign. In our case it is an XML file, so we will instantiate a XAdES service. The process of signing takes place in three stages. The first is the `getDataToSign()` method call, passing as a parameter the document to be signed and the previously selected settings. This step returns the data which is going to be digested and encrypted. In our case it corresponds to the SignedInfo XMLDSig element.

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=demoSigningProcessGetDataToSign]
----

The next step is a call to the function `sign()` which is invoked on the object token representing the KeyStore and not on the service. This method takes three parameters. The first is the array of bytes that must be signed. It is obtained by the previous method invocation. The second is the algorithm used to create the digest. You have the choice between SHA1, SHA256, and SHA512 (this list is not exhaustive). And the last one is the private key entry.

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=demoSigningProcessSign]
----

The 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 the method `signDocument()` on the service. We must pass to it three parameters: again the document to sign, the signature parameters and the value of the signature obtained in the previous step.

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.

When the breakdown of this process is not necessary, than a simple call to only one method can be done as in the following example:

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=demoSigningProcessSignDocument]
----

===== Additional attributes

For this type (XAdES-BASELINE-B) of signature it is possible to identify some additional attributes.

[[SignXmlXadesBPropertiesTest.java]]
[source,java,indent=0]
.XAdES signature with additional signed attributes
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBPropertiesTest.java[tags=demo]
----

In XAdES format the following types of a Content Timestamp can be used:

 * AllDataObjectsTimeStamp - each time-stamp token within this property covers the full set of references defined in the Signature's SignedInfo element, excluding references of type "SignedProperties".
 * IndividualDataObjectsTimeStamp - each time-stamp token within this property covers selected signed data objects.

The code above produces the following signature :

.XAdES signature example
include::_samples/xades-b-properties.adoc[]

==== XAdES-BASELINE-T

XAdES-BASELINE-T is a signature for which there exists a trusted time associated to the signature. It provides the initial steps towards providing long term validity and more specifically it provides a protection against repudiation. This extension of the signature can be created as well during the generation process as validation process. However, the case when these validation data are not added during the generation process should no longer occur. The XAdES-BASELINE-T trusted time indications must be created before the signing certificate has been revoked or expired and close to the time that the XAdES signature was produced. The XAdES-BASELINE-T form must be built on a XAdES-BASELINE-B form. The DSS framework allows extending the old -BES and -EPES profiles to the new BASELINE-T profile, indeed there is no difference in the structure of the signature.

To implement this profile of signature you must indicate to the service the TSA source, which delivers from each Timestamp Request a Timestamp Response (RFC 3161 (cf. <<R08>>)) containing tokens. Below is the source code that creates a XAdES-BASELINE-T signature. For our example, we will use the Belgian provider and an instance of OnlineTSPSource (see "TSP Sources" chapter for more details).

[source,java,indent=0]
.Create a XAdES-Baseline-T with an OnlineTSPSource
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesTWithOnlineSourceTest.java[tags=demo]
----

If the timestamp source is not set a NullPointerException is thrown.

The SignatureTimeStamp mandated by the XAdES-T form appears as an unsigned property within the QualifyingProperties:

.XAdES Signature Timestamp
include::_samples/xades-signature-timestamp.adoc[]

==== XAdES-BASELINE-LT

This level has to prove that the certification path was valid, at the time of the validation of the signature, up to a trust point according to the naming constraints and the certificate policy constraints from the "Signature Validation Policy". It will add to the signature the CertificateValues and RevocationValues unsigned properties. The CertificateValues element contains the full set of certificates that have been used to validate the electronic signature, including the signer's certificate. However, it is not necessary to include one of those certificates, if it is already present in the ds:KeyInfo element of the signature. This is like DSS framework behaves. 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 CertificateVerifier must be passed to the service. The implementer must set some of its properties (e.g. a source of trusted certificates). The code below shows how to use the default parameters with this object. Please refer to "The Signature Validation" chapter to have the further information. It also includes an example of how to implement this level of signature:

[[SignXmlXadesLTTest.java]]
[source,java,indent=0]
.SignXmlXadesLTTest.java
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesLTTest.java[tags=demo]
----

The following XML segment will be added to the signature qualified and unsigned properties:

.Validation data values
include::_samples/xades-revocation-data.adoc[]

NOTE: The use of online sources can significantly increase the execution time of the signing process. For testing purpose you can create your own source of data.

In last example the CommonsHttpDataLoader is used to provide the communication layer for HTTP protocol. Each source which need to go through the network to retrieve data need to have this component set.

==== XAdES-BASELINE-LTA

When the cryptographic data becomes weak and the cryptographic functions become vulnerable the auditor should take steps to maintain the validity of the signature. The XAdES-BASELINE-A form uses a simple approach called "archive validation data". It adds additional time-stamps for archiving signatures in a way that they are still protected, but also to be able to prove that the signatures were validated at the time when the used cryptographic algorithms were considered safe. The time-stamping process may be repeated every time the protection used becomes weak. Each time-stamp needs to be affixed before either the signing key or the algorithms used by the TSA are no longer secure. XAdES-A form adds the ArchiveTimestamp element within the UnsignedSignatureProperties and may contain several ArchiveTimestamp elements.

Below is an example of the implementation of this level of signature (but in practice, we will rather extend the signature to this level when there is a risk that the cryptographic functions become vulnerable or when one of certificates arrives to its expiration date):

[source,java,indent=0]
.Signature level setting
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=demoSignatureLevel]
----

The following XML segment will be added to the signature qualified and unsigned properties:

.XAdES Archive Timestamp
include::_samples/xades-archive-timestamp.adoc[]

=== Versions support

DSS supports the following XAdES formats :

[cols="5*^"]
.Supported XAdES versions
|===
| | B-level | T-level | LT-level | LTA-level

| XAdES 1.1.1 | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:times-circle[role="red"]

| XAdES 1.2.2 | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:times-circle[role="red"]

| XAdES 1.3.2 | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"]

| XAdES 1.4.1  4+| The format contains qualifying properties for XAdES 1.3.2 LTA level
|===

The XAdES Profile, as well as a customizable prefixes can be set with following methods :

[source,java,indent=0]
.XAdES formats and prefixes
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[tags=demoPrefixes]
----

=== Reference Transformations

In case of 'Enveloping', 'Enveloped' and 'Internally Detached' signatures, it is possible to apply custom transformations for signing references in order to compute proper digest result. Example of a definition reference transformations, you can find below:

[[SignXmlXadesBWithTransformsTest.java]]
[source,java,indent=0]
.Custom transformations definition
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[tags=demo]
----

Current version of DSS supports the following transformations:

 * Enveloped - removes the current `Signature` element from the digest calculation of the reference.

WARNING: Enveloped Signature Transform does not support parallel signatures!

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[tags=demoEnvelopedTransform]
----

 * Canonicalization - any canonicalization algorithm that can be used for 'CanonicalizationMethod' can be used as a transform:

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[tags=demoCanonicalizationTransform]
----

 * Base64 - the transform is used if application needs to sign a RAW data (binaries, images, audio or other formats). The 'Base64 Transform' is not compatible with following signature parameters:

 ** Reference contains more than one transform (must be a sole element of the reference transforms);
 ** setEmbedXML(true) - embedded setting cannot be used;
 ** setManifestSignature(true) - As is apparent from the previous point, Manifest cannot be used with the Base64 Transform as well since it also must be embedded to the signature.

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[tags=demoBase64Transform]
----

 * XPath - allows signing a custom nodes in a signature or embedded document. DSS contains an additional class `XPathEnvelopedSignatureTransform` allowing to exclude signatures from the digested content (used for Enveloped signatures by default). Additional information about the 'XPath Transform' can be found https://www.w3.org/TR/xpath20/[by the link].

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[tags=demoEnvelopedXPathTransform]
----

 * XPath-2-Filter - an alternative to 'XPath Transform'. Additional information about the 'XPath2Filter Transform' can be found https://www.w3.org/TR/xmldsig-filter2/[by the link]. DSS contains an additional class `XPath2FilterEnvelopedSignatureTransform` allowing to exclude signatures from the digest calculation.

NOTE: Since DSS 5.7 the XPath-2-Filter transform is used by default for ENVELOPED signature packaging.

[source,java,indent=0]
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[tags=demoEnvelopedXPath2FilterTransform]
----

 * XSLT Transform - This transform requires a 'org.w3.dom.Document' as an input, compatible with the normative https://www.w3.org/TR/xslt-30/[XSLT Specification]. Must be a sole transform.

NOTE: All transformations, except Base64, can be applied only to XML objects.

=== Multiple signatures

In everyday life, there are many examples where it is necessary to have multiple signatures covering the same document, such as a contract to purchase a vehicle. Independent signatures are parallel signatures where the ordering of the signatures is not important. The computation of these signatures is performed on exactly the same input but using different private keys.

=== XAdES and specific schema version

Some signatures may have been created with an older version of XAdES standard using different schema definition. To take into account the validation of such signatures the interface eu.europa.esig.dss.xades.definition.XAdESPaths was created. This interface allows to provide the different needed XPath expressions which are used to explore the elements of the signature. The DSS framework proposes 3 implementations :

 * XAdES132Paths (XAdES 1.3.2 / 1.4.1)
 * XAdES122Paths (XAdES 1.2.2)
 * XAdES111Paths (XAdES 1.1.1)

By default, all XAdES are supported and DSS loads/parses all versions of XAdES. That's possible to restrict to only one version of XAdES with the following code :

[source,java,indent=0]
.Customize the supported XAdES version(s) at the validation
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/validate/XAdES132OnlyTest.java[tags=demo]
----

=== Sign a Trusted List

The standard ETSI TS 119 612 specifies in its annex B the XML structure and the format of the signature (XAdES, enveloped signature, transformation, canonicalization, etc.). With the class `TrustedListSignatureParametersBuilder`, DSS is able to pre-configure the signature parameters to comply with the specifications and simplify the signature creation.

[source,java,indent=0]
.Sign a Trusted List with the TrustedListSignatureParametersBuilder
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignTrustedListTest.java[tags=demo]
----

== Signature Extension

The -B level contains immutable signed properties. Once this level is created, these properties cannot be changed.

The levels -T/-LT/-LTA add unsigned properties to the signature. This means that the properties of these levels could be added afterwards to any AdES signature. This addition helps to make the signature more resistant to cryptographic attacks on a longer period of time. The extension of the signature is incremental, i.e. when you want to extend the signature to the level -LT the lower level (-T) will also be added. The whole extension process is implemented by reusing components from signature production. To extend a signature we proceed in the same way as in the case of a signature, except that you have to call the function "extendDocument" instead of the "sign" function. Note that when the document is signed with several signatures then they are all extended.

=== BASELINE-T

The AdES-BASELINE-T trusted time indications have to be created before a certificate has been revoked or expired and close to the time that the AdES signature was produced. It provides a protection against repudiation. The framework adds the timestamp only if there is no timestamp or there is one but the creation of a new extension of the level-T is deliberate (using another TSA). It is not possible to extend a signature which already incorporates higher level as -LT or -LTA. In the theory it would be possible to add another -T level when the signature has already reached level -LT but the framework prevents this operation. Note that if the signed document contains multiple signatures, then all the signatures will be extended to level -T. It is also possible to sign a document directly at level -T.

Here is an example of creating an extension of type T:

[source,java,indent=0]
.Extend a XAdES signature
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/ExtendSignXmlXadesBToTTest.java[tags=demo]
----

Here is the result of adding a new extension of type-T to an already existing -T level signature:

.XAdES Unsigned Signature Properties
include::_samples/xades-extend-t-to-t.adoc[]

=== BASELINE-LT and -LTA

For these types of extensions, the procedure to follow is the same as the case of the extension of type T. Please refer to the chapter XAdES Profiles to know specific parameters for each level of signature and which must be positioned.

[[signatureValidation]]
== Signature Validation

Generally and following ETSI standard, the validation process of an electronic signature must provide one of these three following statuses: TOTAL-FAILED, TOTAL-PASSED or INDETERMINATE. A TOTAL-PASSED response indicates that the signature has passed verification and it complies with the signature validation policy. A TOTAL_FAILED response indicates that either the signature format is incorrect or that the digital signature value fails the verification. An INDETERMINATE validation response indicates that the format and digital signature verifications have not failed but there is an insufficient information to determine if the electronic signature is valid. For each of the validation checks, 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.

===	Validation Process

Since version 4.7 of the DSS framework the validation process is based on the latest ETSI standard <<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 dependences between these 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.

.Signature Validation Process
image::sig_validation_process.jpg[]

Note that the current version of the framework during the validation process does not indicate what part of a document was signed. However, in a case of XAdES signature XPath transformations presented in the signature will be applied, in the 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 the different detail levels concerning the validation result. They provide four kinds of visions for the validation process: macroscopic, microscopic, input data and ETSI Validation report conformant with the standard <<R09>>. For more information about these reports, please refer to "Simple Report" chapter.

Below is the simplest example of the validation of the signature of a document. The first thing to do is instantiating an object named validator, which orchestrates the verification of the different rules. To perform this it is necessary to invoke a static method fromDocument() on the abstract class `SignedDocumentValidator`. This method returns the object in question whose type is chosen dynamically based on the type of source document.

The next step is to create an object that will check the status of a certificate using the Trusted List model (see "Trusted Lists of Certification Service Provider" for more information). In order to achieve this, an instance of a `CertificateVerifier` must be created with a defined source of trusted certificates. In our example, the trusted source is instantiated with `CommonTrustedCertificateSource` class. As well as a trusted source the CertificateVerifier object needs an OCSP and/or CRL source and a TSL source (which defines how the certificates are retrieved from the Trusted Lists). See chapter "Management of CRL and OCSP Sources" for more information concerning sources.

[source,java,indent=0]
.Validation of a signature
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/validate/ValidateSignedXmlXadesBTest.java[tags=demo]
----

NOTE: When using the TrustedListsCertificateSource class, for performance reasons, consider creating a single instance of this class and initialize it only once.

NOTE: In general, the signature must cover the entire document so that the DSS framework can validate it. However, for example in the case of a XAdES signature, some transformations can be applied on the XML document. They can include operations such as canonicalization, encoding/decoding, XSLT, XPath, XML schema validation, or XInclude. XPath transforms permit the signer to derive an XML document that omits portions of the source document. Consequently those excluded portions can change without affecting signature validity.

[[signedDocumentValidator]]
==== SignedDocumentValidator

For execution of the validation process, DSS uses the 'SignedDocumentValidator' class. The DSS framework provides five implementations of validator:

 * `XMLDocumentValidator` - validates documents in XML format (XAdES format);
 * `CMSDocumentValidator` - validates documents in CMS format (CAdES format);
 * `PDFDocumentValidator` - validates documents in PDF format (PADES format);
 * `JWSCompactDocumentValidator` - validates documents with base64url encoded content (JAdES compact format);
 * `JWSSerializationDocumentValidator` - validates documents in JSON format (JAdES serialization formats);
 * `ASiCContainerWithXAdESValidator` - validates ASiC with XAdES containers;
 * `ASiCContainerWithCAdESValidator` - validates ASiC with CAdES containers;
 * `DetachedTimestampValidator` - validates CMS timestamps provided alone.

DSS initializes a relevant validator based on specific characteristics of an input file (e.g. a PDF file version declaration for a PDF file). It checks the file format and loads the required validator from a classpath. Below you can find a list of settings that can be used for the configuration of the class.

[source,java,indent=0]
.SignedDocumentValidator usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[tags=demo]
----

===	Validation Result Materials

The result of the validation process consists of three elements:

 * the Simple Report,
 * the Detailed Report,
 * the Diagnostic Data and
 * the ETSI Validation Report.

All these reports are encoded using XML, 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 to able to generate PDF or HTML reports (simple and detailed reports).

You will find below a detailed description of each of these elements.

==== Simple Report

This is a sample of the simple validation report:

.Simple Report
include::_samples/simple-report-example.adoc[]

The result of the validation process is based on very complex 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.

==== Detailed Report

This is a sample of the detailed validation report. Its structure is based on the ETSI standard <<R09>> and is built around Basic Building Blocks, Basic Validation Data, Timestamp Validation Data, AdES-T Validation Data and Long Term Validation Data. Some segments were deleted to make reading easier. They are marked by three dots:

.Detailed Report
include::_samples/detailed-report-example.adoc[]

For example the Basic Building Blocks are divided into seven elements:

 * FC - Format Checking
 * ISC - Identification of the Signing Certificate
 * VCI - Validation Context Initialization
 * RFC - Revocation Freshness Checker
 * XCV - X.509 certificate validation
 * CV - Cryptographic Verification
 * SAV - Signature Acceptance Validation

The following additional elements also can be executed in case of validation in the past :

 * PCV - Past Certificate Validation
 * VTS - Validation Time Sliding process
 * POE extraction - Proof Of Existence extraction
 * PSV - Past Signature Validation

Past certificate/signature validation is used when basic validation of a certificate/signature fails at the current time with an INDETERMINATE status such that the provided proofs of existence may help to go to a determined status. The process shall initialize the _best-signature-time_ either to a time indication for a related POE provided, or the current time when this parameter has not been used by the algorithm.

 * *Best-signature-time* is an internal variable for the algorithm denoting the earliest time when it can be trusted by the SVA (either because proven by some POE present in the signature or passed by the DA and for this reason assumed to be trusted) that a signature has existed. <<R09>>

Each block contains a number of rules that are executed sequentially. The rules are driven by the constraints defined in the validation policy. The result of each rule is OK or NOT OK. The process is stopped when the first rule fails. Each block also contains a conclusion. If all rules are met then the conclusion node indicates PASSED. Otherwise FAILED or INDETERMINATE indication is returned depending on the ETSI standard definition.

==== Diagnostic Data

This is a data set constructed from the information contained in the signature itself, but also from information retrieved dynamically as revocation data and information extrapolated as the mathematical validity of a signature. All this information is independent of the applied validation policy. Two different validation policies applied to the same diagnostic data can lead to different results.

This is an example of the diagnostic data for a XAdES signature. Certain fields and certain values were trimmed or deleted to make reading easier:

.Diagnostic Data
include::_samples/diagnostic-data-example.adoc[]

==== ETSI Validation Report

The ETSI Validation Report represents an implementation of TS 119 102-2 (cf. <<R13>>). The report contains a standardized result of an ASiC digital signature validation. It includes the original validation input data, the applied validation policy, as well as the validation result of one or more signature(s) and its(their) constraints.

This is an example of the ETSI validation report:

.ETSI Validation Report (TS 119 102-2)
include::_samples/etsi-validation-report-example.adoc[]

[[validationPolicy]]
=== Validation Policy

The validation process may be 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 https://github.com/esig/dss/blob/master/dss-policy-jaxb/src/main/resources/xsd/policy.xsd[policy.xsd] schema and passed to the relevant `DocumentValidator` as shown below.

[source,java,indent=0]
.Custom validation policy
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=validationPolicy]
----

==== XML policy structure

The validation policy allows to define different behavior for various validating token types or signature formats. The following groups are considered:

 * `ContainerConstraints` - defines rules for processing of ASiC containers validation;
 * `SignatureConstraints` - defines rules for signature basic building blocks processing and the related certificate chain;
 * `CounterSignatureConstraints` - allows to define custom rules for counter signature processing;
 * `Timestamp` - defines rules for timestamp validation;
 * `Revocation` - defines rules for revocation data validation;
 * `Cryptographic` - defines common rules for cryptographic validation of used algorithms. The general constraints are used when no cryptographic constraints are defined for a particular token type;
 * `Model` - defines the way of a certificate chain processing;
 * `eIDAS` - defines rules for validation of Trusted Lists.

==== Constraints

Each constraint defined in the policy forces an execution of a relevant check in the validation process.

NOTE: If a constraint is missing in the policy - the check is not processed.

The following constraint types are supported:

 * `LevelConstraint` - a simple constraint type with a defined processing `Level`;
 * `MultiValuesConstraint` - allows to define a set of accepted values relatively to the using constraint.

==== Level

The `Level` attribute of a constraint defines a validation process behavior in case of a check failure. While used, the following behaviors apply in case of a check failure:

 * `FAIL` - brakes the validation process and returns the relevant indication;
 * `WARN` - continues the validation process and returns a warning message to the validation process output;
 * `INFORM` - continues the validation process and returns an information message to the validation process output;
 * `IGNORE` - processes the check in a silent mode (equivalent to a not defined constraint).

==== Multi Values Constraint

When using the `MultiValuesConstraint`, a list of acceptable values shall be defined in the list of `<Id>...</Id>` elements, one for each accepted value. While doing, the following rules apply:

 * Empty list of values  -> accept only empty values for the item in question, fails otherwise;
 * `"*"` constraint value -> accepts all values, reject empty list of values;
 * Custom values -> accepts only item values matching the constraint.

==== Cryptographic constraints

Cryptographic constraints define a list of acceptable cryptographic algorithms and their expiration dates when needed. The following settings are possible:

 * `AcceptableEncryptionAlgo` - defines a list of acceptable encryption algorithms. All tokens and signatures using other algorithms will be rejected.
 * `MiniPublicKeySize` - defines the minimal allowed public key size to be used with the defined encryption algorithms. An algorithm with a key size less than the defined one will be rejected. The minimal key size if required to be defined for an encryption algorithm, otherwise all used key sizes will be rejected.
 * `AcceptableDigestAlgo` - defines a list of acceptable digest algorithms. All tokens and signatures using other algorithms will be rejected.
 * `AlgoExpirationDate` - defines expiration dates for the algorithms. The algorithm is rejected when it is used after the defined date. If the algorithm expiration date is not defined, or set to null, the algorithm is treated as reliable for an unlimited time.

==== The default XML policy

The default XML validation policy is present below.

.constraint.xml (default policy is provided in dss-policy-jaxb module)
include::_samples/constraint.adoc[]

== CAdES signature (CMS)

To familiarize yourself with this type of signature it is advisable to read the following document:

* CAdES Specifications (cf. <<R02>>)

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. Below is an example of the CAdES-Baseline-B signature:

[source,java,indent=0]
.Signing a file with CAdES
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlCadesBTest.java[tags=demo]
----

== PAdES signature (PDF)

The standard ISO 32000-1 (cf. <<R06>>) allows defining a file format for portable electronic documents. It is based on PDF 1.7 of Adobe Systems. Concerning the digital signature it supports three operations:

 * Adding a digital signature to a document,
 * Providing a placeholder field for signatures,
 * Checking signatures for validity.

PAdES defines eight different profiles to be used with advanced electronic signature in the meaning of European Union Directive 1999/93/EC (cf. <<R07>>):

 * PAdES Basic - PDF signature as specified in ISO 32000-1 (cf. <<R06>>). The profile is specified in ETSI EN 319 142 (cf. <<R03>>).
 * PAdES-BES Profile - based upon CAdES-BES as specified in ETSI EN 319 122 (cf. <<R02>>) with the option of a signature time-stamp (CAdES-T).
 * PAdES-EPES profile - based upon CAdES-EPES as specified in ETSI EN 319 122 (cf. <<R02>>). This profile is the same as the PAdES - BES with the addition of a signature policy identifier and optionally a commitment type indication.
 * PAdES-LTV Profile - This profile supports the long term validation of PDF Signatures and can be used in conjunction with the above-mentioned profiles.
 * Four other PAdES profiles for XML Content.

To familiarize yourself with this type of signature it is advisable to read the documents referenced above.

Below is an example of code to perform a PAdES-BASELINE-B type signature:

[source,java,indent=0]
.Signing a PDF file with PAdES
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBTest.java[tags=demo]
----

In order to add a timestamp to the signature (PAdES-T or LTA), a TSP source must be provided to the service.

To create PAdES-BASELINE-B level with additional options: signature policy identifier and optionally a commitment type indication, please observe the following example in code 5.

All these parameters are optional.

[source,java,indent=0]
.Defining a Signature Policy
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBTest.java[tags=policy]
----

The extension of a signature of the level PAdES-BASELINE-B up to PAdES-BASELINE-LTA profile will add the following features:

 * Addition of validation data to an existing PDF document which may be used to validate earlier signatures within the document (including PDF signatures and time-stamp signatures).
 * Addition of a document time-stamp which protects the existing document and any validation data.
 * Further validation data and document time-stamp may be added to a document over time to maintain its authenticity and integrity.

=== PAdES Visible Signature

The framework also allows creation of PDF files with visible signature as specified in ETSI EN 319 142 (cf. <<R03>>). In the `SignatureParameters` object, there's a special attribute named `SignatureImageParameters`. This parameter allows you customize the visual signature (with text, with image or with image and text).
Below there is an example of code to perform a PADES-BASELINE-B type signature with a visible signature:

[source,java,indent=0]
.Add a visible signature to a PDF document
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java[tags=parameters-configuration;sign]
----

Additionally, DSS also allows you to insert a visible signature to an existing field :

[source,java,indent=0]
.Add a visible signature to an existing field
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=select-pdf-signature-field]
----

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.

==== 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:

 * *OpenPDF (iText)* - supports separate image and text drawing;
 * *PDFBox Default* - supports separate image and text drawing, as well as a joint drawing of image and text together. Transforms text to an image;
 * *PDFBox Native* - supports separate image and text drawing, as well as a joint drawing of image and text together. Prints text in a native way, that increases quality of the produced signature.

===== Positioning

DSS provides a set of functions allowing to place the signature field on a specific place in the PDF page :

[source,java,indent=0]
.Visible signature positioning
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/PAdESVisibleSignatureSnippet.java[tags=positioning]
----

===== Dimensions

DSS framework provides a set of functions to manage the signature field size :

[source,java,indent=0]
.Visible signature dimensions
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/PAdESVisibleSignatureSnippet.java[tags=positioning]
----

===== Text Parameters

The available implementations allow placing of a visible text to a signature field :

[source,java,indent=0]
.List of available visible text parameters
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java[tags=text]
----

===== 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 'SignatureImageTextParameters' object :

[source,java,indent=0]
.Combination of text and image parameters
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java[tags=textImageCombination]
----

The result of applying the foregoing transformations is provided on the image below:

image::visual-sig-text-parameters.jpg[]

==== Fonts usage

Since version 5.5, DSS supports two types of fonts. The custom font must be added as an instance of `DSSFont` interface to a `SignatureImageTextParameters` object.
`DSSFont` interface has following common implementations:

 * `DSSFileFont` for using of physical fonts, which must be embedded to the produced PDF document. To create an instance of the class, you must pass to a `DSSFileFont` constructor an object of `DSSDocument` type or InputStream of the font file;
 * `DSSJavaFont` for using of logical fonts (default Java fonts). The logical Java fonts allow you to significantly reduce the document size, because these fonts cannot be embedded to the final PDF document. Be aware, because of the fact, using of logical fonts does not allow producing PDF documents satisfying the PDF/A standard. To create an instance of this class, you should pass as an input a `java.awt.Font` object or target font parameters (name, style, size).

WARNING: Logical fonts may have different implementations depending on a used PAdES Visible signature service or Operating System (OS). Keep this in mind when switching an implementation or system environment.

As well as classes allowing to define native fonts for used implementations (available since DSS 5.7):

 * `ITextNativeFont` to be used with `ITextSignatureDrawerFactory`;
 * `PdfBoxNativeFont` to be used with `PdfBoxNativeObjectFactory`.

You can create a custom font as following (for a physical font):

[source,java,indent=0]
.Add a custom font as a file
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java[tags=font]
----

For a logical font:

[source,java,indent=0]
.Java font usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleExistingTest.java[tags=font]
----

For a native font:

[source,java,indent=0]
.Native font usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/PAdESVisibleSignatureSnippet.java[tags=nativeFont]
----

By default, DSS uses a Google font : 'PT Serif Regular' (its physical implementation).

NOTE: 'Native PDFBox Drawer' implementation supports only one of the following fonts: SERIF, SANS-SERIF, MONOSPACED, DIALOG and DIALOG_INPUT.

=== 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 are no algorithms to detect the malicious change with 100% guarantee. For more information, please refer to https://pdf-insecurity.org/[the website].

Since v5.8, DSS provides a set of own utils to detect the "shadow attack" on a signed PDF document. The following algorithms have been introduced:

 * `Page amount difference` - the validation tool compares the number of pages between the obtained PDF and signed revision. If the numbers do not match, the validation fail. The validation level can be configured within the <<validationPolicy>> with the constraint `<PdfPageDifference>`.
 * `Annotations overlap` - DSS checks if any annotation overlaps occurred. The overlapping is potentially dangerous, because some annotations can cover a visual content, e.g. forms and signature fields. The validation level can be configured with the constraint `<PdfAnnotationOverlap>`.
 * `Visual difference` - DSS verifies the visual difference between the provided document and signed revision, excluding the newly created annotations (between the validating revisions). The validation level can be configured with the constraint `<PdfVisualDifference>`.

== JAdES signature (JWS)

Since v5.8, DSS includes a possibility of creation and validation of JSON Advanced signatures.

JSON format for AdES Signatures (cf. [R05]) represents an extension of JSON Web Signatures (JWS) as specified in https://tools.ietf.org/html/rfc7515[IETF RFC 7515].

WARNING: The implementation is based on a draft of the standard ETSI TS 119 182-1. Some modifications can occur in future releases.

A typical example of a JAdES signature creation is represented below:

[source,java,indent=0]
.Signing a file with JAdES
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlJadesBTest.java[tags=demo]
----

The specific parameters for JAdES signature are described in the next sections.

=== JWS Serialization type

A JWS signature can be represented in different forms which are supported by the JAdES as well:

 * `COMPACT_SERIALIZATION` represents a compact, URL-safe serialization. It has no JWS Unprotected Header, therefore only JAdES-BASELINE-B level is possible with the format.
 * `JSON_SERIALIZATION` represents a JSON object with a collection of signatures inside the `signatures` header that allows a parallel signing. It allows JAdES-BASELINE-T/-LT/-LTA signature extension levels.
 * `FLATTENED_JSON_SERIALIZATION` represents a JSON object with a single signature container. It allows JAdES-BASELINE-T/-LT/-LTA signature extension levels.

[source,java,indent=0]
.JWS Serialization type usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlJadesBTest.java[tags=serialization]
----

=== JAdES Signature Packaging

JAdES signatures allow two types of JWS Payload (signed data) inclusion: `ENVELOPING` and `DETACHED`.

==== Enveloping packaging

With `ENVELOPING` packaging the JWS Payload is enveloped into the JAdES Signature. The type only allows signing one document.

==== Detached packaging

A simple JWS signature allows a `DETACHED` packaging by omitting the JWS Payload in the created signature. For the validation process the detached content shall be provided and it is treated in the same way as attached.

To create a such signature, the parameter `SigDMechanism.NO_SIG_D` shall be set. The solution allows signing of only one document.

The JAdES standard [R05] provides a possibility for signing of multiple documents withing one signature in a detached way.

The following mechanisms are possible:

 * `HTTP_HEADERS` is used to sign an HTTP request. The signature may explicitly sign several HTTP headers (represented by the class `HTTPHeader`), as well as the HTTP message body (see the `HTTPHeaderDigest` class).

[source,java,indent=0]
.Configuration for signing with detached mechanism HttpHeaders
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignHttpHeadersJadesBTest.java[tags=demo]
----

 * `OBJECT_ID_BY_URI` can be used for signing of multiple documents. The signed files are dereferenced by URIs and their content is concatenated for generation of the JWS Payload.

 * `OBJECT_ID_BY_URI_HASH` similarly provides a possibility to sign multiple documents, by signing the computed digests of the original documents. The JWS Payload for this format stays empty.

[source,java,indent=0]
.Configuration for signing with detached mechanism ObjectIdByURIHash
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignMultipleDocumentsJadesTTest.java[tags=demo]
----

=== Base64Url encoding

The `Base64Url` represents a Base64 encoded format with URI safe alphabet (see https://tools.ietf.org/html/rfc4648[RFC 4648]).

JAdES signatures (as well as JWS) force some values to be Base64Url-encoded, while provides a possibility to customize the format for some of them.

DSS provides options to configure encoding for the following elements:

 * JWS Payload can be represented as Base64Url encoded octets (by default), as well as can be present in its initial form (with the protected header `b64` set to `false`).

[source,java,indent=0]
.Use unencoded JWS Payload
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignHttpHeadersJadesBTest.java[tags=unencodedPayload]
----

 * The components of the unsigned header `etsiU` can occur either as Base64Url encoded strings (by default), or as clear JSON objects.

NOTE: All components inside the `etsiU` header shall be present in the same form (Base64Url encoded or as clear JSON).

WARNING: The current version of DSS does not allow JAdES-BASELINE-LTA level creation for `etsiU` components in their clear JSON representation.

[source,java,indent=0]
.Represent EtsiU components as clear JSON instances
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignMultipleDocumentsJadesTTest.java[tags=clearEtsiU]
----

== ASiC signature (containers)

When creating a digital signature, the user must choose between different packaging elements, namely enveloping, enveloped or detached. This 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. That's where the standard ETSI EN 319 162 (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.

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; the first (ASiC-S) allows you to associate one or more signatures with a single data element. In this case the structure of the signature can be based (in a general way) on a single CAdES signature or on multiple XAdES signatures or finally on a single TST; the second is an extended container (ASiC-E) that includes multiple data objects. Each data object may be signed by one or more signatures which structure is similar to ASiC-S. This second type of container is compatible with OCF, UCF and ODF formats.

For the moment the 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.

.ASiC containers
|===
|Input |Output

|ASiC-S CAdES |ASiC-S CAdES

|ASiC-S XAdES |ASiC-S XAdES

|ASiC-E CAdES |ASiC-E CAdES

|ASiC-E XAdES |ASiC-E XAdES

|Binary |ASiC-S CAdES, ASiC-S XAdES, ASiC-E CAdES, ASiC-E XAdES
|===

This is an example of the source code for signing a document using ASiCS-S based on XAdES-B:

[source,java,indent=0]
.Sign a file within an ASiC-S container
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignOneFileWithASiCSBTest.java[tags=demo]
----

This is another example of the source code for signing multiple documents using ASiCS-E based on CAdES:

[source,java,indent=0]
.Sign multiple files within an ASiC-E container
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignMultipleDocumentsWithASiCSEWithCAdESTest.java[tags=demo]
----

Please note that you need to pass only few parameters to the service. Other parameters, although are positioned, will be overwritten by the internal implementation of the service. Therefore, the obtained signature is always based on CAdES and of DETACHED packaging.

It is also possible with the framework DSS to make an extension of an ASiC container to the level XAdES-BASELINE-T or -LT.

== Counter signatures

Since v5.8 DSS allows producing of counter signatures according to the corresponding AdES formats.

NOTE: Counter signature does not provide a Proof Of Existence for a signed signature! Use signature extension / timestamping for this purpose.

The following formats are supported for the counter signature creation:

 * `XAdES` - multiple, nested and extended counter signatures (up to LTA level) are allowed;
 * `CAdES` - B-level counter signatures are allowed, as well as multiple counter signatures;
 * `JAdES` - multiple, nested and extended signatures (up to LTA level) are allowed;
 * `ASiC` - counter signatures are allowed according to the used format (XAdES or CAdES).

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 represents a counter signature creation:

[source,java,indent=0]
.Counter signature creation
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/CounterSignXadesBTest.java[tags=demo]
----

== Various parameters

[[signaturePolicy]]
=== Signature policy

With the new standards the policy handling is linked to -B level. The old -EPES level is not used anymore by the framework. This does not alter the structure of the old signature but only modifies how to control the process of its creation.

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. It includes two kinds of text:

* In a human readable form:
It can be assessed to meet the requirements of the legal and contractual context in which it is being applied.

* In a machine processable form:
To facilitate its automatic processing using the electronic rules.

If no signature policy is identified then the signature may be assumed to have been generated or verified without any policy constraints, and hence may be given no specific legal or contractual significance through the context of a signature policy.

The signer may reference the policy either implicitly or explicitly. An implied policy means the signer follows the rules of the policy but the signature does not indicate which policy. It is assumed the choice of policy is clear from the context in which the signature is used and SignaturePolicyIdentifier element will be empty. When the policy is not implied, the signature contains an ObjectIdentier that uniquely identifies the version of the policy in use. The signature also contains a hash of the policy document to make sure that the signer and verifier agree on the contents of the policy document.

This example demonstrates an implicit policy identifier. To implement this alternative you must set SignaturePolicyId to empty string.

[source,java,indent=0]
.XAdES with implicit policy
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBImplicitPolicyTest.java[tags=demo]
----

An XML segment will be added to the signature's qualified and signed properties:

include::_samples/xades-implicit-policy.adoc[]

The next example demonstrates an explicit policy identifier. This is obtained by setting -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 to the developer to proceed with the calculation using for example java.security.MessageDigest class (rt.jar). 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. See also chapter 7 for further information.

[source,java,indent=0]
.XAdES with explicit policy
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBExplicitPolicyTest.java[tags=demo]
----

The following XML segment will be added to the signature qualified & signed properties (<QualifyingProperties><SignedProperties>):

.XAdES Signature Policy element
include::_samples/xades-explicit-policy.adoc[]

=== Signature Policy Store

Since v5.8 DSS 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:

* XAdES (as well as ASiC with XAdES);
* CAdES (as well as ASiC with CAdES);
* JAdES.

NOTE: Being an unsigned component the Signature Policy Store is not protected by a digital signature, unlike a Signature Policy Identifier incorporated into the signed properties.

Before incorporating of a Signature Policy Store, you need to ensure the target signature contains the matching Signature Policy Identifier element (see ch. <<signaturePolicy>>).

An example of a Signature Policy Store creation is available below:

[source,java,indent=0]
.Add SignaturePolicyStore
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBExplicitPolicyTest.java[tags=addSPS]
----

=== Trust anchor inclusion policy

It is possible to indicate to the framework if the certificate related to the trust anchor should be included to the signature or not. The setter #setTrustAnchorBPPolicy of the BLevelParameters class should be used for this purpose.

This rule applies as follows: when -B level is constructed the trust anchor is not included, when -LT level is constructed the trust anchor is included.

NOTE: When trust anchor baseline profile policy is defined only the certificates previous to the trust anchor are included when -B level is constructed.

== Timestamps

=== Timestamp creation

Since DSS 5.6 the framework allows an independent document timestamping (without a signature). The following Document Signature Services support the timestamping :

 * `PAdESService` - adds a timestamp to a PDF document;
 * `ASiCWithCAdESService` - creates a timestamped ASiC container with provided documents.

[source,java,indent=0]
.PDF timestamping
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/timestamp/TimestampPDFTest.java[tags=creation]
----

=== Timestamp validation

As well as a single timestamp creation, DSS provides a validation service for timestamped documents. The timestamp validation process represents "5.4 Time-stamp validation building block" (cf. <<R09>>). The validation process is identical to <<signatureValidation>> process. An appropriate validator will be selected automatically. In total, DSS supports timestamp-alone validation for the following file formats:

 * Detached CMS timestamp (`DetachedTimestampValidator`) - a detached signed content must be provided (or its digest);
 * PDF document (`PDFDocumentValidator`);
 * ASiC CAdES container with a timestamp (`ASiCWithCAdESTimestampValidator`).

The validation process can be run with the following inputs :

[source,java,indent=0]
.Timestamped document validation
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/timestamp/TimestampPDFTest.java[tags=validation]
----

The produced reports use the same structure as for <<signatureValidation>>.

==== Timestamp qualification

DSS is also 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 <<tlValidationJob>>) (cf. <<R14>>).

Three qualification levels are supported by DSS and can be obtained :

 * `QTSA` (issued from a granted trust service with TSA/QTST type at the timestamp production time);
 * `TSA` any other from a known trust anchor;
 * `N/A` for others.

An example of a produced Detailed Report you can see below:

.Timestamp Detailed Report
include::_samples/timestamp-detailed-report-example.adoc[]

== Available implementations of DSSDocument

DSS allows creation of different kinds of DSSDocument :

 * `InMemoryDocument` : fully loads in memory. This type of DSSDocument can be instantiated with an array of bytes, an InputStream,...
 * `FileDocument` : refers an existing File
 * `DigestDocument` : only contains pre-computed digest values for a given document. That allows a user to avoid sending the full document (detached signatures).

[source,java,indent=0]
.DigestDocument
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sources/DigestDocumentTest.java[tags=demo]
----

== Management of signature tokens

The DSS framework is able to create signatures from PKCS#11, PKCS#12 and MS CAPI. Java 6 is inherently capable of communicating with these kinds of KeyStores. To be independent of the signing media, DSS framework uses an interface named SignatureTokenConnection to manage different implementations of the signing process. The base implementation is able to sign a stream of the data in one step. That means that all the data to be signed needs to be sent to the SSCD. This is the case for MS CAPI. As to the PKCS#11 and PKCS#12, which give to the developer a finer control in the signature operation, the DSS framework implements the AsyncSignatureTokenConnection abstract class that permits to execute the digest operation and signature operation in two different threads or even two different hardwares.

This design permits also other card providers/adopters to create own implementations. For example, this can be used for a direct connection to the Smartcard through Java 6 PC/SC.

=== PKCS#11

PKCS#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.

[source,java,indent=0]
.Pkcs11SignatureToken usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/PKCS11Snippet.java[tags=demo]
----

=== PKCS#12

This standard defines a file format commonly used to store the private key and corresponding public key certificate protecting them by password.

In order to use this format with the DSS framework you have to go through the class Pkcs12SignatureToken.

[source,java,indent=0]
.Pkcs12SignatureToken usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/PKCS12Snippet.java[tags=demo]
----

=== MS CAPI

If the middleware for communicating with an SSDC provides a CSP based on MS CAPI specification, then to sign the documents you can use MSCAPISignatureToken class.

[source,java,indent=0]
.MSCAPISignatureToken usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/MSCAPISnippet.java[tags=demo]
----

=== Other Implementations

As you can see, it is easy to add another implementation of the SignatureTokenConnection, thus enabling the framework to use other API than the provided three (PKCS#11, PKCS#12 and MS CAPI). For example, it is likely that in the future PC/SC will be the preferred way of accessing a Smartcard. Although PKCS#11 is currently the most used API, DSS framework is extensible and can use PC/SC. For our design example we propose to use PC/SC to communicate with the Smartcard.

== Management of certificates sources

The validation of a certificate requires the access to some other certificates from multiple sources like trusted lists, trust store, the signature itself: certificates can be contained inside or any other source.
Within the framework, an X509 certificate is wrapped through the class:

 * `eu.europa.esig.dss.model.x509.CertificateToken`

This encapsulation helps make certificate handling more suited to the needs of the validation in the context of trust. The framework associates two internal identifiers to the certificate : the DSS Id based on the certificate binary (unique for each certificate) and the Entity Id based on its public key (common to cross-signed certificates).

Certificate tokens are grouped into sources. A certificate token can be declared in several sources. The class that models a source is called:

 * `eu.europa.esig.dss.spi.x509.CertificateSource`

This class stores all extracted/injected certificates for a specific source (Signature, OCSP Response, Trust store, Trusted-list,...). All source types are specified in the enumeration :

 * `eu.europa.esig.dss.enumerations.CertificateSourceType`

This information is used, for example, to distinguish between the certificate from a trusted source and the others. A source has one and only one type, but a certificate token can be found in multiple sources.
The DSS framework supplies some standard implementations, but also gives the possibility to implement owner solutions. Among the standard solutions you can find:

 * `eu.europa.esig.dss.spi.x509.CommonCertificateSource`

This is the superclass of almost of the certificate sources. It stores the extracted certificates and implements the common methods from the `CertificateSource` to retrieve certificate(s) by subject, public key, subject key identifier (ski),...

It also exposes the method CommonCertificateSource#addCertificate which gives the possibility to add manually any CertificateToken as a part of this source.

 * `eu.europa.esig.dss.spi.x509.CommonTrustedCertificateSource`

The CommonTrustedCertificateSource is a certificate source for trusted certificates. All added certificates are marked as trust anchors and no revocation data are required for these certificates.

 * `eu.europa.esig.dss.validation.SignatureCertificateSource`

This class and its sub-classes are used to extract and collect certificates from signatures / timestamps. It also has methods to retrieve certificates / certificate references by their origin (eg : SigningCertificate attribute, DSS Dictionary,...).

 * `eu.europa.esig.dss.spi.tsl.TrustedListsCertificateSource`

Certificates coming from the list of Trusted Lists. This class inherits of `CommonTrustedCertificateSource` and  gives the mechanism to define the set of trusted certificates (trust anchors). They are used in the validation process to decide if the prospective certificate chain has a trust anchor. See chapter <<tlValidationJob>> to get more information about trusted lists loading (e.g. EU Trusted List).

 * `eu.europa.esig.dss.spi.x509.ListCertificateSource`

This class follows the composite design pattern with a list of CertificateSources. That's used in the validation to retrieve all sources from the signatures / timestamps / revocation data / trusted lists /... It contains some methods which check over all sources to retrieve certificates or verify if a certificate is trusted.

== Management of CRL and OCSP sources

A CRL is a time-stamped list identifying revoked certificates. It is signed by a Certificate Authority (CA) and made freely available in a public repository. Each revoked certificate is identified in a CRL by its certificate serial number.

The Online Certificate Status Protocol (OCSP) is an Internet protocol used for obtaining the revocation status of an unique X.509 digital certificate.

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

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

[source,java,indent=0]
.CRLSource usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/CRLSourceSnippet.java[tags=demo]
----

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

[source,java,indent=0]
.OCSPSource usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/OCSPSourceSnippet.java[tags=demo]
----

We use these classes during the certificate validation process through "validationContext" object (based on ValidationContext class) which is a "cache" for one validation request that contains every object retrieved so far. This object in turn instantiates a "verifier" based on `RevocationDataLoadingStrategy` class whose role is to fetch revocation data by querying an OCSP or CRL source in the defined order and return the succeeded result.
In general, we can distinguish three main sources:

 * Offline sources (`OfflineRevocationSource`);
 * Online sources (`OnlineRevocationSource`);
 * Sources with the cache mechanism;
 * List of sources (`ListRevocationSource`) with a collection of several sources.

=== Repository Revocation Source

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

List of cached Revocation sources implemented in DSS:

 * `JdbcRevocationSource`
 ** `JdbcCacheCRLSource`
 ** `JdbcCacheOCSPSource`

The classes allow the following configuration :

[source,java,indent=0]
.JdbcCacheCRLSource usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/CRLSourceSnippet.java[tags=demo-cached]
----

And an example for JdbcCacheOCSPSource :

[source,java,indent=0]
.JdbcCacheOCSPSource usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/OCSPSourceSnippet.java[tags=demo-cached]
----

Be aware that you have to initialize a table before start of working with the cached revocation repository.

=== Other implementations of CRL and OCSP Sources

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

 * CRL sources
 ** `OfflineCRLSource` : This class implements the `OfflineRevocationSource` and retrieves the revocation data from extracted information. The code is common for all signature formats and CRL contents are injected by its sub-classes :
 *** `CMSCRLSource` : Extracts CRLs and CRL references from a CMS Signed Data :
 **** `CAdESCRLSource` : Sub-class of `CMSCRLSource` for a CAdES Signature;
 **** `TimestampCRLSource`: Sub-class of `CMSCRLSource` for a Timestamp token (RFC 3161);
 *** `PAdESCRLSource` : Extracts CRLs and CRL references from a PAdES signature.
 *** `XAdESCRLSource` : Extracts CRLs and CRL references from a XAdES signature.
 *** `ExternalResourcesCRLSource` : A class that can instantiate a list of certificate revocation lists from a directory where should be the individual lists.
 ** `OnlineCRLSource` : Retrieves CRL files from online sources with the CRL Distribution Points information from the certificate.
 ** `JdbcCacheCrlSource` : Implementation of the `JdbcRevocationSource`. This implementation allows storage of valid CRL entries to a defined `DataSource'` and retrieve them locally.

 * OCSP sources
 ** `OfflineOCSPSource` : This class implements the `OfflineRevocationSource` and retrieves the revocation data from extracted information. The code is common for all signature formats and OCSP responses are injected by its sub-classes :
 *** `CMSOCSPSource` : Extracts OCSP responses and OCSP references from a CMS Signed Data :
 **** `CAdESOCSPSource` : Sub-class of `CMSOCSPSource` for a CAdES Signature;
 **** `TimestampOCSPSource`: Sub-class of `CMSOCSPSource` for a Timestamp token (RFC 3161);
 *** `PAdESOCSPSource` : Extracts OCSP responses and OCSP references from a PAdES signature.
 *** `XAdESOCSPSource` : Extracts OCSP responses and OCSP references from a XAdES signature.
 **** `ExternalResourcesOCSPSource` : A class that can instantiate a list of OCSPToken from a directory where should be the individual DER Encoded X509 certificates files.
 ** `OnlineOCSPSource` : Retrieves OCSP responses from online source.
 ** `JdbcCacheOcspSource` : Implementation of the `JdbcRevocationSource`. This implementation allows storage of valid OCSP entries to a defined `DataSource` and retrieve them locally.

==== Online CRL Source

This is a representation of an Online CRL repository. This implementation will contact using HTTP protocol the CRL Responder to download the CRLs from the given URI. Note that certificate"s Authority Information Access (AIA) extension is used to find issuer's resources location like CRL file and/or Online Certificate Status Protocol (OCSP). 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 :

[source,java,indent=0]
.OnlineCRLSource usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/CRLSourceSnippet.java[tags=demo-online]
----

==== Online OCSP Source

This is a representation of an Online OCSP repository. This implementation will contact using HTTP protocol the OCSP Responder to retrieve the OCSP response. Note that certificate's Authority Information Access (AIA) extension is used to find issuer's resources location like CRT file and/or 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 :

[source,java,indent=0]
.OnlineOCSPSource usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/OCSPSourceSnippet.java[tags=demo-online]
----

[[certificateVerifier]]
== CertificateVerifier configuration

The CertificateVerifier and its implementation CommonCertificateVerifier determines how DSS accesses the external resources and how it should react in some occasions. This configuration is used in both extension and validation mode.

[source,java,indent=0]
.CertificateVerifier usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/CertificateVerifierSnippet.java[tags=demo]
----

== Trust Anchor(s) configuration

Trust anchors represent an important part in the signature creation / validation. That defines which are the trusted entities, which signatures can be trusted,... Do I trust certificates/signatures from another company / country / ... ?

Since the version 5.6, DSS allows to configure one or more trusted certificate source(s). These sources can be configured from a TrustStore (kind of keystore which only contains certificates), a trusted list and/or a list of trusted lists.

[source,java,indent=0]
.Multiple trusted certificate sources usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=multi-trusted-certificate-sources]
----

=== Trust store initialization

If you have a collection of certificates to trust, the easier way to provide them to DSS it to use a KeyStore / TrustStore.

[source,java,indent=0]
.Trust anchor initialization from a Trust Store
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=trust-store]
----

To generate the trust store, there's an utility class CreateKeyStoreApp in the dss-cookbook module.

=== Trusted List Certificate Source

In several countries, a list of Trust Service Providers (TSP) is published. This list is usually published in a machine processable format (XML) and sometimes in a human-readable format (PDF). A standard (ETSI TS 119 612) exists with the specifications for the XML format.

DSS contains all needed resources to download, parse, validate and interpret the trusted list contents. Since DSS 5.6, that's possible to configure one or more independent trusted list(s) (aka not linked to a list of trusted lists) and/or one or more list of trusted lists.

If you want to collect your trusted certificates from trusted list(s), the TrustedListsCertificateSource is required. The trusted list(s) loading can require some times (connection time-out, xml parsing, xml validation,...). This process is usually executed in background. An instance of TrustedListsCertificateSource needs to be created. That will be synchronized with the TLValidationJob.

[source,java,indent=0]
.Trusted List Certificate Source
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=trusted-list-source]
----

[[tlValidationJob]]
== TLValidationJob

The TLValidationJob allows to download, parse, validate the Trusted List(s) and Lists Of Trusted Lists (LOTL). Once the task is done, its result is stored in the TrustedListsCertificateSource. The job uses 3 different caches (download, parsing and validation) and a state-machine to be efficient.

Trusted lists are stored on the file system. That offers the possibility to run 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.

=== TLSource and LOTLSource

Several TLSources and several LOTLSources can be injected in a TLValidationJob. The only constraint is the uniqueness of the Trusted List URLs.

[source,java,indent=0]
.Multiple TLSources and multiple LOTLSources configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=job-config-sources]
----

==== Trusted List Source (TLSource)

A TLSource allows to quickly setup a trusted list configuration. The URL and the signing certificates for this TL are mandatory. Optionally, predicates / filters can be configured to retrieve only a part of the trust service providers or trust services.

[source,java,indent=0]
.TLSource configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=french-tl-source]
----

==== List Of Trusted Lists Source (LOTLSource)

A similar configuration is possible for Lists Of Trusted Lists (LOTL). That requires an URL and the possible LOTL signers. Some other parameters are possible. By default, all listed trusted lists are loaded.

[source,java,indent=0]
.LOTLSource configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=european-lotl-source]
----

=== DSSFileLoader

The FileCacheDataLoader is used to download the trusted list contents on the file-system. Two different configurations are needed. Both of them share the same folder :

 * offline refresh : disabled download from Internet and unlimited cache expiration
 * online refresh : enabled download from Internet and limited cache expiration

[source,java,indent=0]
.Offline and Online refresh configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=job-loaders]
----

=== The SynchronizationStrategy

The SynchronizationStrategy defines which are the trusted lists or list of trusted lists to be synchronized. By default, DSS synchronizes all of them. DSS don't reject any expired / invalid /... trusted lists. The content is trusted and a warning is added in a signature / certificate validation.

The strategy is configurable via the interface SynchronizationStrategy :

[source,java,indent=0]
.Example of a custom  SynchronizationStrategy
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=custom-strategy]
----

DSS provides two implementations : ExpirationAndSignatureCheckStrategy and AcceptAllStrategy (default).

=== The CacheCleaner

The CacheCleaner specifies how DSS clear the cache in case of expired URL,... 2 options are available : memory and file-system.

[source,java,indent=0]
.CacheCleaner Configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=cache-cleaner]
----

=== Alerting from TL Loading

DSS allows running of custom alerts in some situations (eg : invalid TL signature, LOTL location change,...). 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).

[source,java,indent=0]
.Examples of Alerting
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=alerting]
----

=== Executor Service

An Executor Service parameter 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.

[source,java,indent=0]
.Executor Service
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=executor-service]
----

=== Complete configuration for the European LOTL

Below, you can find a complete configuration for the European List Of Trusted Lists. The URLs need to be externalized.

[source,java,indent=0]
.European LOTL Configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/EuropeanLOTLSnippets.java[tags=complete-european-lotl-config]
----

=== The TL / LOTL refresh

The TL / LOTL loading in DSS works as below :

 * Download / parse / validate all LOTLSources from the configuration with/without pivot support (multi-threaded)
 * Analyze introduced changes and expire cache entries (new TL URLs, new signing certificates for a TL,...)
 * Create TLSources from the retrieved LOTLs
 * Combine these TLSources with independent TLSources (from the configuration)
 * Download / parse / validate all TLs (multi-threaded)
 * If alerts are configured, test if an alert needs to be launched
 * If the debug is enabled, print in the log the cache status
 * Synchronize the TrustedListCertificateSource
 * If the cache cleaner is configured, execute it
 * If the debug is enabled, print in the log the cache status

The refresh can be called with the offline or the online loader and run exactly the same code

[source,java,indent=0]
.How to refresh the Trusted List(s) and Lists of Trusted Lists
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=refresh]
----

[[KeyStore]]
==== Java Keystore Management

Generally (like in case of European LOTL) DSS downloads Trusted Lists by using the SSL protocol (for resources using HTTPS extension), that requires to have a certificate of a remote source in the Java trust store. The certificates have their own validity period and can expire. If a certificated is expired, it will be replaced on a server by a new one in order to support a secure SSL connection. The easiest way to know if your Java trust store is outdated and new certificates need to be added is to check your logs during a TLValidationJob update :

[source]
--
ERROR 14052 --- [pool-2-thread-30] e.e.e.dss.tsl.runnable.AbstractAnalysis  : Unable to process GET call for url [https://sr.riik.ee/tsl/estonian-tsl.xml]. Reason : [PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target]
--

The `SunCertPathBuilderException` means that the certificate established the secure connection is not trusted by your Java Virtual Machine. In order to add the certificate to the trust store, you need to do the following steps (the example is based on Windows OS and Google Chrome browser):

 . Open the failed URL in your browser. In our case it will be 'https://sr.riik.ee/tsl/estonian-tsl.xml' obtained from the logs.
 . Click on a lock icon next to the URL in the tab you just opened. It will open a window about the current connection status.
 . Click on 'Certificate' button to open the Certificate window.
 . Go to 'Details' tab and choose 'Copy to File...'.
 . Process the 'Certificate Export Wizard', by saving the certificate in one of '.CER' formats. Store the file in your file system. For us it will create a file 'ee.cer'.
 . Run 'Command Prompt' with administrator permissions (right click -> 'Run As Administrator').
 . Execute the following line (ensure that 'keytool' is installed) :

.Certificate import
[source,ruby]
----
keytool -import -alias newCert -file pathToCert\ee.cer -keystore pathToJavaDirectory\lib\security\cacerts -storepass changeit
----

The default password for a Java keystore is "changeit". Ensure that you have a default configuration, or use another password you have configured.

NOTE: In order to apply changes, the application using Java must be rebooted.

After these steps the `TLValidationJob` will successfully download the target Trusted List (i.e. Estonian in our example).

NOTE: This described algorithm is not only one available solution, if you have difficulties with this, you can search in the Internet for another working for you solution.

=== TLValidationJobSummary

The class TLValidationJobSummary contains all processed data about the download (time, error,...), the parsing (extracted information, parsing error,...) and the signature validation (signing certificate, signing time,...).

[source,java,indent=0]
.How to retrieve the information about the TLValidationJob process
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java[tags=tl-summary]
----

== TSP Sources

The Time Stamp Authority by creating time-stamp tokens provides independent and irrefutable proof of time for business transactions, e-documents and digital signatures. The TSA must comply with the IETF RFC 3161 specifications (cf. <<R08>>). A time-stamp is obtained by sending the digest value of the given data and digest algorithm to the Time Stamp Authority. The returned time-stamp is a signed data that contains the digest value, the identity of the TSA, and the time of stamping. This proves that the given data existed before the time of stamping.
The DSS framework proposes TSPSource interface to implement the communication with TSA. The class OnlineTSPSource is the default implementation of TSP using HTTP(S) communication layer.
The following bit of Java code illustrates how you might use this class:

[source,java,indent=0]
.OnlineTSPSource usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sources/OnlineTSPSourceTest.java[tags=demo]
----

=== Time-stamp policy

A 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. A time-stamp policy may be defined by the user of times-stamp services.

=== Composite TSP Source

Sometimes, timestamping servers may encounter interruptions (restart,...). To avoid failing signature extension, DSS allows a user to configure several TSP Sources. DSS will try source by source until getting an usable timestamp token.

[source,java,indent=0]
.Configuration of a CompositeTSPSource
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/sources/CompositeTSPSourceTest.java[tags=demo]
----

== Supported algorithms

DSS 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.

NOTE: SmartCards/HSMs don't allow signing with all digest algorithms. Please refer to your SmartCard/HSM provider.

[cols="13*^"]
.Supported algorithms
|===
| | SHA-1 | SHA-224 | SHA-256 | SHA-384 | SHA-512 | SHA3-224 | SHA3-256 | SHA3-384 | SHA3-512 | MD2 | MD5 | RIPEMD160

13+|*RSA*

| XAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | | | | | icon:check-circle[role="lime"] | icon:check-circle[role="lime"]

| CAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"]

| JAdES | | | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | | | | | |

13+|*RSA-PSS*

| XAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | |

| CAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | |

| JAdES | | | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | | | | | |

13+|*ECDSA*

| XAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | | | | | | icon:check-circle[role="lime"]

| CAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | |

| JAdES | | | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | | | | | |

13+|*Ed25519*

| XAdES | | | | | | | | | | | |

| CAdES | | | | | icon:check-circle[role="lime"] | | | | | | |

13+|*DSA*

| XAdES | icon:check-circle[role="lime"] | | icon:check-circle[role="lime"] | | | | | | | | |

| CAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | |

| JAdES | | | | | | | | | | | |

13+|*HMAC*

| XAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | | | | | | icon:check-circle[role="lime"]

| CAdES | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | |

| JAdES | | | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | icon:check-circle[role="lime"] | | | | | | |
|===

== Implementation management with ServiceLoader

DSS incorporates modules that are loaded in the run time based on the chosen configuration and the input data via a https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html[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 ServiceLoader, a file listing all the desired implementations should be created in the resource directory `META-INF/services` with a name matching the implemented interface. When merging sources (e.g. creating a Fat JAR module), the files can be lost/overwritten, and should be configured manually (all the required implementations shall be listed).

NOTE: If a DSS module(s) implementing a required interface(s) is added to your project's dependency list, the implementation shall be loaded automatically.

The following modules are provided with independent implementations:

 * <<dssUtils>>;
 * <<dssCrlParser>>;
 * <<dssPades>>.

Additionally, DSS is able to choose the required implementation for the following interfaces:

 * `DocumentValidationFactory` - checks a provided signed file's format and loads a relevant validator;
 * `SignaturePolicyValidator` - checks a signature policy file and loads a relevant validator to be able to process the detected format.

WARNING: If no appropriate available implementation is found, an exception will be thrown.

=== Document Validation Factory

This factory is used to create a required instance of a `DocumentValidator` based on the provided file's format (signature or timestamp). An implementation shall process a file format check and load the related <<signedDocumentValidator>> implementation to be used for the file's validation.

The following implementations are present in DSS:

 * CMSDocumentValidatorFactory : loads CMSDocumentValidator, used for a CAdES validation (delivered in dss-cades module);
 * XMLDocumentValidatorFactory : loads XMLDocumentValidator, used for a XAdES validation (delivered in dss-xades module);
 * PDFDocumentValidatorFactory : loads PDFDocumentValidator, used for a PAdES validation (delivered in dss-pades module);
 * JAdESDocumentValidatorFactory : loads JWSCompactDocumentValidator or JWSSerializationDocumentValidator, depending on provided JSON signature type (delivered in dss-jades module);
 * ASiCContainerWithCAdESValidatorFactory : loads ASiCContainerWithCAdESValidator (delivered in dss-asic-cades module);
 * ASiCContainerWithXAdESValidatorFactory : loads ASiCContainerWithXAdESValidator (delivered in dss-asic-xades module);
 * DetachedTimestampValidatorFactory : loads DetachedTimestampValidator, for an indepenedent timestamp validation (delivered in dss-document module).

=== Signature Policy Validator

This interface is used to validate a signature policy reference extracted from a signature. The following implementations are provided:

 * BasicASNSignaturePolicyValidator : validates policy files, which are based on ETSI TR 102 272;
 * XMLSignaturePolicyValidator : validates XML signature policies supporting transformations;
 * NonASN1SignaturePolicyValidator : validates a policy by digest computed on an original file's content;
 * ZeroHashSignaturePolicyValidator : validates a policy if "zero hash" value is defined in a signature (see <<R02>>);
 * EmptySignaturePolicyValidator : is proceeded if a policy file is not found or not accessible.

== Multi-threading

DSS 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 CertificateVerifier object. This object is responsible to provide certificates and accesses to external resources (AIA, CRL, OCSP,...). At the beginning of all operation, CertificateSources and RevocationSources are created for each signature / timestamp / revocation data. Extracted information are combined with the configured sources in the CertificateVerifier. For these reasons, integrators need to be careful about the CertificateVerifier configuration.

=== Resource sharing

The 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 not present certificates. These certificates are not necessarily trusted and may require future "modifications" like revocation data collection,...

=== Caching

In 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.

[[xmlSecurities]]
== XML Securities

Since DSS 5.7, the framework allows custom configuration of XML-related modules for enabling/disabling of XML securities (e.g. in order to use Xalan or Xerces).

WARNING: We strongly do not recommend disabling of security features and usage of deprecated dependencies. Be aware: the feature is designed only for experienced users, and all changes made in the module are at your own risk.

The configuration is available for the following classes:

 * `javax.xml.parsers.DocumentBuilderFactory` with a `DocumentBuilderFactoryBuilder` - builds a DOM document object from the obtained XML file and creates a new Document;
 * `javax.xml.transform.TransformerFactory` with a `TransformerFactoryBuilder` - loads XML templates and builds DOM objects;
 * `javax.xml.validation.SchemaFactory` with a `SchemaFactoryBuilder` - loads XML Schema;
 * `javax.xml.validation.Validator` with a `ValidatorConfigurator` - configures a validator to validate an XML document against an XML Schema.

All the classes can be configured with the following methods (example for `TransformerFactory`):

[source,java,indent=0]
.XMLSecurities configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/XMLSecuritiesConfigTest.java[tags=demo]
----

The `javax.xml.parsers.DocumentBuilderFactory`, that allows XML files parsing and creation of DOM `Document` object, can be configured with the following methods:

NOTE: Since DSS 5.9 the configuration of `javax.xml.parsers.DocumentBuilderFactory` has been moved from `DomUtils` to a new singleton class `DocumentBuilderFactoryBuilder`.

[source,java,indent=0]
.DocumentBuilderFactory configuration
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/XMLSecuritiesConfigTest.java[tags=dbf]
----

The class `XmlDefinerUtils` is a singleton, therefore all changes performed on the instance will have an impact to all calls of the related methods.

== JAXB modules

Since the version 5.5, DSS provides the following JAXB modules with a harmonized structure :

 * `dss-policy-jaxb` - defines validation policy JAXB model
 * `dss-diagnostic-jaxb` - defines Diagnostic Data JAXB model
 * `dss-detailed-report-jaxb` - defines Detailed Report JAXB model
 * `dss-simple-report-jaxb` - defines Simple Report JAXB model
 * `dss-simple-certificate-report-jaxb` - defines Certificate Simple Report JAXB model

All modules share the same logic and have the following structure (where *** is a model name):

`*_dss-***-jaxb_*`::
	`*_src/main/java_*`:::
		`*_eu.europa.esig.dss.***_*`::::
			** `*_***.java_*` - wrapper(s) which eases the JAXB manipulation
			** `*_..._*`
			** `*_***Facade.java_*` - class which allows marshalling/unmarshalling of jaxb objects, generation of HTML/PDF content, etc.
			** `*_***XmlDefiner.java_*` - class which contains the model definition (XSD, XSLT references, ObjectFactory)
			** `*_jaxb_*` - generated on compile time
			 	*** `*_Xml***.java_*` - JAXB model
				*** `*_..._*`
	`*_src/main/resources_*`:::
		`*_xsd_*`::::
			** `*_***.xsd_*` - XML Schema (XSD) for the Detailed Report model
			** `*_binding.xml_*` - XJC instructions to generate the JAXB model from the XSD
		`*_xslt_*`::::
			** `*_html_*`
			*** 	`*_***.xslt_*` - XML Stylesheet for the HTML generation
			** `*_pdf_*`
			***	`*_***.xslt_*` - XML Stylesheet for the PDF generation

In the main classes, a `Facade` is present to quickly operate with the JAXB objects (eg: marshall, unmarshall, generate the HTML/PDF, validate the XML structure,...).

[source,java,indent=0]
.DetailedReportFacade usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[tags=demo-facade]
----

A `XmlDefiner` is also available with the access to the embedded XML Schemas (XSD), the XML Stylesheets (XSLT) to be able to generate the HTML or the PDF content (for DSS specific JAXB) and the JAXB Object Factory.

[source,java,indent=0]
.DetailedReportXmlDefiner usage
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[tags=demo-xml-definer]
----

=== Report stylesheets

The report modules (namely: `dss-simple-report-jaxb`, `dss-simple-certificate-report-jaxb` and `dss-detailed-report-jaxb`) contain two XSLT style sheets each for final reports generation:

 * Bootstrap 4 XSLT for HTML report;
 * PDF XSLT for PDF report.

NOTE: Since DSS 5.9 only Bootstrap 4 XSLT is provided within the framework for HTML report generation.

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

[source,java,indent=0]
.HTML report generation
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/StylesheetSnippet.java[tags=demo]
----

Otherwise, in case if you need to customize the transformer, you can create a report by using an XmlDefiner:

[source,java,indent=0]
.Custom report generation
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/StylesheetSnippet.java[tags=custom]
----

== Alerts

Since DSS 5.7 the framework includes an extended possibility to execute custom processes in case of arbitrary defined events.

The `Alert` is a basic interface used to trigger a process on a passed object.
DSS provides an `AbstractAlert` implementation of the interface with a clearly defined structure. The class must be instantiated with two attributes:

 * `AlertDetector` - used to detect an event/state of the object and trigger a process;
 * `AlertHandler` - defines a process to be executed on an object.

In its basic module, framework provides a few alerts based on a `Status`:

 * `ExceptionOnStatusAlert` - throws an `AlertException` (RuntimeException) when the status reports an issue;
 * `LogOnStatusAlert` - logs a message with the defined log level;
 * `SilentOnStatusAlert` - ignores the reported issue and does nothing.

The usage of alerts is available in the following classes:

 * <<xmlSecurities>> configurators from `dss-jaxb-parsers` module : `TransformerFactoryBuilder`, `SchemaFactoryBuilder`, `ValidatorConfigurator`;
 * <<certificateVerifier>> - to handle the unexpected situation(s) in a custom way (introduced `AlertException` to re-throw exceptions);
 * <<tlValidationJob>> - to process custom actions on change/state on loading of LOTL/TLs (see `LOTLAlert` and `TLAlert`).

== I18N (Internationalization)

Since DSS 5.6 a new module has been introduced allowing changing of a language for reports generated by DSS. The current version of the framework allows customization of text values only for a  `DetailedReport`.

A target language of the report can be set with the following code:

[source,java,indent=0]
.Language customization
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java[tags=i18n]
----

In case if no language is specified, the framework will use a default Locale obtained from OS on a running machine. If a requested language is not found, a default translation will be used.

As a default configuration DSS provides English translation.

In order to provide a custom translation, a new file must be created inside `src\main\resources` directory of your project with a name followed by one of the patterns:

`dss-messages_XX.properties` or
`dss-messages_XX_YY.properties`, where:

 * XX - an abbreviation of a target language;
 * YY - a country code.

For example, for a French language a file with a name `dss-messages_fr.properties` need to be created, or `dss-messages_fr_FR.properties` to use it only in France local.

== Additional features

=== Certificate validation

DSS offers the possibility to validate a certificate. 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 draft standard ETSI TS 119 172-4 (<<R10>>). It analyses the certificate properties (QCStatements, Certificate Policies,...) and applies possible overrules from the related trusted list ("catched" 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 the time, its status is not immutable (eg: a trust service provider lost its granted status). The eIDAS regulation (<<R12>>) clearly defines these different times in the Article 32 and related Annex I.

[source,java,indent=0]
.Validate a certificate and retrieve its qualification level
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/validate/CertificateValidationTest.java[tags=demo]
----

=== SSL Certificate validation (QWAC)

With DSS, that's also possible to validate SSL certificate against the EUMS TL and the ETSI TS 119 615 to determine if it is a Qualified certificate for WebSite Authentication (QWAC).

[source,java,indent=0]
.Validate a SSL certificate and retrieve its qualification level
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/validate/QWACValidationTest.java[tags=demo]
----

=== Extract the signed data from a signature

DSS is able to retrieve the original data from a valid signature.

[source,java,indent=0]
.Retrieve original data from a signed document
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/validate/RetrieveOriginalDocumentTest.java[tags=demo]
----

== REST and SOAP Services

DSS offers REST and SOAP web services. Additionally, we also provide a SOAP-UI project and Postman samples in the `dss-cookbook` module.

The different webservices are :

 * Signature webservices (`dss-signature-soap` / `dss-signature-rest`) and their clients : they expose methods to allow signing and extending or counter-signing a signature from a client.
 * Server-signing webservice (`dss-server-signing-soap` / `dss-server-signing-rest`) and their clients : they expose method to retrieve keys from a server (PKCS#11, PKCS#12, HSM,...) and to sign the digest on the server side.
 * Signature validation webservices (`dss-validation-soap` / `dss-validation-rest`) and their clients : they expose methods to allow signature validation, with an optional detached file and an optional validation policy.
 * Certificate validation webservices (`dss-certificate-validation-soap` / `dss-certificate-validation-rest`) and their clients : they expose methods to allow certificate validation, with an optional provided certificate chain and custom validation time.
 * Timestamp webservices (`dss-timestamp-remote-soap` / `dss-timestamp-remote-rest`) and their clients : they expose methos to allow remote timestamp creation, by providing digest value to be timestamped and a digest algorithm, used for the digets calculation.

The data structure in webservices is similar in both REST and SOAP modules.

The documentation will covers the REST calls. All the REST services present in DSS are compliant with https://www.openapis.org/[OpenAPI Specification].

=== REST signature service

This service exposes 4 methods for one or more document(s) :

[source,java,indent=0]
.Rest signature service
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/RestSignatureServiceSnippet.java[tags=demo]
----

==== 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,...) and the certificate chain.

WARNING: The parameters in getDataToSign and signDocument MUST be the same (especially the signing date).

.Request
include::_restdocs/sign-and-extend-one-document/1/http-request.adoc[]

.Response
include::_restdocs/sign-and-extend-one-document/1/http-response.adoc[]

==== Sign document

The method allows generation of the signed document with the received signature value.

WARNING: The parameters in getDataToSign and signDocument MUST be the same (especially the signing date).

.Request
include::_restdocs/sign-and-extend-one-document/2/http-request.adoc[]

.Response
include::_restdocs/sign-and-extend-one-document/2/http-response.adoc[]

==== Extend document

The method allows extension of an existing signature to a stronger level.

.Request
include::_restdocs/sign-and-extend-one-document/3/http-request.adoc[]

.Response
include::_restdocs/sign-and-extend-one-document/3/http-response.adoc[]

==== Timestamp document

The method allows timestamping of a provided document.
Available for PDF, ASiC-E and ASiC-S container formats.

.Request
include::_restdocs/timestamp-one-document/1/http-request.adoc[]

.Response
include::_restdocs/timestamp-one-document/1/http-response.adoc[]

==== 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()'.

WARNING: The parameters in getDataToBeCounterSigned and counterSignSignature MUST be the same (especially the signing date).

.Request
include::_restdocs/counter-sign-signature/1/http-request.adoc[]

.Response
include::_restdocs/counter-sign-signature/1/http-response.adoc[]

==== Counter Sign Signature

This method incorporates a created counter signature to unsigned properties of the master signature with this specified id.

WARNING: The parameters in getDataToBeCounterSigned and counterSignSignature MUST be the same (especially the signing date).

.Request
include::_restdocs/counter-sign-signature/2/http-request.adoc[]

.Response
include::_restdocs/counter-sign-signature/2/http-response.adoc[]

=== REST server signature service

This service also exposed 4 methods :

[source,java,indent=0]
.Rest server signing service
----
include::{sourcetestdir}/eu/europa/esig/dss/cookbook/example/snippets/RestServerSigningSnippet.java[tags=demo]
----

==== Get keys

This method allows retrieving of all available keys on the server side (PKCS#11, PKCS#12, HSM,...). All keys will have an alias, a signing certificate and its chain. The alias will be used in following steps.

.Request
include::_restdocs/get-keys/1/http-request.adoc[]

.Response
include::_restdocs/get-keys/1/http-response.adoc[]

==== Get key

This method allows retrieving a key information for a given alias.

.Request
include::_restdocs/get-key/1/http-request.adoc[]

.Response
include::_restdocs/get-key/1/http-response.adoc[]

==== Sign

This method allows signing of given digests with a server side certificate.

.Request
include::_restdocs/sign-digest-document-remotely/3/http-request.adoc[]

.Response
include::_restdocs/sign-digest-document-remotely/3/http-response.adoc[]

=== REST validation service

DSS provides also a module for documents validation.

==== Validate a document

This service allows a signature validation (all formats/types) against a validation policy.

.Request
include::_restdocs/validate-doc/1/http-request.adoc[]

.Response
include::_restdocs/validate-doc/1/http-response.adoc[]

==== Retrieve original document(s)

This service returns the signed data for a given signature.

.Request
include::_restdocs/get-original-documents/1/http-request.adoc[]

.Response
include::_restdocs/get-original-documents/1/http-response.adoc[]

=== REST certificate validation service

==== Validate a certificate

This service allows a certificate validation (provided in a binary format).

.Request
include::_restdocs/validate-cert/1/http-request.adoc[]

.Response
include::_restdocs/validate-cert/1/http-response.adoc[]

=== REST remote timestamp service

==== Get Timestamp Response

This 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.

.Request
include::_restdocs/get-timestamp-response/1/http-request.adoc[]

.Response
include::_restdocs/get-timestamp-response/1/http-response.adoc[]