signature-creation.adoc

1. Signature creation

1.1. AdES specificities

1.1.1. Existing formats

The different digital signature formats make it possible to cover a wide range of real life use cases of this technique. Thus, we distinguish the following formats:

• XAdES - for XML Advanced Electronic Signatures (cf. [R01]);

• CAdES - for CMS Advanced Electronic Signatures (cf. [R02]);

• PAdES - for PDF Advanced Electronic Signatures (cf. [R03]);

• JAdES - for JSON Advanced Electronic Signatures (cf. [R05]);

• ASIC - for Associated Signature Containers (cf. [R04]). XAdES and CAdES combinations are possible.

1.1.2. Signature profiles

The eIDAS Regulation (910/2014) sets the legal framework for electronic signatures in the European Union. It defines who can use electronic signatures and in what context. To ensure that electronic signatures can be created and validated anywhere in Europe, a number of standards were identified for their implementation.

To ensure cross-border interoperability the eIDAS Regulation through the Commission Implementing Decision (EU) 2015/1506 (cf. [R16]) specifies minimum formats of advanced electronic signatures and advanced seals to be recognised by member states. It defines a number of baseline profiles:

• XAdES Baseline Profile: ETSI TS 103171 v.2.1.1;

• CAdES Baseline Profile: ETSI TS 103173 v.2.2.1;

• PAdES Baseline Profile: ETSI TS 103172 v.2.2.2;

• ASiC Baseline Profile: ETSI TS 103174 v.2.2.1.

The baseline profile for a certain signature format provides the basic features required to assure interoperability in the EU for that format. Each baseline profile defines four different levels that correspond to the four signature classes described in the ETSI standard EN 319 102-1 (cf. [R09]) and which are described in the following section.

Before the introduction of the baseline profiles, old extended profiles were used. Below is a comparative table of old extended profiles and new baseline profiles for each signature format:

Table 1. Signature supported profiles

XAdES		CAdES		PAdES		JAdES
EXTENDED	BASELINE	EXTENDED	BASELINE	EXTENDED	BASELINE	BASELINE
XAdES-E-BES	XAdES-B-B	CAdES-E-BES	CAdES-B-B	PAdES-E-BES	PAdES-B-B	JAdES-B-B
XAdES-E-EPES		CAdES-E-EPES		PAdES-E-EPES
XAdES-E-T	XAdES-B-T	CAdES-E-T	CAdES-B-T		PAdES-B-T	JAdES-B-T
XAdES-E-C		CAdES-E-C
XAdES-E-X		CAdES-E-X
XAdES-E-X-L	XAdES-B-LT	CAdES-E-X-L	CAdES-B-LT		PAdES-B-LT	JAdES-B-LT
XAdES-E-A	XAdES-B-LTA	CAdES-E-A	CAdES-B-LTA	PAdES-E-LTV	PAdES-B-LTA	JAdES-B-LTA

The DSS framework is compatible with the baseline profiles. However, it is not possible to use the extended profiles for signing purpose except for XAdES-E-A/C/X/XL. The validation of the signature has a basic support of old profiles.

1.1.3. Signature classes/levels

The ETSI standard EN 319 102-1 (cf. [R09]) defines four conformance classes to address the need to protect the validity of the signature in time. Henceforth, to denote the class of the signature the word "level" will be used. Follows the list of profiles implementing the four classes defined in the standard:

• AdES-BASELINE-B: Profile implementing the signature class Basic Signature
  The lowest and simplest version containing at least a signature value, a reference to or a copy of the signing certificate as a signed attribute, and optionally other signed or unsigned attributes.

• AdES-BASELINE-T: Profile implementing the signature class Signature with time
  A timestamp regarding the time of signing is added to protect against repudiation.

• AdES-BASELINE-LT: Profile implementing the signature class Signature with Long-Term Validation Material
  All the material or references to material required for validating the signature are embedded to allow verification in future even if their original source is not available. For example, 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".

• AdES-BASELINE-LTA: Profile implementing the signature class Signature providing Long Term Availability and Integrity of Validation Material
  By using periodical timestamping (e.g. each year), the availability or integrity of the validation data is maintained. The validity could be limited due to cryptographic obsolescence of the algorithms, keys and parameters used, or due to expiration or revocation of the validation material. The AdES-BASELINE-LTA augmentation 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 valid at the time when the used cryptographic algorithms were considered safe. Additional validation data can be included too.

