Skip to content

Latest commit

 

History

History
439 lines (278 loc) · 27 KB

signature-creation-different-formats.adoc

File metadata and controls

439 lines (278 loc) · 27 KB

1. Specificities of signature creation in different signature formats

1.1. XAdES (XML)

1.1.1. Versions support

DSS supports the following XAdES formats :

Table 1. Supported XAdES versions
B-level T-level LT-level LTA-level

XAdES 1.1.1

[check circle]

[check circle]

[check circle]

[times circle]

XAdES 1.2.2

[check circle]

[check circle]

[check circle]

[times circle]

XAdES 1.3.2

[check circle]

[check circle]

[check circle]

[check circle]

XAdES 1.4.1

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 :

XAdES formats and prefixes
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[role=include]

1.1.2. 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 a proper digest result. You can find an example of definition reference transformations below:

Custom transformations definition
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[role=include]

Current version of DSS supports the following transformations:

  • EnvelopedSignatureTransform - removes the current Signature element from the digest calculation of the reference.

Warning
 Enveloped Signature Transform does not support parallel signatures! 
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[role=include]

  • CanonicalizationTransform - any canonicalization algorithm that can be used for 'CanonicalizationMethod' can be used as a transform:

link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[role=include]

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

    • Other reference transformations. The reference shall not contain other transforms, the Base64Transform shall be the sole element of the reference transformation;

    • 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 shall also be embedded to the signature;

    • ENVELOPED, DETACHED or INTERNALLY DETACHED packaging.

link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[role=include]

  • XPathTransform - allows signing a custom node 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 by the link.

link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[role=include]

  • XPath2FilterTransform - an alternative to 'XPath Transform'. Additional information about the 'XPath2Filter Transform' can be found by the link. DSS contains an additional class XPath2FilterEnvelopedSignatureTransform allowing to exclude signatures from the digest calculation.

Note
 In DSS, the XPath-2-Filter transform is used by default for ENVELOPED signature packaging. 
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[role=include]

  • XsltTransform - This transform requires a 'org.w3.dom.Document' as an input, compatible with the normative XSLT Specification. Must be a sole transform.

link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignXmlXadesBWithTransformsTest.java[role=include]
Note
 All transformations, except Base64, can be applied only to XML objects.

1.1.3. Specific schema version

Some signatures may have been created with an older version of the XAdES format using different schema definition. To take into account the validation of such signatures the interface eu.europa.esig.dss.xades.definition.XAdESPaths was created. This interface allows providing 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. It is possible to restrict to only one version of XAdES with the following code :

Customize the supported XAdES version(s) at the validation
link:../../../test/java/eu/europa/esig/dss/cookbook/example/validate/XAdES132OnlyTest.java[role=include]

1.2. 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. For an extensive example see section [CAdES] of the Annex.

1.3. PAdES signature (PDF)

The standard ISO 32000-1 (cf. [R06]) allows defining a file format for portable electronic documents (PDF). The standard defines the PDF version 1.7 of Adobe Systems. Concerning the advanced electronic signature, the PAdES standard is used (cf. [R03]).

The DSS implementation supports main operations for PAdES signatures:

  • Adding a digital signature to a document,

  • Providing a placeholder field for signatures,

  • Checking signatures for validity.

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

An example of code to perform a PAdES-BASELINE-B type signature can be found in section [PAdES] of the Annex.

1.3.1. PAdES Visible Signature

The framework also allows creation of PDF files with visible signatures as specified in ETSI EN 319 142 (cf. [R03]). In the PAdESSignatureParameters object, there is a special attribute named SignatureImageParameters. This parameter allows you to customize the visual signature (with text, with image or with image and text). An example of code to perform a PAdES-BASELINE-B type signature with a visible signature can be found in section [PAdESVisibleSignatureAnnex] of the Annex.

Additionally, DSS also allows you to insert a visible signature to an existing field. This is illustrated in section [PAdESVisibleSignatureAnnex] of the Annex.

In case of placing an image or text to an existing field, the visible signature will fill out the whole available area of the field.

1.3.1.1. Visible signature parameters (image and text)

This chapter introduces existing parameters for creation of visible signatures with DSS. DSS has three implementations for visible signature drawing:

  • 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. It transforms text to an image;

  • PDFBox Native - supports separate image and text drawing, as well as a joint drawing of image and text together. It prints text in a native way, that increases quality of the produced signature.

