Digital Signature Service

This section explains the usage and build requirements for DSS framework.

This section explains the build and use requirements for the DSS Demonstration Applications.

This chapter provides an overview on modules available within Source code of DSS Core.

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

DSS contains a bundle of JAXB-based modules, generating Java classes at runtime based on XSD-schema. When any change is made in the XSD, the classes of the module are being re-generated according to the change. The following modules present this behavior:

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

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

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

This chapter provides an overview on modules available within demonstrations project.

A Trust Service Provider (TSP) is a natural or legal person who provides one or more trust services. A trust service is an electronic service related, among others, to the creation, validation and preservation of electronic signatures, timestamps, and certificates.

Given that a TSP can provide a combination of trust services, a TSP can take one or more of the following roles

A TSP can be either a qualified or non-qualified trust service provider. All TSPs no matter if qualified or not have the following obligations and requirements

This ensures the validity and security of the trust services that TSPs provide, such as the integrity of the data that was used for certificate and signature creation as well as the security of the signing keys.

A qualified trust service provider (QTSP) is a TSP that provides one or more qualified trust services and is included in a Trusted List (cf. Trusted Lists).

Some aspects are specific to QTSPs and follow from the requirements of eIDAS

A (simplified) description of the PKI model and where DSS is involved in that model is given in the figure below.

In this simplified model, a PKI is composed of:

In turn, DSS within that model, can be used to implement Signature creation applications (SCA) and/or Signature Validation Applications (SVA)

Each of those concepts are further detailed in the next sections.

As mentioned before, in the present context, digital signatures are supported by public key certificates. Public key certificates are data structures that binds an entity to a public key and that are signed by a third party, they provide a proof of authenticity of the public key.

The ITU-T X.509 Recommendation is a standard describing (among others) such a data structure, and public key certificates structured as per the specifications provided in that standard are commonly referred to as “X.509 public key certificates”.

Furthermore, the IETF published the RFC 5280 ([R22]) which specifies a profile for X.509 public key certificates (and certificate revocation lists). For the remainder of this document, X.509 public key certificates are assumed to be profiled as per RFC 5280.

Certificates can be end-entity certificates or CA certificates:

Certificates have a defined validity period during which the CA having issued the certificate guarantees the correctness of its content. During that validity period, they may however be revoked or suspended, for instance when the entity to which the certificate has been issued has lost control of the corresponding private key.

A certificate contains among other things information on:

As previously mentionned, a certificate can be revoked or suspended. This information is usually provided in the form of a Certificate Revocation List (CRL), or through the Online Certificate Status Protocol (OCSP).

A CRL is a list of revoked (and/or suspended) certificates that is digitally signed and published by a CRL issuer. This issuer can be the CA having issued the certificates listed in the CRL, or it can be another CA in which case the CRL is called an “indirect CRL”. RFC 5280 ([R22]) provides a profile for X.509 CRLs.

The OCSP is a protocol defined in RFC 6960 ([R23]) that enables the determination of the (revocation) status of a certificate without the use of a CRL. An OCSP request, containing (among other things) information on the certificate for which the (revocation) status is requested, is sent to a server and a response, containing information of that (revocation) status, is provided by an OCSP responder. OCSP responses are signed by the OCSP responder, and the OCSP responder can be the CA having issued the certificate or another CA in which case the OCSP responder is called a “delegated OCSP responder”.

RFC 5280 section 6.3 describes an algorithm for the validation of CRLs, while Common PKI v2.0 part 5 section 2.3 ([R24]) describes an algorithm for checking the revocation status of a certificate using CRLs and OCSP responses.

The certificate path validation is an algorithm that seeks to verify the binding between the public key and the subject of a certificate, using trust anchor information. The complete processing is described in RFC 5280 section 6.1, and as stated there, it verifies among other things that a prospective certification path (a sequence of n certificates) satisfies the following conditions:

Although RFC 5280 states that procedures performed to obtain the sequence of certificate that is provided to the certification path validation is outside its scope, Common PKI v2.0 part 5 section 2.1 ([R24]) provides one such possible procedure.