Note	The use of extended profiles on signature creation, such as -E-C, -E-X, -E-XL, -E-A, is supported only for XAdES.

The following schema from the ETSI standard EN 319 102-1 (cf. [R09]) illustrates the different classes.

1.1.4. Signature packaging

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.

The choice is not obvious, because in one case the signature will alter the signed document and in the other case it is possible to lose the association between the signed document and its signature.

The following types of packaging can be defined for various signature formats:

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

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

More information about packaging use in combination with available formats can be found in the Signature profile guide.

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

Table 2. File formats and Signature types conformance

Signature profiles			XML	JSON	PDF	Binary	Digest	Multiple files	Multiple signatures	Augmentation BASELINE-T+	Counter signature	Stand-alone timestamp
XAdES	Enveloping	Base64 encoded	[check circle]	[check circle]	[check circle]	[check circle]	[times circle]	[check circle]	[times circle]	[check circle]	[check circle]	[times circle]
		Embed XML	[check circle]	[times circle]	[times circle]	[times circle]	[times circle]	XML only	[times circle]	[check circle]	[check circle]	[times circle]
		Manifest	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[times circle]	[check circle]	[check circle]	[times circle]
		Canonicalization	[check circle]	[times circle]	[times circle]	[times circle]	[times circle]	XML only	[times circle]	[check circle]	[check circle]	[times circle]
	Enveloped	enveloped transformation	[check circle]	[times circle]	[times circle]	[times circle]	[times circle]	[times circle]	[times circle]	[check circle]	[check circle]	[times circle]
		based on XPath	[check circle]	[times circle]	[times circle]	[times circle]	[times circle]	[times circle]	[check circle]	[check circle]	[check circle]	[times circle]
		based on Filter2	[check circle]	[times circle]	[times circle]	[times circle]	[times circle]	[times circle]	[check circle]	[check circle]	[check circle]	[times circle]
		Canonicalization	[check circle]	[times circle]	[times circle]	[times circle]	[times circle]	XML only	[check circle]	[check circle]	[check circle]	[times circle]
	Detached		[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[times circle]	[check circle]	[check circle]	[times circle]
	Internally Detached		[check circle]	[times circle]	[times circle]	[times circle]	[times circle]	XML only	[check circle]	[check circle]	[check circle]	[times circle]
CAdES	Enveloping		[check circle]	[check circle]	[check circle]	[check circle]	[times circle]	[times circle]	[check circle]	[check circle]	[check circle]	[times circle]
	Detached		[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[times circle]	[check circle]	[check circle]	[check circle]	[times circle]
PAdES	Enveloped		[times circle]	[times circle]	[check circle]	[times circle]	[times circle]	[times circle]	[check circle]	[check circle]	[times circle]	[check circle]
JAdES	Enveloping	Compact Serialization	[check circle]	[check circle]	[check circle]	[check circle]	[times circle]	[times circle]	[times circle]	[check circle]	[times circle]	[times circle]
		Flattened JSON Serialization	[check circle]	[check circle]	[check circle]	[check circle]	[times circle]	[times circle]	[times circle]	[check circle]	[check circle]	[times circle]
		JSON Serialization	[check circle]	[check circle]	[check circle]	[check circle]	[times circle]	[times circle]	[check circle]	[check circle]	[check circle]	[times circle]
	Detached	Compact Serialization	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	SigD only	[times circle]	[check circle]	[times circle]	[times circle]
		Flattened JSON Serialization	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	SigD only	[times circle]	[check circle]	[check circle]	[times circle]
		JSON Serialization	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	SigD only	[check circle]	[check circle]	[check circle]	[times circle]
ASiC	ASiCS	CAdES / XAdES	[check circle]	[check circle]	[check circle]	[check circle]	[times circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]
	ASiCE	CAdES / XAdES	[check circle]	[check circle]	[check circle]	[check circle]	[times circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]

1.1.5. Signature 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.

Table 3. Supported algorithms

	SHA-1	SHA-224	SHA-256	SHA-384	SHA-512	SHA3-224	SHA3-256	SHA3-384	SHA3-512	SHAKE256-512	MD2	MD5	RIPEMD160
RSA
XAdES	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]							[check circle]	[check circle]
CAdES	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]		[check circle]	[check circle]	[check circle]
JAdES			[check circle]	[check circle]	[check circle]
RSA-PSS
XAdES	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]
CAdES	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]
JAdES			[check circle]	[check circle]	[check circle]
ECDSA
XAdES	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]								[check circle]
CAdES	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]
JAdES			[check circle]	[check circle]	[check circle]
Ed25519
XAdES					[check circle]
CAdES					[check circle]
JAdES					[check circle]
Ed448
XAdES										[check circle]
CAdES										[check circle]
JAdES										[check circle]
DSA
XAdES	[check circle]		[check circle]
CAdES	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]
HMAC
XAdES	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]								[check circle]
CAdES	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]	[check circle]
JAdES			[check circle]	[check circle]	[check circle]