1.3.1.1.1. Positioning

DSS provides a set of functions allowing to place the signature field on a specific place in the PDF page. For an illustrative example see section Positioning in the Annex.

DSS also provide a set of functions to ensure the correctness of a signature field positioning. For more information please see [PdfSignatureFieldPositionChecker] in the Annex.

1.3.1.1.2. Dimensions

DSS framework provides a set of functions to manage the signature field size. See section Dimensions in the Annex for a concrete example.

1.3.1.1.3. Text Parameters

The available implementation allows placing of a visible text in a signature field. See section [TextParameters] in the Annex for a concrete example.

1.3.1.1.4. Text and image combination

DSS provides a set of functions to align a text with respect to an image. The parameters must be applied to a 'SignatureImageTextParameters' object. See section [TextImageCombi] in the Annex for a concrete example.

1.3.1.2. Fonts usage

To customize a text representation a custom font can be defined. The font must be added as an instance of the DSSFont interface to a SignatureImageTextParameters object.

DSS provides the following common implementations for the DSSFont interface:

  • DSSFileFont for use 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 an InputStream of the font file;

  • DSSJavaFont for use 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 that, because of the latter fact, use 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 the PAdES Visible signature service or Operating System (OS) used. Keep this in mind when switching from an implementation or system environment to another.

Additionally, there are implementation-dependent classes:

  • ITextNativeFont to be used with ITextSignatureDrawerFactory;

  • PdfBoxNativeFont to be used with PdfBoxNativeObjectFactory.

You can find an example of how to create a custom font for a physical font, for a logical font and for a native font in section [Fonts].

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

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

1.3.2. PAdES using external CMS provider

Instead of computing a signature value, some signature creation providers implement a service returning a CMS or CAdES signature, enveloping the signed attributes and the user provided message-digest. This architecture may benefit the end-user, as only one request to the external server is required and there is no need to additionally request a signing-certificate or a certificate chain prior the signing.

This design is also suitable for a PAdES signature creation, as the obtained CMS signature may be embedded into PDF with a prepared signature revision. Starting from the version 5.12, DSS exposes a few classes providing a possibility for users to benefit from the aforementioned architecture in order to create PAdES signatures.

The scheme below demonstrates the mechanism of PAdES creation using an external CMS provider:

pades with external cms workflow
Figure 1. PAdES signing using external CMS provider workflow

The scheme demonstrates a workflow between the following independent services implemented in DSS:

  • PAdESWithExternalCMSService is a client-side service, taking a responsibility on PDF processing and preparation of a signature revision. This class should be used when there is direct access to CMS/CAdES signature provider service signing the digest. The class exposes the following methods:

    1. getMessageDigest(pdfDocument, padesSignatureParameters) prepares PDF signature revision and returns message-digest computed on the signature’s byte range (see ISO 32000-1 standard [R06] for more details);

    2. signDocument(pdfDocument, padesSignatureParameters, cmsSignature) envelops CMS signature obtained from external provider within prepared PDF signature revision.

Note
 As the CMS containing signed attributes is obtained externally, the signature parameters provided to the methods of this class should contain only values concerning the creation of a PDF signature revision and do not require a signing-certificate nor certificate chain.

Additionally, the class provides two optional methods allowing verification of a CMS signature received from the external CMS provider, namely:

  1. isValidCMSSignedData(messageDigest, cmsSignature) verifies a cryptographic validity of a CMS signature received from an external signature provider, using the signing-certificate extracted from CMS signature itself;

  2. isValidPAdESBaselineCMSSignedData(messageDigest, cmsSignature) verifies compatibility of a CMS signature received from an external signature provider for a PAdES-BASELINE signature format (cf. [R03]).

Warning
 Please note that not every CMS or CAdES signature is suitable for a PAdES-BASELINE creation. For example a CAdES-BASELINE as per ETSI EN 319 122-1 (cf. [R02]) cannot be used for PAdES-BASELINE as per ETSI EN 319 142-1 (cf. [R03]).

  • ExternalCMSService provides a functionality to expose a server-based service generating a CMS signature suitable for PAdES-BASELINE creation. It exposes the following methods:

    1. getDataToSign(messageDigest, cmsSignatureParameters) computes signed attributes of a CMS signature to be eventually signed using the provided message-digest and signature parameters;

    2. signMessageDigest(messageDigest, cmsSignatureParameters, signatureValue) creates a CMS signature suitable for PAdES-BASELINE conformant signature creation.

  • SignatureTokenConnection represents a remote-signing service exposing methods for a private key signing and signature value creation (see [SignatureTokens] for more details).