An intuitive approach to build a prospective certification path is to start by looking at the “Authority Information Access” (AIA) extension of the target certificate (see RFC 5280 section 4.2.2.1) which, if present, frequently includes information on how to retrieve the certificate of the issuer of that certificate. Repeating this action on the certificate retrieved can then allow to build a prospective certification path.

The wording "certificate chain" is often used interchangeably with "certification path".

In ETSI EN 319 102-1 ([R09]) however, a prospective certificate chain is defined as a sequence of certificate that satisfies the conditions a. to c. above and for which the trust anchor is trusted according the validation policy in use.

An illustration of different certificate chains/certification paths is provided in the figure below.

Taking a very (or over) simplified model, validating a digital signature can be seen as:

We’ll see that even such a simplified model is useful for the purpose of introducing common concepts in digital signature validation.

Let’s imagine that we want to validate a digital signature and the time when this validation occur is denoted as T_val.

If the signing certificate successfully passes the certification path validation at T_val, and the digital signature value is cryptographically valid, one can then say that the digital signature is valid at T_val.

Now, if computing the hash of the signed data does not yield the same value as the decryption of the signature value, one can then say that the digital signature is invalid.

Beyond valid and invalid digital signature however, there are a lot of cases when one cannot determine the validity of a digital signature. Below are some examples where one cannot conclude that a digital signature is valid or invalid, in which case the validity status of the signature is indeterminate.

Let’s imagine that at T_val, when we are trying to access the certification status information, that information is unavailable (e.g. the CRL cannot be downloaded, the OCSP responder is unavailable). Then it is not possible, at T_val, to determine whether the signing certificate is valid or not because at that time we are lacking information to conclude on that validity status. Because the validity of the signing certificate cannot be determined, the validity of the overall signature cannot be determined either and the validity of the signature is indeterminate. However, this status is only indeterminate because we do not have the information that would allow us to conclude, retrying to validate the signature with more information (e.g. at a time when the CRLs can be downloaded) could result in a definite valid or invalid status.

A more complex example is when, at T_val, revocation information indicates that the signing certificate is revoked since a time indicated as T_rev (which is thus < T_val).

Then at T_val, we can only conclude that the signing certificate is revoked and thus the signature cannot be determined as valid at T_val. However, this does not mean necessarily that the signature was created when the signing certificate was revoked, it may very well be that the signature was created at a time prior to T_rev and that, should we have validated the signature at that time, the validation would have been successful. Therefore, we cannot conclude that the signature is invalid because we do not know in a definite manner if the signature was created before the revocation of the signing certificate.

For instance, if we had a proof that the signature existed before T_rev, such as a signature timestamp indicating a time T_poe < T_rev, then using that proof of existence (POE) we can conclude that the signature was created before the signing certificate was revoked and this could allow us to produce a definite conclusion.

On the other hand, if we had a proof that the signature could not have existed before T_rev, such as a content timestamp indicating a time T_cnt > T_rev (a content timestamp is necessarily created before the digital signature value), then we could definitely conclude that the signing certificate was revoked when the digital signature was created and thus that the digital signature is invalid.

Another issue that can be illustrated here is when one creates a digital signature using cryptographic algorithms that are not considered secure: In such a case, it may be possible for an malicious actor to create counterfeited signed documents.

When validating a signature, it is therefore necessary to verify that the signature was created using cryptographic algorithms and parameters that are considered as secure. This is usually done by comparing a POE of the digital signature value with a sunset date for the cryptographic algorithms and parameters involved. A sunset date for a cryptographic algorithm and/or parameter is called a cryptographic constraint, and the application validating the signature usually keeps a set of such dates and cryptographic algorithms and parameters; this set is what is called the set of cryptographic constraints.

In general, the validation of a signature is made against a set of constraints, which the cryptographic constraints are a part of, that is also sometimes referred to as a signature validation policy.

The standard ETSI EN 319 102-1 specifies a complete validation model and procedures for the validation of “AdES digital signatures”, which are implemented in DSS. The result of a validation process performed according to those procedures is a validation report and an indication which can be:

