annex.adoc

1. Annex

1.1. Use of Alerts throughout the framework

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:

• XML securities configurators from dss-jaxb-parsers module : TransformerFactoryBuilder, SchemaFactoryBuilder, ValidatorConfigurator (see chapter [xmlSecurities] for more information);

• CertificateVerifier - to handle the unexpected situation(s) in a custom way (introduced AlertException to re-throw exceptions, see section [certificateVerifier] for more information);

• TLValidationJob - to process custom actions on change/state on loading of LOTL/TLs (see LOTLAlert and TLAlert in the [AlertingTL] section).

1.2. Configuration of validation policy in different use cases

dss-policy.adoc

[.portrait] <<< ==== AdES validation According to ETSI EN 319 102-1 (cf. [R09]), the signature validation process can be separated to different levels: * Validation process for basic signatures - validates the signature at the validation (current) time; * Validation process for Signatures with Time and Signatures with Long-Term Validation Material - verifies the signature against its best-signature-time (i.e. against the signature time-stamp’s production time); * Validation process for Signatures providing Long Term Availability and Integrity of Validation Material - verifies the signature with all available Long-Term Availability material (i.e. including the validation of archive time-stamps). DSS allows the user to choose the validation level when performing a signature validation, i.e. to specify the validation process to be used for validation (cf. [R09]). By default, the highest level (with LTA enabled) is used. ===== Basic AdES validation Below you can find a signature validation example with a basic signature validation level: [source,java,indent=0] .B-level AdES validation ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/validate/SignatureLevelValidationTest.java ---- ===== Long Term AdES validation [source,java,indent=0] .LTV-level AdES validation ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/validate/SignatureLevelValidationTest.java ---- ===== Long Term Availability AdES validation [source,java,indent=0] .LTA-level AdES validation ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/validate/SignatureLevelValidationTest.java ---- ==== Trusted list validation A validation of a Trusted List is similar to a signature validation, with the only difference that the validation of a Trusted List can be done in offline mode. Additionally, a validation against the XSD schema should be performed. [source,java,indent=0] .Validation of a trusted list ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignTrustedListTest.java ---- === Caching use cases ==== Caching revocation data (CRL, OCSP) ===== CRL An example for JdbcCacheCRLSource: [source,java,indent=0] .JdbcCacheCRLSource usage ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/CRLSourceSnippet.java ---- ===== OCSP An example for JdbcCacheOCSPSource: [source,java,indent=0] .JdbcCacheOCSPSource usage ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/OCSPSourceSnippet.java ---- ==== Caching certificates (AIA certificates) An example for JdbcCacheOCSPSource: [source,java,indent=0] .Caching of certificates ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/AIASourceSnippet.java ---- ==== Caching trusted lists Trusted Lists and List(s) of Trusted Lists are cached automatically as a part if TLValidationJob (see [tlValidationJob]). To configure it you may use FileCacheDataLoader (see [DSSFileLoader]). To load Trusted Lists from a cache, the offline loader shall be configured, and the action can be performed with the method: [source,java,indent=0] .Trusted Lists update from a cache ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/TLValidationJobSnippets.java ---- === Complete examples of Signature creation ==== XAdES Below is an example of the XAdES-Baseline-B signature signing an XML document: [source,java,indent=0] .Create a XAdES-BASELINE-B signature ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBTest.java ---- ==== CAdES Below is an example of the CAdES-Baseline-B signature: [source,java,indent=0] .Signing a file with CAdES ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignXmlCadesBTest.java ---- ==== PAdES Below is an example of code to perform a PAdES-BASELINE-B type signature: [source,java,indent=0] .Signing a PDF file with PAdES ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBTest.java ---- ===== PAdES Visible Signature DSS provides a large set of utilities for PDF visible signature creation (see [PAdESVisibleSignature] for more information). 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 ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java ---- 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 ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java ---- The following sections present examples of existing parameters for creation of visible signatures with DSS. ====== 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 ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/PAdESVisibleSignatureSnippet.java ---- ====== Signature Field Position Checker In certain cases it is beneficial to ensure validity of a position for a newly created signature field, in particular to verify if the signature field lies within the borders of a PDF page and/or it does not cover other existing signature field(s). To set up the behavior, DSS provides PdfSignatureFieldPositionChecker class, a configured instance of which should be provided within a used IPdfObjFactory object in a PAdESService. It can be configured as in the example below: [source,java,indent=0] .Ensure validity of a signature field position ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/PAdESWithIPdfObjFactoryConfiguration.java ---- For more information about configuration with alerts please see Use of Alerts throughout the framework section. ====== Dimensions DSS framework provides a set of functions to manage the signature field size : [source,java,indent=0] .Visible signature dimensions ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/PAdESVisibleSignatureSnippet.java ---- ====== 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 ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java ---- ====== 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 ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java ---- The result of applying the foregoing transformations is provided on the image below: image::visual-sig-text-parameters.jpg[] ====== Fonts usage You can create a custom font as following, for a physical font: [source,java,indent=0] .Add a custom font as a file ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleTest.java ---- For a logical font: [source,java,indent=0] .Java font usage ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBVisibleExistingTest.java ---- For a native font: [source,java,indent=0] .Native font usage ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/PAdESVisibleSignatureSnippet.java ---- ==== JAdES A typical example of a JAdES-BASELINE-B signature creation is represented below: [source,java,indent=0] .Signing a file with JAdES ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignXmlJadesBTest.java ---- ==== ASiC ===== ASiC-S This is an example of the source code for signing a document using ASiC-S based on XAdES-BASELINE-B profile: [source,java,indent=0] .Sign a file within an ASiC-S container ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignOneFileWithASiCSBTest.java ---- ===== ASiC-E This is another example of the source code for signing multiple documents using ASiC-E based on CAdES-BASELINE-B: [source,java,indent=0] .Sign multiple files within an ASiC-E container ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignMultipleDocumentsWithASiCSEWithCAdESTest.java ---- === Examples of SCA and SCDev Topology and Workflows ==== Hash computation In order to avoid transfer of original or sensitive information, and also to reduce the amount of data by online protocols, a hash of a document or data to be signed can be computed. [source,java,indent=0] .Hash computation ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/Snippets.java ---- ==== Detached signature based on digested document When you want to keep your original documents private, a signature can be created in a detached way, by providing the digest of an original document only. You can find an example of a use case below: [source,java,indent=0] .Detached signature based on digested document ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignDetachedDocumentTest.java ---- ==== Client-side signature creation with server-side remote key activation When a private key signing is operated remotely, i.e. on an external server, then the document preparation and the actual signing can be separated. The signature document is created on client’s side and the actual signature is made remotely. Refer to section [ClientServerSeparation] for a detailed description and visual illustration of the steps that take place in such a situation. See the code below for a code illustration: [source,java,indent=0] .Creation of the signature envelope on client side and signature value on server side ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/ServerSignTest.java ---- === Interpreting a detailed report We will illustrate here how to read a detailed validation report where the validation succeeds even though the signing certificate has been revoked. This will illustrate how to look up at which check failed and how the overall validation process can succeed even when a sub-process failed. First, as explained in [DetailedReport] the structure of the detailed validation report is based on ETSI EN 319 102-1 ([R09]). This means that the detailed report is structured in terms of: * Validation processes; and * Building blocks. There are three validation processes specified in ETSI EN 319 102-1: * The Validation process for Basic Signatures; * The Validation process for Signatures with Time and Signatures with Long-Term Validation Material; * The Validation process for Signatures providing Long Term Availability and Integrity of Validation Material, abbreviated in the report as "Validation Process for Signatures with Archival Data". Those validation processes in turn rely on building blocks, which are denoted in ETSI EN 319 102-1 as: * The basic building blocks; * The time-stamp validation building block; * The additional building blocks. DSS groups the basic building blocks and the additional building blocks related to the validation of a particular signature together. However, it separates the time-stamp validation builiding block from the rest and present it alongside the validation processes because this building block essentially consists in applying the validation process for basic signatures to a timestamp token taken as a CMS object. Now let’s see how this looks in a validation report (we use here the HTML representation provided by the demonstration). First, as mentioned, are the validation processes and the time-stamp validation building block, which are numbered in the figure below with: . The validation process for Basic Signatures; . The time-stamp building block in which appears the validation process of the timestamp; . The validation process for Signatures with Time and Signatures with Long-Term Validation Material; . The validation process for Signatures with Archival Data. image::DetailedReport-Illustration-SigProcesses.png[width="100%", height="100%", align="center"] As further illustrated in the figure above: * The validation process for Basic signature is executed against the first time which is the (current) validation time; * The validation process for Signatures with Time and Signatures with Long-Term Validation Material is executed against a second time which is the "best signature time" that is determined using the signature timestamp; * The validation process for Signatures with Archival Data is executed against a third time which is the "best signature time" determined using all time assertions present in the signature. Additionally, each process has an associated indication, here: . REVOKED_NO_POE for the validation process for basic signatures; . PASSED for the timestamp validation block; . PASSED for the validation process for Signatures with Time and Signatures with Long-Term Validation Material; . PASSED for the validation process for Signatures with Archival Data. Each of those indications is determined using the result of the associated building blocks, and applying additional checks. Here we can see that the REVOKED_NO_POE indication arises from the fact that the result of the "X.509 Certificate Validation" building block is not conclusive. Now delving into the building blocks themselves, we can see in the figure below that the building blocks are grouped by the signed objects to which they relate: * BBB SIG are the building blocks used for the validation of the signature itself; * BBB TIMESTAMP are the building blocks used for the validation of the timestamp; * BBB REVOCATION DATA are the building blocks used for the validation of the OCSP responses taken as CMS objects. image::DetailedReport-Illustration-BB.png[width="100%", height="100%", align="center"] We saw previously that the "validation process for basic signature" resulted in the REVOKED_NO_POE indication because the result of the "X.509 Certificate Validation" building block was not conclusive. To check what went wrong, we must therefore look at the "X.509 Certificate Validation" building block associated to the signature, that is the "X.509 Certificate Validation" building block that is in BBB SIG. We see there that the check "Is the certificate validation conclusive?" has failed. Therefore, we now need to look at the "Certificate" sub-block of BBB SIG. In the "Certificate" sub-block we can see that all checks succeeded except for "Is the certificate not revoked?". We can thus conclude that the validation process for basic signature resulted in the indication REVOKED_NO_POE because the signing certificate is revoked at validation time. That being said, we saw before that although the validation process for basic signature failed with REVOKED_NO_POE, the other validation processes resulted in the PASSED indication. And in fact, the overall result of the validation process is TOTAL_PASSED. To understand why that is so, we need to look back at the signature validation processes. There we can see in the "validation process for Signatures with Time and Signatures with Long-Term Validation Material" that specific checks differing from the building blocks are executed. Which checks are executed depends on the indication determined during the "validation process for basic signatures". In the present case, because the indication was REVOKED_NO_POE the specific check "Is the revocation time after best-signature-time" is executed. As mentioned before, best-signature-time is determined, for that validation process, using the signature timestamp. Because here the validation of the signature timestamp succeeded, the time indicated in the timestamp is used as best-signature-time, and because this time is indeed before the time of revocation of the signing certificate, the check succeeds, and the whole "validation process for Signatures with Time and Signatures with Long-Term Validation Material" succeeds. Now to understand why the overall result of the validation is TOTAL_PASSED, we need to go back to the procedures specified in ETSI EN 319 102-1 (cf. [R09]). The three validation processes specified in that standard are in fact not independent: * The "validation process for Signatures providing Long Term Availability and Integrity of Validation Material" calls the "validation process for Signatures with Time and Signatures with Long-Term Validation Material"; and * The "validation process for Signatures with Time and Signatures with Long-Term Validation Material" itself calls the "validation process for basic signatures". The overall validation result is then provided as the indication returned by the validation process against which the validation was performed. Although it is possible to only run the validation process for basic signature, in our case the process that was run was the "validation process for Signatures providing Long Term Availability and Integrity of Validation Material" which required to run the other two validation processes. Therefore, because that validation process returned PASSED, the overall validation result is TOTAL_PASSED. Finally, the report contains information on the determination of the qualification of the signature. image::DetailedReport-Illustration-Qualification.png[width="100%", height="100%", align="center"] This determination is not specified in ETSI EN 319 102-1 ([R09]), but rather in ETSI TS 119 172-4 ([R10]). Essentially, a signature can be determined as qualified if: . The result of running the "validation process for Signatures providing Long Term Availability and Integrity of Validation Material" defined in ETSI EN 319 102-1 is TOTAL_PASSED; . The signing certificate is determined as qualified at best-signature-time and at issuance time (the time when the certificate was issued i.e. the value of the "notBefore" field); . The private key corresponding to the signing certificate is determined as being held in a qualified signature creation device (QSCD). We discussed above the validation processes defined in ETSI EN 319 102-1. The determinations of point 2 and 3 on the other hand rely on the procedures specified in ETSI TS 119 615 ([R14]). Without going into details, ETSI TS 119 615 specifies procedures for interpreting the content of EUMS trusted lists, including procedures for validating EUMS trusted lists. Illustrated in the figure above are the results of the main steps defined in that standard. === ASiC Merger Since DSS v5.11 the framework provides a possibility to merge ASiC containers of the same type (e.g. ASiC-E with XAdES merge with another ASiC-E with XAdES). This can benefit from creating signature containers in parallel by different users and/or on different machines and finally merging them after obtaining all signatures, without breaking the cryptographical validity of signatures. The possibility is provided with introduction of DefaultContainerMerger class that chooses a relevant implementation of ASiCContainerMerger based on the provided containers types, evaluates a technical possibility to execute the merge and creates the merged container, when possible. [source,java,indent=0] .Sign multiple files within an ASiC-E container ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignTwoAsicAndMergeTest.java ---- The following implementations of ASiCContainerMerger are provided within the framework: * ASiCSWithXAdESContainerMerger - a part of dss-asic-xades module. The class supports a merging of ASiC-S with XAdES containers, containing the same signed data. * ASiCEWithXAdESContainerMerger - a part of dss-asic-xades module. The class supports a merging of ASiC-E with XAdES containers, including merging of containers signing a different set of signed data. * ASiCSWithCAdESContainerMerger - a part of dss-asic-cades module. The class supports a merging of ASiC-S with CAdES containers, containing the same signed data. * ASiCEWithCAdESContainerMerger - a part of dss-asic-cades module. The class supports a merging of ASiC-E with CAdES containers, including merging of containers signing/timestamping a different set of signed data, provided that signature/timestamp document names are different. NOTE: The merging classes are able to resolve conflicts between container entries, when feasible. If the extension is not possible, a corresponding exception will be thrown. In order to use a selected class, the corresponding module shall be loaded within the project. DefaultContainerMerger will choose a relevant implementation across available modules using [ServiceLoaderAdvanced]. When using provided implementations of the ASiCContainerMerger, a user can also benefit from merging a corresponding ASiC container with a simple not-signed ZIP archive, or even from merging not signed ZIP archives. === ASiC Filename Factory In order to customize file naming within ASiC containers, DSS introduces ASiCWithXAdESFilenameFactory and ASiCWithCAdESFilenameFactory (for ASiC with XAdES and CAdES, respectively), allowing customization of the created files, such as signature, manifest, timestamp and other documents. For each container entry being created, the underlying service is making a call to the factory providing the current content of an ASiC container using an ASiCContent object. Based on the defined rules within a factory, it returns a valid file name for the current container. The following implementations are provided within DSS framework: * DefaultASiCWithXAdESFilenameFactory/DefaultASiCWithCAdESFilenameFactory (for XAdES and CAdES, respectively) - the default implementation used in DSS code, providing a user-friendly filename, conformant to EN 319 162 (cf. [R04]) (e.g. META-INF/signatures001.xml). * SimpleASiCWithXAdESFilenameFactory/SimpleASiCWithCAdESFilenameFactory (for XAdES and CAdES, respectively) - allows definition of custom document names, using corresponding setters. The factories verify the conformance of the defined names according to EN 319 162 (cf. [R04]), when applicable. NOTE: When using SimpleASiCWithXAdESFilenameFactory or SimpleASiCWithCAdESFilenameFactory, the name of signature, manifest or timestamp files may be defined without META-INF/ directory prefix. The factory will add the required directory to the filename, when applicable. Below you can find an example of a SimpleASiCWithXAdESFilenameFactory use within an ASiCWithXAdESService for a container signature creation with a custom filename: [source,java,indent=0] .SimpleASiCWithXAdESFilenameFactory use for a a custom signature filename ---- ../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignASiCWithSimpleFilenameFactoryTest.java ----