Note
 All the services may work independently as well as in collaboration with each other.

An example of a PAdES creation using an external CMS provider using DSS is copied below:

PAdES with external CMS signature provider
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignPdfWithExternalCmsTest.java[role=include]

In case a server-based solution is desired to expose own CMS-creation service for a PAdES-signing, the following approach may be followed accepting a message-digest as the input:

External CMS creation
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignPdfWithExternalCmsTest.java[role=include]

The aforementioned classes and methods are also available as REST/SOAP webservices, see [RestPAdESWithExternalCMS] and [ExternalCMSSignature].

1.3.3. Protected PDF documents

PDF documents may contain certain permission dictionaries defining the allowed scope of actions to be performed on a document, such as signature field creation, filling in existing signature field, etc.

DSS allow configuration of the behaviour on a signature creation, such as restricting changes within PDF documents establishing limitations and allowing them, when required.

The class PdfPermissionsChecker is responsible for configuration of the setup. It handles the following cases/dictionaries establishing the restrictions:

  • Standard encryption dictionaries /Encrypt (as per "7.6.3.2 Standard encryption dictionary" of ISO 32000-1 [R06]) - define a set of permitted operations when a document is opened with user access.

  • DocMDP /DocMDP (as per "12.8.2.2 DocMDP" of ISO 32000-1 [R06]) - defines access and modification permissions granted for a PDF document using a certification signature (see Certification signatures).

  • FieldMDP /FieldMDP (as per "12.8.2.4 FieldMDP" of ISO 32000-1 [R06]) - defines permission issued for modifications within form fields (including signature fields).

  • Signature Lock dictionary /Lock (as per "12.7.4.5 Signature fields" of ISO 32000-1 [R06]) - defines permission for a particular signature field.

Note
 ETSI EN 319 142-1 (cf. [R03]) and ISO 32000-2 (cf. [R28]) allow augmentation of signatures having modification restriction dictionaries, thus supporting the long-term validity preservation mechanism for PDF signatures (e.g. for certification signatures). Therefore, DSS does not invalidate those signatures, nor restricts their augmentation.

A configured instance of the class should be provided to the used IPdfObjFactory. The behaviour has to be defined with a StatusAlert (see [Alerts] for more information):

Restrict signature creation on permission-protected PDF document
link:../../../test/java/eu/europa/esig/dss/cookbook/example/snippets/PAdESWithIPdfObjFactoryConfiguration.java[role=include]
1.3.3.1. Certification signatures

/DocMDP dictionary allows creation of "certification signatures". When used, the dictionary defines a set modification types permitted within a PDF document’s incremental update (see Protected PDF documents for more information). If a validator encounters forbidden modifications within a PDF document, the validation of the certification signature will fail.

DSS allows certification signature creation with one of the following values (see "12.8.2.2 DocMDP" of ISO 32000-1 [R06]):

  • NO_CHANGE_PERMITTED (DocMDP value "1") - No changes to the document are permitted; any change to the document shall invalidate the signature.

  • MINIMAL_CHANGES_PERMITTED (DocMDP value "2") - Permitted changes shall be filling in forms, instantiating page templates, and signing; other changes shall invalidate the signature.

  • CHANGES_PERMITTED (DocMDP value "3") - Permitted changes are the same as for 2, as well as annotation creation, deletion, and modification; other changes shall invalidate the signature.

To create a certification signature, the target modification restriction value shall be provided to the signature parameters on signature creation:

Create a certification signature
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignPdfPadesBTest.java[role=include]