1.2. Representation of documents in DSS

DSS allows creation of different kinds of DSSDocument :

• InMemoryDocument : fully loads the document in memory. This type of DSSDocument can be instantiated with an array of bytes or an InputStream.

• FileDocument : created from an existing local file.

• DigestDocument : only contains pre-computed digest values for a given document. That allows a user to avoid sending the full document (detached signatures).

• CMSSignedDocument : an internal implementation of a DSSDocument, loading a CMS Signed Data object.

• HTTPHeader : represents an HTTP Header used as a signed object within a JAdES implementation (see JAdES Detached Packaging).

• HTTPHeaderDigest : represents an HTTP body message’s digest to be used as a signed HTTP Header within JAdES Detached Packaging. The object is built from another DSSDocument (e.g. from binaries, digest document, etc.);

• ContainerEntryDocument : represents a container entry, containing metadata about the document;

• FileArchiveEntry : internal implementation, used to increase performance when reading a ZIP archive from file system.

InMemoryDocument

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

FileDocument

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

DigestDocument

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

CMSDocument

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

HTTPHeader and HTTPHeaderDigest

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

ContainerEntryDocument

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

1.3. Signature tokens

The DSS framework is able to create signatures using different keystores: PKCS#11, PKCS#12, JKS, MS CAPI and Apple Keystore. To be independent of the signing media, the DSS framework uses an interface named SignatureTokenConnection to manage different implementations of the signing process. All token implementations provided within the framework extend the AbstractSignatureTokenConnection abstract class that allows executing complete signature operation (digest and encryption on the token) or raw signature operation (external digest and encryption on the token).

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

1.3.1. Available implementations

The following implementations are provided within the framework:

• Pkcs11SignatureToken - for accessing smart cards or HSMs;

• Pkcs12SignatureToken - for accessing PKCS#12 (.p12) keystore;

• MSCAPISignatureToken - for accessing Microsoft keystore (e.g. on Windows OS);

• AppleSignatureToken - for accessing Keychain store in a MacOS environment;

• JKSSignatureToken - for accessing a Java KeyStore (i.e. .jks).

More information about each available implementations may be found below.

1.3.1.1. 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. It requires some installed drivers (dll, sso, etc.).

Pkcs11SignatureToken usage

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

1.3.1.2. PKCS#12

This standard defines a file format commonly used to store the private key and corresponding public key certificate protecting them with a password. It allows signing with a PKCS#12 keystore (.p12 file). In order to use this format with the DSS framework you have to go through the class Pkcs12SignatureToken.

Pkcs12SignatureToken usage

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

1.3.1.3. MS CAPI

If the middleware for communicating with an SCDev provides a CSP based on MS CAPI (the Microsoft interface to communicate with SmartCards) specification, then you can use the MSCAPISignatureToken class to sign the documents.

MSCAPISignatureToken usage

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

1.3.1.4. Apple Keystore

Since DSS 5.10 a new class AppleSignatureToken is provided within the source code allowing to access a Keychain store in a MacOS environment.

Warning

The API does not access keys from a smartcard, as opposite to the MS CAPI implementation.

AppleSignatureToken usage

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

1.3.1.5. Java Key Store

The JKSSignatureToken class allows signing with a Java Key Store (.jks file).

JKSSignatureToken usage

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

1.3.1.6. Other Implementations

Another implementation can be added by extending the SignatureTokenConnection interface, thus enabling the framework to use other API than provided within the framework. 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.

1.3.2. Key management

Since DSS 5.12, the framework offers a functionality of filtering key entries to be accessed from a SignatureTokenConnection interface. The filtering is done within SignatureTokenConnection#getKeys method with a help of DSSKeyEntryPredicate interface. Unless the predicate is configured, DSS will return all available keys by default.