For each of the validation checks/constraint (e.g. signature format, signing certificate validity), the validation process must provide information justifying the reasons for the resulting status indication as a result of the check against the applicable constraints. In addition, the ETSI standard defines a consistent and accurate way for justifying statuses under a set of sub-indications. This allows the user to determine whether the signature validation has succeeded and the reason in case of a failure.

The following table presents the indications and sub-indications that can be encountered at completion of a signature validation process. For a detailed description of their meaning, refer to ETSI EN 319 102-1 ([R09]).

As illustrated in Signature validation (introduction), validating a signature sometimes require a proof of existence of that signature at a given time.

Such proof of existence can be given in the form of a timestamp.

A digital timestamp is an assertion of proof that a data object existed at particular time. This usually takes the form of a binding between a hash of a data object and a date and time issued and signed by a trustworthy timestamping authority.

When signing digitally, a date and time can be already included into the signature, but it corresponds to the signer computer’s local time. The latter can easily be modified prior to signing so that the time of signing is not the actual one. Thus, this signing time cannot be trusted. A trustworthy digital timestamp shall be used to prove existence of the signature (and its associated data) at a certain point in time.

This principle exists for handwritten signatures too. When a document is signed manually, it is done in the presence of a trustworthy notary, who verifies not only the identity of the signer but also the date and time of the signature.

Before explaining the timestamping process, let us define some concepts that are involved in this process

Furthermore, in the context of digital signatures, we usually distinguish timestamps depending on the data for which they provide a proof of existence:

Timestamping, the process of adding a timestamp to a signature, can be broken down into the following steps:

An illustration of that process for the creation of a signature timestamp is provided below:

The timestamp token created by a TSA can be considered as trustworthy because

Up until now, only creation of a single signature have been covered. However, in most cases multiple signatures need to be created (e.g. a contract signing by multiple parties). In such cases, it is useful to note that multiple signatures can be created in parallel or in a sequential order.

The term "signature policy" is often used to refer to "Signature Applicability Rules", that is, a set of rules for the creation, validation and long-term management of one (or more) electronic signature(s).

A Signature Policy, in that meaning, contains general information such as:

A Signature Policy is composed of three main parts that define technical and procedural requirements:

A signature policy is a way of expressing:

The exact information contained in a signature policy will depend on the use cases of the signature and on the involved parties as the signature policy can be negotiated between them. Therefore, it is not possible to define a single template policy to cover all use cases.

Having a signature policy and thus all the above-mentioned information, available in a signature, has several advantages:

Parties involved in a signature policy are:

ETSI ESI has developped several standards to express signature applicability rules or "signature policy" in two forms:

The Token class is the base class for the different types of tokens used in the process of signature validation which are certificates, OCSPs, CRLs and timestamps. These tokens can be described as follows:

DSS implements the following ETSI standards for various signature forms:

but also claims:

DSS is not limited to EU contexts. It can be used in non-EU contexts with all its basic functions, i.e. signing, augmentation, validation, etc.

An example would be the configuration of trust anchors (see section Trust anchor configuration from a certificate store). The certificate sources can be configured from a TrustStore (kind of keystore which only contains certificates), a trusted list and/or a list of trusted lists. In case of an EU context you could use any of these three trust anchors. For a non-EU context you could use a trust store or a non-EU trusted list. However, non-EU TLs are supported by DSS only if they have the same XML structure as EU TLs, i.e. if they are compliant with the XSD schema. Another constraint is that there is no guarantee for a proper qualification determination as the non-EU TL shall also be compliant with EU regulations.

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:

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:

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:

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.

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:

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

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:

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

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.

The following implementations are provided within the framework:

More information about each available implementations may be found below.

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:

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

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:

and an example of its usage:

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.

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

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:

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:

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.

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.

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

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:

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.

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

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

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

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

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

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 Trust Anchors and Trust Stores 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.

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

DSS allows creation of sequential signatures according to the PAdES formats (cf. Sequential signatures).