1.4. ISO 32000-1 PDF signature (PKCS#7)

The ISO 32000-1 standard gives a specification for the creation of electronic signatures in the PDF format. However, these signatures are not in the AdES format defined by ETSI.

The Public Key Cryptographic Standard Number 7 (PKCS#7) is a common format of a signature included in a PDF which has been created by Adobe PDF Reader. The PKCS#7 signature format is described in the ISO 32000-1 standard (cf. [R06]) and must conform to the RFC 2315 (cf. [R15]). To familiarize yourself with this type of signature you can read these documents.

DSS only supports AdES formats (e.g. PAdES for PDF) and thus does not support signature creation for PKCS#7. DSS only provides a limited support for the augmentation and validation of PKCS#7 signatures.

There is no specific validation standard for PKCS#7 nor any augmentation formats in the ISO 32000-1 standard. Thus, DSS validates and augments PKCS#7 according to rules defined in ETSI standards. It validates PKCS#7 signatures according to the AdES validation algorithm, and it adds the same components as when augmenting PADES-BASELINE-B to PAdES-BASELINE-T.

1.5. JAdES signature (JWS)

DSS includes a possibility of creation and validation of JSON Advanced signatures (JAdES).

The JSON format for AdES Signatures (cf. [R05]) represents an extension of JSON Web Signatures (JWS) as specified in IETF RFC 7515.

A typical example of a JAdES signature creation can be found in section [JAdES] of the Annex.

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

1.5.1. JWS Serialization type

A JWS signature can be represented in different forms which are supported by the JAdES standard 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 this format.

  • JSON_SERIALIZATION represents a JSON object with a collection of signatures inside the 'signatures' header that allows parallel signing. It allows JAdES-BASELINE-T/-LT/-LTA signature augmentation levels.

  • FLATTENED_JSON_SERIALIZATION represents a JSON object with a single signature container. It allows JAdES-BASELINE-T/-LT/-LTA signature augmentation levels.

JWS Serialization type usage
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignXmlJadesBTest.java[role=include]
Note
 While COMPACT_SERIALIZATION signature type does not support augmentation, it is possible to change a format of existing signature to allow its extension. For that, provide a target JWS signature type within signature parameters on signature extension, for instance use setJwsSerializationType(JWSSerializationType.JSON_SERIALIZATION) to transform the signature to a JSON_SERIALIZATION type and augment it to the target level.

1.5.2. SigD header parameter

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

1.5.2.1. Enveloping packaging

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

1.5.2.2. 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 if it were attached.

To create such a 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 multiple documents within 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).

Configuration for signing with detached mechanism HttpHeaders
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignHttpHeadersJadesBTest.java[role=include]

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

Configuration for signing with detached mechanism ObjectIdByURIHash
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignMultipleDocumentsJadesTTest.java[role=include]

1.5.3. Base64Url encoding

The Base64Url represents a Base64 encoded format with URI safe alphabet (see RFC 4648).

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

DSS provides options to configure encoding for the following elements:

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

Use unencoded JWS Payload
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignHttpHeadersJadesBTest.java[role=include]

  • 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.
Represent EtsiU components as clear JSON instances
link:../../../test/java/eu/europa/esig/dss/cookbook/example/sign/SignMultipleDocumentsJadesTTest.java[role=include]

1.6. ASiC signature (containers)

The ETSI EN 319 162 standard (cf. [R04]) offers a standardized use of container forms to establish a common way for associating data objects with advanced signatures or time-stamp tokens. It is an alternative to the packaging types presented in section [Packaging].

A number of application environments use ZIP-based container formats to package sets of files together with meta-information. ASiC technical specification is designed to operate with a range of such ZIP-based application environments. Rather than enforcing a single packaging structure, ASiC describes how these package formats can be used to associate advanced electronic signatures with any data objects.

The standard defines two types of containers:

  • ASiC-S is a simple container that allows you to associate one or more signatures with a single data element (zip-container). 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;

  • ASiC-E is an extended container that includes multiple data objects. Each data object may be signed by one or more signatures whose structure is similar to ASiC-S. This second type of container is compatible with OCF, UCF and ODF formats.

DSS framework has some restrictions on the containers you can generate, depending on the input file. If the input file is already an ASiC container, the output container must be the same type of container based on the same type of signature. If the input is any other file, the output does not have any restriction.

Table 2. 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

Typical examples of the source code for signing a document using ASiC-S based on XAdES-BASELINE-B and ASiC-E based on XAdES-BASELINE-B can be found in sections [ASiC-S] and [ASiC-E] respectively.

You need to pass only few parameters to the service. Other parameters, although they are positioned, will be overwritten by the internal implementation of the service. Therefore, the obtained signature is always based on the DETACHED packaging no matter the packaging that was specified.

It is also possible with the DSS framework to make an augmentation of an ASiC container to the levels BASELINE-T, BASELINE-LT or BASELINE-LTA, respectively for XAdES and CAdES formats.