An example of a basic usage of the DSSKeyEntryPredicate implementation is provided below:

DSSKeyEntryPredicate usage

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

The list of provided default implementations of the DSSKeyEntryPredicate interface is provided below for reference:

Provided DSSKeyEntryPredicate implementations

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

It is also possible to implement a custom predicate filtering key entries. An example below demonstrates an implementation filtering key entries based on a QcQSCD certificate:

Implementation of DSSKeyEntryPredicate to return keys associated with a QcQSCD based certificate

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

and an example of its usage:

QcQSCDKeyEntryPredicate usage

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

1.4. Signature creation in DSS

In the DSS framework, there are two alternatives for signing a document which are illustrated in the following schema.

The first path consists in 3 atomic steps:

1. Compute the data to be signed (DTBS);

2. Sign the DTBS to obtain the signature value;

3. Sign the document (add the signature value).

The alternative is to use the following 4 steps:

1. Compute the data to be signed (DTBS);

2. Compute the digest of the DTBS to obtain the data to be signed representation (DTBSR);

3. Sign the DTBSR to obtain the signature value;

4. Sign the document (add the signature value).

1.4.1. Signature creation in 3 stateless methods

Usually, the signature creation is done using the 3 stateless methods approach.

DSS fully manages the first and last steps of the document signature process. The signature operation (signing the DTBS) needs to be specified. DSS offers some implementations in the dss-token module. During this step, the signing keys are not retrieved. Instead, a communication channel that allows sending the DTBS to the keys is opened.

The following code presents the three stateless steps.

Three stateless steps

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

The first step uses the getDataToSign() method, which receives the following arguments:

• the document to be signed;

• the previously selected settings.

This step returns the DTBS. In the case of a XAdES, it corresponds to the SignedInfo XMLDSig element. Usually the DTBS is composed of the digest of the original document and the signed attributes (i.e. XAdES or CAdES).

The second step is a call to the function sign(), which is invoked on the object token representing the KeyStore and not on the service. This method takes three parameters:

• Array of bytes that must be signed. It is obtained by the previous method invocation.

• Algorithm used to create the digest. There is the choice between, for example, SHA256 and SHA512. This list is not exhaustive. For an exhaustive list see this class.

• Private key entry.

The third and last step of this process is the integration of the signature value in the signature and linking of that one to the signed document based on the selected packaging method. This is done using the method signDocument() on the service. It requires three parameters:

• Document to sign;

• Signature parameters (the same as the ones used in the first step);

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

1.4.2. Signature creation in 4 stateless methods

The main difference in this approach is that the digest of DTBS (i.e. DTBSR) is computed separately from a SignatureValue creation.

The following code presents the alternative with four stateless steps.

Four stateless steps

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

The first and last steps, which compute the DTBS and sign the document, are the same as for the alternative with three steps.

The second step uses the digest method, which takes the following arguments

• the digest algorithm;

• the DTBS computed during the first step.

It returns the data to be signed representation (DTBSR) of a DTBS, i.e. it computes the digest.

The step that signs the digest with a raw signature (eg: NONEwithECDSA) and returns the signature value uses the method signDigest, which takes the following arguments:

• the DTBSR.

• the private key entry.

1.5. Creating a Baseline B-level signature

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]).

The referenced specifications define the following:

• To digitally sign a document, a signing certificate (that proves the signer’s identity) and the access to its associated private key is needed.

• To digitally 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, associated to the private key used to create the signature, must also be provided.

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

xml_example.xml

<?xml version="1.0"?>
<test>Hello World !</test>

To instantiate a document from a file in DSS, refer to the section about DSSDocuments.

Since this is an XML document, we will use the XAdES signature and more particularly the XAdES-BASELINE-B level. For our example, we will use the ENVELOPED packaging.

To write our Java code, we still need to specify the type of KeyStore to use for signing our document. In other words, we need to specify where the private key can be found. To know more about the use of the different signature tokens, please consult the Signature tokens section.

In this example the class Pkcs12SignatureToken will be used. A file in PKCS#12 format must be provided to the constructor of the class. It contains a private key accompanying the X.509 public key certificate and protected by a password. The certificate chain can also be included in this file.

Note	It is possible to generate dummy certificates and their chains with OpenSSL. Please visit http://www.openssl.org/ for more details and http://dss.nowina.lu/pki-factory/keystore/list to access dummy certificates and their chains.

This is the complete code example that allows you to sign an XML document:

