DSS incorporates modules that are loaded in the run time based on the chosen configuration and the input data via a ServiceLoader. This provides a flexibility for an end-user to work only with selected modules and a possibility to expand DSS with custom implementations.
In order to provide a chosen implementation(s) to 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).
It is also possible to customize the order of the used implementation, but creating a corresponding file in META-INF/services directory within your project.
|
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:
-
DSS Utils;
-
DSS CRL Parser;
-
DSS PAdES.
|
Warning
|
At least one implementation shall be chosen. |
The module dss-utils offers an interface with utility methods to operate on String, Collection, I/O, etc. 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 uses Google Guava (recommended on Android).
If your integration includes dss-utils, you will need to select an implementation. For example, to choose the dss-utils-apache-commons implementation within a Maven project you need to define the following:
<dependency>
<groupId>eu.europa.ec.joinup.sd-dss</groupId>
<artifactId>dss-utils-apache-commons</artifactId>
</dependency>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 theX509CRLjava object. -
dss-crl-parser-streams: this module offers an alternative with a CRL streaming.
If your integration requires dss-crl-parser, you will need to choose your implementation. For example, to choose the dss-crl-parser-streams implementation within a Maven project you need to define the following:
<dependency>
<groupId>eu.europa.ec.joinup.sd-dss</groupId>
<artifactId>dss-crl-parser-stream</artifactId>
</dependency>DSS allows generation, augmentation and validation of 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: PAdES implementation based on Apache PDFBox. Supports drawing of custom text, images, as well as text+image, in a signature field. -
dss-pades-openpdf: PAdES implementation based on OpenPDF (fork of iText). 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 theSignatureDrawerdepending on theSignatureImageParameterscontent); -
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 allows switching between two implementations of the PDFBox framework: default (original) and native.
-
Native Drawer: A native implementation of PDFBox Drawer, allowing a user to add a vector 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, but also clearer and smoother in comparison with the raster implementation.
-
Default Drawer: The original drawer implemented on the PDFBox framework, supports displaying of custom text, images, but also text and 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).
By default, DSS uses the "Native Drawer" as the PDFBox implementation. In order to switch the implementation, that allowed at runtime, you have to set a new instance for PdfObjFactory as following:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java[role=include]Or create a new file META-INF/services/eu.europa.esig.dss.pdf.IPdfObjFactory within project’s resources, defining the desired implementation (see ServiceLoader for more information).
This implementation is based on the OpenPDF framework. DSS provides two drawers using the implementation:
-
TextOnlySignatureDrawer- to draw a vector text information within a signature field. The text information is selectable and searchable. -
ImageOnlySignatureDrawer- to draw an image within a signature field.
|
Warning
|
DSS provides a limited support of OpenPDF framework, therefore not all features are supported (e.g. text+image drawing). |
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, etc.). 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.
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 certificates that are not present. These certificates are not necessarily trusted and may require future "modifications" like revocation data collection, etc.
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.
See section [CachingUseCases] of the Annex for complete examples of caching revocation data, certificates and trusted lists.
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 (e.g. marshall, unmarshall, generate the HTML/PDF, validate the XML structure, etc.).
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[role=include]An 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.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/SignedDocumentValidatorTest.java[role=include]It is possible to programmatically create or/and edit an XML Trusted List using the JAXB module.
Below is an example of how to use JAXB modules to create a trusted list (not complete solution):
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/CreateTLSnippet.java[role=include]And an example how to modify an existing Trusted List (e.g. change its version):
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/CreateTLSnippet.java[role=include]You can also use JAXB modules not only for the content creation or changing, but also in order to verify the conformity of an XML document against its XSD schema.
For example, in order to validate a XAdES signature conformance against 1.3.2 XSD schema, you can use the corresponding class XAdES319132Utils:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBPropertiesTest.java[role=include]The report modules (namely: dss-simple-report-jaxb, dss-simple-certificate-report-jaxb and dss-detailed-report-jaxb) contain 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):
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/StylesheetSnippet.java[role=include]Otherwise, in case you need to customize the transformer, you can create a report by using an XmlDefiner:
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/StylesheetSnippet.java[role=include]The dss-diagnostic-jaxb module contains an XSLT stylesheet that creates an SVG image from an XML document in order to visually represent the signature at validation time.
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/SVGGenerationSnippet.java[role=include]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.DocumentBuilderFactorywith aDocumentBuilderFactoryBuilder- builds a DOM document object from the obtained XML file and creates a neworg.w3c.dom.Document; -
javax.xml.transform.TransformerFactorywith aTransformerFactoryBuilder- loads XML templates and builds DOM objects; -
javax.xml.validation.SchemaFactorywith aSchemaFactoryBuilder- loads XML Schema; -
javax.xml.validation.Validatorwith aValidatorConfigurator- 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):
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/XMLSecuritiesConfigTest.java[role=include]The javax.xml.parsers.DocumentBuilderFactory, that allows XML files parsing and creation of DOM org.w3c.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.
|
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/XMLSecuritiesConfigTest.java[role=include]The class XmlDefinerUtils is a singleton, therefore all changes performed on the instance will have an impact to all calls of the related methods.
See section [Alerts] in chapter Annex for more information on alerts.