Create a XAdES-BASELINE-B signature

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

To summarize, signing a document in DSS requires to:

• Create an object based on the SerializableSignatureParameters class. Generally, the number of specified parameters depends on the format, profile and level of the signature. This object also defines some default parameters.

• Choose the level, packaging and signature digest algorithm.

• Indicate the private key entry as well as the associated signing certificate and certificate chain.

• Instantiate the adequate signature service based on the format of the signature. In our case it is an XML file, so we will instantiate a XAdES service.

• Carry out the signature process (three or four steps). in our case, the process of signing takes place in three stages.

The encryption algorithm is determined by the private key and therefore shall not be compelled by the setter of the signature parameters object. It would cause an inconsistency in the signature making its validation impossible. This setter can be used in a particular context where the signing process is distributed on different machines and the private key is known only to the signature value creation process.

Setting the signing certificate and the certificate chain should always be done. They can be set even if the private key is only known to the signature value creation process and there is no access to the private key at DTBS preparation. However, of course, the signing certificate shall be associated to the private key that will be used at the signature value creation step. Integrating the certificate chain in the signature simplifies the build of a prospective certificate chain during the validation process.

When the specific service is instantiated a certificate verifier must be set. It is recommended to read section [certificateVerifier] for information on the configuration of a CertificateVerifier.

The code above produces the signature that can be found here.

1.6. Configuration of attributes in DSS

1.6.1. Signed and unsigned attributes

A signature is composed of signed and unsigned attributes.

Signed attributes shall be included in a signature. These are BASELINE-B attributes that are set upon signature creation. They cannot be changed after the signature has been created.

Unsigned attributes are not obligatory and can be added after the signature creation during signature augmentation.

1.6.1.1. Table with all attributes per format and class

Table 4. File formats and Signature types conformance

		DSS classes and methods	XAdES	CAdES	PAdES	JAdES
B-Level	Signed attributes	class BLevelParameters #setSigningDate	SigningTime	signing-time	/M	iat sigT
		class BLevelParameters #setClaimedSignerRole	SignerRoleV2	signer-attributes-v2	signer-attributes-v2	srAts
		class BLevelParameters #setSignedAssertions	SignedAssertions	signedAssertions	signedAssertions	signedAssertions
		class BLevelParameters #setCommitmentTypeIndications	CommitmentTypeIndication	commitment-type-indication	commitment-type-indication	srCms
		class BLevelParameters #setSignerLocation	SignatureProductionPlaceV2	signer-location	/Location	sigPl
		class BLevelParameters #setSignaturePolicy	SignaturePolicyIdentifier	signature-policy-identifier	signature-policy-identifier	sigPId
B-Level	Signed attributes	class *AdESSignatureParameters #setSigningCertificate	SigningCertificate SigningCertificateV2	signing-certificate-v2	signing-certificate-v2	x5t#256 x5t#o
		class *AdESSignatureParameters #setCertificateChain	KeyInfo/X509Data	SignedData.certificates	SignedData.certificates	x5c
		class *AdESSignatureParameters #setEncryptionAlgorithm #setDigestAlgorithm	SignatureMethod	/	/	alg
		class *AdESSignatureParameters #setContentTimestamps	AllDataObjectsTimeStamp IndividualDataObjectsTimeStamp	content-time-stamp	content-time-stamp	adoTst
		class XAdESSignatureParameters #setReferences	SignedInfo/Reference	/	/	/
B-Level	Signed attributes	class XAdESSignatureParameters #setDataObjectFormatList	DataObjectFormat	/	/	/
		class XAdESSignatureParameters #setSignedAdESObject	Object	/	/	/
		class CAdESSignatureParameters #setContentHintsType #setContentHintsDescription	/	content-hints	/	/
		class CAdESSignatureParameters #setContentIdentifierPrefix #setContentIdentifierSuffix	/	content-identifier	/	/
		class PAdESSignatureParameters #setReason	/	/	/Reason	/
B-Level	Signed attributes	class PAdESSignatureParameters #setContentSize	/	/	/Contents (length)	/
		class PAdESSignatureParameters #setFilter	/	/	/Filter	/
		class PAdESSignatureParameters #setSubFilter	/	/	/SubFilter	/
		class PAdESSignatureParameters #setSignerName	/	/	/Name	/
		class PAdESSignatureParameters #setImageParameters	/	/	Visual representation	/
		class PAdESSignatureParameters #setPermission	/	/	/P (CertificationPermission)	/
B-Level	Signed attributes	class JAdESSignatureParameters #setIncludeCertificateChain	/	/	/	x5c
		class JAdESSignatureParameters #setIncludeSignatureType	/	/	/	typ
		class JAdESSignatureParameters #setIncludeKeyIdentifier	/	/	/	kid
		class JAdESSignatureParameters #setX509Url	/	/	/	x5u
		class JAdESSignatureParameters #setSigningCertificateDigestMethod (DigestAlgorithm.SHA256)	/	/	/	x5t#S256
B-Level	Signed attributes	class JAdESSignatureParameters #setSigDMechanism	/	/	/	sigD
		class JAdESSignatureParameters #setBase64UrlEncodedPayload	/	/	/	b64
		class DSSDocument (for signer document) #setMimeType	DataObjectFormat/MimeType	mime-type	/	cty
B-Level	Unsigned attributes	class *AdESService #getDataToBeCounterSigned #counterSignSignature	CounterSignature	countersignature	/	cSig
		class *AdESService #addSignaturePolicyStore	SignaturePolicyStore	signature-policy-store	/	sigPSt
		class JAdESSignatureParameters #setBase64UrlEncodedEtsiUComponents	/	/	/	etsiU (items encoding)
T-Level	Unsigned attributes	class *AdESSignatureParameters #setSignatureLevel(*AdES_BASELINE_T) #setSignatureTimestampParameters	SignatureTimeStamp	signature-time-stamp	signature-time-stamp	sigTst
LT-Level	Unsigned attributes	class *AdESSignatureParameters #setSignatureLevel(*AdES_BASELINE_LT) #setSignatureLevel(XAdES_XL)	CertificateValues RevocationValues	SignedData.certificates SignedData.crls	/DSS /VRI (conditional)	xVals rVals
		class PAdESSignatureParameters #setIncludeVRIDictionary	/	/	/VRI	/
LTA-Level	Unsigned attributes	class *AdESSignatureParameters #setSignatureLevel(*AdES_BASELINE_LTA) #setSignatureLevel(XAdES_A) #setArchiveTimestampParameters	ArchiveTimeStamp	archive-time-stamp-v3	document-time-stamp	arcTst
C-Level (xades only)	Unsigned attributes	class XAdESSignatureParameters #setSignatureLevel(XAdES_C)	CompleteCertificateRefs CompleteRevocationRefs	(not supported)	(not supported)	(not supported)
X-Level (xades only)	Unsigned attributes	class XAdESSignatureParameters #setSignatureLevel(XAdES_X)	SigAndRefsTimeStamp	(not supported)	(not supported)	(not supported)

1.6.2. Signed attributes

Additional signed attributes can be added to the basic signature configuration as presented in the following example of a XAdES-BASELINE-B signature.

XAdES signature with additional signed attributes

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

In the XAdES format the following types of 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.

By default, the AllDataObjectsTimeStamp is used. The IndividualDataObjectsTimeStamp can be configured manually.

Note	To set the Content Timestamp, a TSP source needs to be set. The method getOnlineTSPSource() is not a core feature of DSS and shall be implemented by the user.

Concerning the signing date, the framework uses the current date time by default. In the case where it is necessary to indicate a different time it is possible to use the setter setSigningDate(Date).

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

The code above produces the signature that can be found here.

1.6.2.1. Signature Policy

The signature policy is a BASELINE-B signed attribute that is set upon signature creation. Thus, this attribute cannot be changed after the signature has been created.

The DSS framework allows you to reference a signature policy, which is a set of rules for the creation and validation of an electronic signature. For more information on the signature policy refer to section [SignaturePolicies].

The signer may reference the policy either implicitly or explicitly.

• An implied policy means the signer follows the rules of a 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 the SignaturePolicyIdentifier element will be empty.

• When the policy is explicit, the signature contains an ObjectIdentifier 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 content of the policy document.

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

XAdES with implicit policy

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

The following XML segment will be added to the signature’s qualifying and signed properties (<QualifyingProperties><SignedProperties>):

../_samples/xades-implicit-policy.adoc

The next example demonstrates the use of an explicit policy identifier. This is obtained by setting the BASELINE-B profile signature policy and assigning values to the policy parameters. The Signature Policy Identifier is a URI or OID that uniquely identifies the version of the policy document. The signature will contain the identifier of the hash algorithm and the hash value of the policy document. The DSS framework does not automatically calculate the hash value; it is up to the developer to proceed with the computation. It is important to keep the policy file intact in order to keep the hash constant. It would be wise to make the policy file read-only.

XAdES with explicit policy

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

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

XAdES Signature Policy element

../_samples/xades-explicit-policy.adoc

1.6.2.2. Signature Policy Store

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 for example 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 section Signature Policy).

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

Add SignaturePolicyStore

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

1.6.3. Trust Anchor Inclusion Policy

In DSS, it is possible to indicate whether to include or not the certificate related to the trust anchor in the signature. Refer to section [TrustAnchors] for information on trust anchors.

By default, when a BASELINE-B signature is constructed the trust anchor is not included, only the certificates previous to the trust anchor are included. When a BASELINE-LT signature is constructed the trust anchor is included.

It is possible to indicate to the framework that the certificate related to the trust anchor should be included to the signature even at the BASELINE-B level. The setter setTrustAnchorBPPolicy(trustAnchorBPPolicy) of the BLevelParameters class should be used for this purpose.

By default, the argument trustAnchorBPPolicy is set to true so that only the certificates previous to the trust anchor are included. It should be set to false in order to include all certificates, including the trust anchor.

Use of Trust Anchor Inclusion Policy parameter

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

1.6.4. Other parameters

1.6.4.1. XAdES

1.6.4.1.1. Canonicalization parameters

Before computing digests on an XML element, a canonicalization should be performed.

DSS allows defining canonicalization algorithms to be used on signature or timestamp creation:

Use of canonicalization algorithm parameters

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

1.6.4.1.2. References

In order to compute digest for original document(s) in a custom way, a class DSSReference can be used to define a ds:Reference element’s content:

DSSReference definition

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

Warning

The parameter modifies default behavior on ds:Reference’s computation and its incorrect definition may cause production of invalid signatures. The parameter is recommended to be used only by experienced users.

For more information about DSSReference configuration, please refer the section [RefTransformations].

1.6.4.1.3. Data Object Format

Since version 5.13 DSS provides a possibility to identify signed data objects in a customized way by setting a configuration for created DataObjectFormat signed elements. The individual configuration can be achieved by providing a list of DSSDataObjectFormat objects corresponding the signed data objects within the XAdESSignatureParameters:

DSSDataObjectFormat definition

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

Warning

The parameter modifies default behavior the xades:DataObjectFormat elements are created. It is up to the implementor to ensure the validity of the defined configuration. The parameter is recommended to be used only by experienced users.

1.6.4.1.4. Objects

It is possible to provide a list of custom data objects to be incorporated within a created signature as ds:Object elements (which is similar to signed data objects in ENVELOPING XAdES signature packaging). For this a list of DSSObject objects should be provided within the used XAdESSignatureParameters instance:

DSSObject definition

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

Note	The provided objects are not signed by default. To sign the data, the corresponding configuration can be achieved with a help of References parameter. Such configuration is considered as advanced and not covered within the documentation.

1.6.4.2. PAdES

The framework allows creation of PDF files with visible signature as specified in ETSI EN 319 142 (cf. [R03]) and allows the insertion of a visible signature to an existing field. For more information on the possible parameters see section [PAdESVisibleSignature].

1.7. Multiple signatures

1.7.1. Parallel signatures

Parallel signatures, described in section [ParallelSignatures], can be created in DSS according to the corresponding AdES formats.

Parallel signatures creation

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

1.7.2. Sequential signatures

DSS allows creation of sequential signatures according to the PAdES formats (cf. [SequentialSignatures]).

Sequential signatures creation

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

1.8. Counter signatures

DSS allows creation of counter signatures in accordance with corresponding AdES formats (cf. [CounterSignatures]).

Note	A counter signature does not provide a Proof Of Existence for a signed signature! Use signature augmentation / timestamping for this purpose.

The following formats are supported for the counter signature creation:

• XAdES - multiple, nested and augmented counter signatures (up to LTA level) are allowed;

• CAdES - B-level counter signatures are allowed, as well as multiple counter signatures. This limitation comes from the cryptography library (bouncyCastle) and not from the standard;

• JAdES - multiple, nested and augmented 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 presents a counter signature creation:

Counter signature creation

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

1.9. Extract the original document from a signature

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

Retrieve the original data from a signed document

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