CEF Esig DSS Cookbook

CEF eSignature Building BlockDSS Cookbook

DIGIT

Unit B1

DSS Cookbook

CEF eSignature Building Block

Date: 25/06/2015

Doc. Version: V2.8

PM² Template v2.1.0 (Oct.2013)

CEF eSIG DSS Cookbook - CEF iSIG DSS CookbookPage 1 / 87

Document Version 1.Error! Unknown document property name. dated 05-03-2015

CEF eSignature Building BlockDSS Cookbook

Document Control Information

Settings / Value
Document Title: / DSS Cookbook
Project Title: / CEF eSignature Building Block
Document Author: / Mr. Nicolas Pirard
Project Owners: / Mr.Andrea Servida, DG CNECT
Project Manager: / Mr. Philippe Schneider, DIGIT
Doc. Version: / V2.7
Sensitivity: / High
Date: / 05/03/2015

Document Approver(s) and Reviewer(s):

NOTE: All Approvers are required. Records of each approver must be maintained. All Reviewers in the list are considered required unless explicitly listed as Optional.

Name / DG / Role / Action / Date
Mr. Philippe Schneider / DIGIT.A.3 / Information Systems Architect / ISIP / Review

Document history:

The Document Author is authorized to make the following types of changes to the document without requiring that the document be re-approved:

• Editorial, formatting, and spelling
• Clarification

To request a change to this document, contact the Document Author or Owner.

Changes to this document are summarized in the following table in reverse chronological order (latest version first).

Revision / Date / Created by / Short Description of Changes
0.01 / 17/12/2012 / Robert Bielecki / Version sent for Review
0.05 / 13/02/2013 / Robert Bielecki / Alignment following the comments of the European Commission
1.00 / 20/02/2013 / Frank Meyer / Version sent for Acceptance
1.01 / 19/03/2013 / Robert Bielecki / Alignment for publication following the comments of the European Commission
1.03 / 28/03/2013 / Robert Bielecki / Addressed further comments
1.04 / 09/04/2013 / Robert Bielecki / Aligned with DSS version 2.0/2.0.1
1.05 / 11/03/2013 / Robert Bielecki / Addressed further comments
2.00 / 27/11/2013 / Robert Bielecki / General update after implementation of the new validation process based on “ETSI TS 102 853” standard and incorporation of baseline profiles.
2.01 / 24/01/2014 / Robert Bielecki / Incorporation of WS and PdfBox
2.02 / 03/03/2014 / Robert Bielecki / Update of cookbook’s classes. XAdES: Managing different versions.
2.1 / 08/06/2014 / Robert Bielecki / -Performance optimisation: multi-threaded retrieval of validation data
-Validation of non ADES signatures
Information on the scope of the signatures
2.2 / 16/07/2014 / Robert Bielecki / Update of test classes
2.3 / 15/09/2014 / Vincent Bouckaert / Alignment with version 4.2.0-RC
2.4 / 13/11/2014 / Robert Bielecki / Code sample updated
2.5 / 15/12/2014 / Robert Bielecki / Code sample updated
2.6 / 30/01/2014 / Robert Bielecki / Code sample updated
0.01 / 17/12/2012 / Robert Bielecki / Version sent for Review
0.05 / 13/02/2013 / Robert Bielecki / Alignment following the comments of the European Commission
1.00 / 20/02/2013 / Frank Meyer / Version sent for Acceptance
1.01 / 19/03/2013 / Robert Bielecki / Alignment for publication following the comments of the European Commission
1.03 / 28/03/2013 / Robert Bielecki / Addressed further comments
1.04 / 09/04/2013 / Robert Bielecki / Aligned with DSS version 2.0/2.0.1
1.05 / 11/03/2013 / Robert Bielecki / Addressed further comments
2.00 / 27/11/2013 / Robert Bielecki / General update after implementation of the new validation process based on “ETSI TS 102 853” standard and incorporation of baseline profiles.
2.01 / 24/01/2014 / Robert Bielecki / Incorporation of WS and PdfBox
2.02 / 03/03/2014 / Robert Bielecki / Update of cookbook’s classes. XAdES: Managing different versions.
2.1 / 08/06/2014 / Robert Bielecki / -Performance optimisation: multi-threaded retrieval of validation data
-Validation of non ADES signatures
-Information on the scope of the signatures
2.2 / 16/07/2014 / Robert Bielecki / Update of test classes
2.3 / 15/09/2014 / Vincent Bouckaert / Alignment with version 4.2.0-RC
2.4 / 13/11/2014 / Robert Bielecki / Code sample updated
2.5 / 15/12/2014 / Robert Bielecki / Code sample updated
2.6 / 30/01/2014 / Robert Bielecki / Code sample updated
2.7 / 05/03/2015 / Nicolas Pirard / -Aligned with DSS version 4.4.RC1
-Document migrated to CEF eSig template.
2.8 / 25/06/2015 / David Naramski / -Version 4.4.0

Reference and Applicable Documents

This section contains the lists of all references and applicable documents. When referring to any of the documents below, the bracketed reference will be used in the text, such as [R01].

Reference and applicable documents:

Ref. / Title / Reference / Version / Date
R01 / DSS - Functional Analysis / DSS4-FAD / 2.02 / 24/01/2014
R02 / DSS - Software Architecture / DSS4-SAD / 2.01 / 24/01/2014
R03 / DSS - Design Model / DSS2-DM / 2.00 / 20/01/2012
R04 / XAdES Specifications / ETSI TS 101 903 / 1.4.2 / 12/2010
R05 / CAdES Specifications / ETSI TS 101 733 / 2.2.1 / 04/2013
R06 / PAdES Specification / ETSI TS 102 778 part 1-6 / 1.x.x / 07/2010
R07 / Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation
List (CRL) Profile / IETF RFC 5280 / N/A / May 2008
R08 / OCSP / RFC 6960 / N/A / June 2013
R09 / TC Security - Electronic Signatures
and Infrastructures (ESI);
XML format for signature policies / ETSI TR 102 038 / 1.1.1 / 2002-04
R10 / Document management - Portable document format - Part 1:
PDF 1.7 / ISO 32000-1 / 1 / 2008
R11 / Electronic Signatures and Infrastructures;
Associated Signature Containers
Testing Compliance & Interoperability;
Test Suite for ASiC interoperability test events / ETSI TS 119 164-2 / 1.1.1 / 2012-03
R12 / Electronic Signatures and Infrastructures;
Associated Signature Containers / ETSI TS 102 918 / 1.1.1 / 2011-04
R13 / Directive 1999/93/EC of the European Parliament and of the Council of 13 December 1999 on a Community framework for electronic signatures. / DIRECTIVE 1999/93/EC / N/A / 13/12/1999
R14 / Internet X.509 Public Key Infrastructure
Time-Stamp Protocol (TSP) / RFC 3161 / N/A / 08/2001
R15 / Electronic Signatures and Infrastructures;
Signature verification procedures and policies / ETSI TS 102 853 / 1.1.1 / 2012-07
R16 / Policy Requirements for Time-Stamping Authorities (TSAs) / RFC 3628 / N/A / 11/2003
R17 / XAdES Baseline profiles / ETSI TS 103 171 / 2.1.1 / 2012-03
R18 / CAdES Baseline profiles / ETSI TS 103 173 / 2.2.1 / 2013-04
R19 / PAdES Baseline profiles / ETSI TS 103 172 / 2.1.1 / 2012-03
R20 / ASiC Baseline profiles / ETSI TS 103 174 / 2.1.1 / 2012-03
R21 / DSS3-QTM4-Signature Validation Policy and Report Simplification Analysis-v1.00.doc

Abbreviations and Acronyms:

Code / Description
AdES / Advanced Electronic Signature
API / Application Programming Interface
ASiC / Associated Signature Containers
BB / Building Block (CEF)
CA / Certificate authority
CAdES / CMS Advanced Electronic Signatures
CD / Commission Decision
CEF / Connecting Europe Facility
CMS / Cryptographic Message Syntax
CRL / Certificate Revocation List
CSP / Core Service Platform (CEF)
CSP / Cryptographic Service Provider
DER / Distinguished Encoding Rules
DSA / Digital Signature Algorithm - an algorithm for public-key cryptography
DSI / Digital Service Infrastructure (CEF)
DSS / Digital Signature Service
EC / European Commission
eID / Electronic Identity Card
EJB / Enterprise Java Beans
ESI / Electronic Signatures and Infrastructures
ETSI / European Telecommunications Standards Institute
EUPL / European Union Public License
FAT / Factory Acceptance Testing
FSF / Free Software Foundation
GS / Generic Service (CEF)
GUI / Graphical User Interface
HSM / Hardware Security Modules
HTTP / Hypertext Transfer Protocol
I18N / Internationalisation
iText / Is an open source library that allows you to create and manipulate PDF documents:
Java EE / Java Enterprise Edition
JavaDoc / JavaDoc is developed by Sun Microsystems to create API documentation in HTML format from the comments in the source code. JavaDoc is an industrial standard for documenting Java classes.
JAXB / Java Architecture for XML Binding
JCA / Java Cryptographic Architecture
JCE / Java Cryptography Extension
JDBC / Java DataBase Connectivity
LGPL / Lesser General Public License
LOTL / List of Trusted List or List of the Lists
LSP / Large Scale Pilot
MIT / Massachusetts Institute of Technology
MOCCA / Austrian Modular Open Citizen Card Architecture; implemented in Java
MS / EUMS / Member State
MS CAPI / Microsoft Cryptographic Application Programming Interface
OCF / OEBPS Container Format
OCSP / Online Certificate Status Protocol
ODF / Open Document Format
ODT / Open Document Text
OEBPS / Open eBook Publication Structure
OID / Object Identifier
OOXML / Office Open XML
OSI / Open Source Initiative
OSS / Open Source Software
PAdES / PDF Advanced Electronic Signatures
PAO / Project and Architecture Office (CEF)
PC/SC / Personal computer/Smart Card
PDF / Portable Document Format
PDFBox / Apache PDFBox - A Java PDF Library:
PKCS / Public Key Cryptographic Standards
PKCS#12 / It defines a file format commonly used to store X.509 private key accompanying public key certificates, protected by symmetrical password
PKIX / Internet X.509 Public Key Infrastructure
RSA / Rivest Shamir Adleman - an algorithm for public-key cryptography
SCA / Signature Creation Application
SCD / Signature Creation Device
SME / Subject Matter Expert
SMO / Stakeholder Management Office (CEF)
SOAP / Simple Object Access Protocol
SSCD / Secure Signature-Creation Device
SVA / Signature Validation Application
TL / Trusted List
TLManager / Application for managing trusted lists.
TSA / Time Stamping Authority
TSL / Trust-service Status List
TSP / Time Stamp Protocol
TSP / Trusted Service Provider
TST / Time-Stamp Token
UAT / User Acceptance Testing
UCF / Universal Container Format
URI / Uniform Resource Identifier
WP / Work Package
WSDL / Web Services Description Language
WYSIWYS / What you see is what you sign
XAdES / XML Advanced Electronic Signatures
XML / Extensible Markup Language
ZIP / File format used for data compression and archiving

Date: 05/03/2015 1 / 88 Doc.Version:V2.7

CEF eSignature Building BlockDSS Cookbook

TABLE OF CONTENTS

Reference and Applicable Documents

1Introduction

1.1Purpose of the Document

1.2Scope of the Document

1.3Intended Audience

2General Framework Structure

3Signature’s Profile simplification

4The XML Signature (XAdES)

4.1XAdES Profiles

4.1.1XAdES-BASELINE-B

4.1.1.1Signing process

4.1.1.2Additional attributes

4.1.1.3Handling signature policy

4.1.2XAdES-BASELINE-T

4.1.2.1Use of online TSP source

4.1.3XAdES-BASELINE-LT

4.1.4XAdES-BASELINE-LTA

4.2Various settings

4.2.1Trust anchor inclusion policy

4.3Multiple signatures

4.4The XML Signature Extension (XAdES)

4.5XAdES-BASELINE-T

4.6XAdES-BASELINE-LT and -LTA

4.7XAdES and specific schema version

5The Signature Validation

5.1Validation Process

5.2EU Trusted Lists of Certification Service Providers

5.3Validation Result Materials

5.3.1Simple Report

5.3.2Detailed Report

5.3.3Diagnostic Data

5.4Customised Validation Policy

5.5Structural signature validation

6CAdES Signature and Validation

7PAdES Signature and Validation

7.1PAdES Visible Signature

8ASiC Signature and Validation

9Management of Signature Tokens

9.1PKCS#11

9.2PKCS#12

9.3MS CAPI

9.4Other Implementations

10Management of Certificates Sources

11Management of CRL and OCSP Sources

11.1Other implementations of CRL and OCSP Sources

12TSP Sources

13WEB SERVICES

13.1Available SOAP services:

13.1SignatureService

13.2ValidationService

14How to check a simple certificate

15Validation of non ADES signatures

16Handling the Scope of the signature

17TESTING facility classes

Mock CRL Sources

Mock OCSP Sources

AlwaysValidOCSPSource

MockTSLCertificateSource

MockTSPSource

18Accessing a standard Java KeyStore

18.1JavaKeyStore

18.2Signing „Application“

18.3Root class „Cookbook“

TABLE OF FIGURES

Figure 1: Signature Validation Process Scheme (source: [ETSI TS 102 853])

Figure 2: Pkcs11SignatureToken interface

Figure 3: Pkcs12SignatureToken interface

Figure 4: MSCAPISignatureToken interface

Figure 5: Implementation of SignatureTokenConnection for Java 6 IO PC/SC

Figure 6: CertificateSource interface (not trusted part)

Figure 7: CertificateSource interface (trusted part)

Figure 8: CRLSource interface

Figure 9: OCSPSource interface

Figure 10: SignatureScope default specializations

Figure 11: SignatureScopeFinder and its specializations

Figure 12: SignatureScopeFinderFactory class

TABLE OF CODE

Code 1: src\main\resources\xml_example.xml

Code 2: cookbook.example.sign.SignXmlXadesB.java

Code 3: cookbook.example.signXmlXadesBProperties.java

Code 4: cookbook.example.sign.SignXmlXadesBAllDataObjectsTimestamp.java

Code 5: cookbook.example.sign.SignXmlXadesBImplicitPolicy.java

Code 6: cookbook.example.sign.SignXmlXadesBExplicitPolicy.java

Code 7: cookbook.example.sign.SignXmlXadesT.java

Code 8: cookbook.example.sign.SignXmlXadesTWithOnlineSource.java

Code 9: cookbook.example.Sign.SignXmlXadesLT.java

Code 10: cookbook.example.sign.CountersignXmlXadesB.java

Code 11: cookbook.example.sign.ExtendSignXmlXadesBToT.java

Code 12: cookbook.example.validate.ValidateSignedXmlXadesB.java

Code 13: cookbook.example.validate.ValidateXmlXadesLTWithOnlineSources.java

Code 14: cookbook.example.validate.ValidateSignedXmlXadesBWithCustomPolicy.java

Code 15: cookbook.example.sign.SignXmlCadesB.java

Code 16: cookbook.example.sign.SignPdfPadesB.java

Code 17: cookbook.example.sign. SignPdfPadesBVisible.java

Code 18: cookbook.example.sign.SignPdfAsicB.java

Code 19: cookbook.example.sign.SignXmlXadesBWithMSCAPI.java

Code 20: cookbook.example.sign.EidNativeSignatureTokenConnection.java

Code 21: cookbook.example.sources.EidPrivateKeyEntry.java

Code 22: cookbook.example.sources.AppletView.java

Code 23: cookbook.example.sources.InitOnlineTSPSource.java

Code 24: cookbook.example.sign.SignWithWS.java

Code 25: cookbook.example.sources.CheckCertificate.java

Code 26: Constraint file for non AdES signature validation

Code 27: Example of the Java code to validate non AdES signature

Code 28: Example of the simple (non AdES) XML signature

Code 29: Example of the Simple Report associated to the non AdES signature

Code 30: XSD description of the signature scope

Code 31: cookbook.example.sources.JavaKeyStoreTool.java

Code 32: cookbook.example.sign.SigningApplication.java

Code 33: cookbook.example.Cookbook.java

1Introduction

1.1Purpose of the Document

This document describes some examples of how to develop in Java using the DSS framework. The aim is to show to the developers, in a progressive manner, the different uses of the framework. It will familiarise them with the code step by step.

1.2Scope of the Document

This document provides examples of code which allow easy handling of digital signatures. The examples are consistent with the Release 4.4.RC1 of SD-DSS framework which can be downloaded via

Three main features can be distinguished within the framework:

• The digital signature;
• The extension of a digital signature and;
• The validation of a digital signature.

On a more detailed manner the following concepts and features are addressed in this document:

• Formats of the signed documents: XML, PDF, DOC, TXT, ZIP…;
• Packaging structures: enveloping, enveloped and detached;
• Forms of digital signatures: XAdES, CAdES, PAdES and ASiC;
• Profiles associated to each form of the digital signature;
• Trust management;
• Revocation data handling (OCSP and CRL sources);
• Certificate chain building;
• Signature validation and validation policy;
• Validation of the signing certificate.

This is not an exhaustive list of all the possibilities offered by the framework and the proposed examples cover only the most useful features. However, to discover every detail of the operational principles of the framework, the JavaDoc is available within the source code.

Please note that the SD-DSS framework is still under maintenance and new features will be released in the future.

1.3Intended Audience

The present document is intended to be read by the following teams, but not limited to:

• DG MARKT Team;

• Development Teams.

2General Framework Structure

The framework consists of the modules below.

The core building blocks of SD-DSS:

• dss-common

Contains the XSD schemas needed to parse and create Java classes for XAdES signature and TSL management (using JAXB as underlying technology). Additionally there are a very limited amount of other classes used by trusted list manager (TLManager).

• dss-document

That is the most important module that allows to easy sign a document and to verify a signature. Different forms of signatures are implemented: XAdES CAdES, PAdES and ASiC.

• dss-itext

This module was removed. The iText library for handling PDFs was replaced by PDFBox library.

• dss-report

This module was removed. It allowed creating the technical validation report, indeed the result of the validation process is now represented in the generic form of XML.

• dss-spi

It provides the Service Provider Interface of SD-DSS framework. It contains utility classes and some common functionality (PKCS#11, PKCS#12, MS CAPI…).

• dss-service

This module provides the server-side implementation of services for TSL handling, revocation data and certificates retrieval.

The integration building blocks of SD-DSS framework:

• dss-webservices

This defines and implements a SOAP web service of SD-DSS server. This endpoint permits the use of web service functionality from a third party application.

• dss-webservices-client

This module contains client side implementation of web services. It is used for demonstration purpose in the applet.

MOCCA integration:

• sscd-mocca-adapter

This module provides the integration layer for MOCCA within the SD-DSS framework.

Some examples/demonstrations on how to use SD-DSS framework:

• dss-demo-webapp

This is a Spring MVC based web application that provides an intuitive user interface giving access to an applet; implements the server-side logic and an administration part.

• dss-demo-applet

This provides an applet with the following functionalities:

• Signing a document (including the communication with a SSCD);
• Extending an existing signature;
• Validating a signed document (including creation of simple validation report, detailed validation report and diagnostic data);
• Editing the validation policy.

Below you find a list of classes (under the eu.europa.ec.markt package) with their brief descriptions used in the examples of this cookbook:

NOTE:

The source code of the CookBook facility classes is included in this document, please follow the links.

Class / Package / Module
AlwaysValidOCSPSource(C) / cookbook / CookBook facility classes
A utility test class that simulates the use of OCSP.
ASiCXMLSignatureService (C) / *.dss.signature.cades / dss-document
ASiC-S signature implementation based on DocumentSignatureService.
CAdESService (C) / *.dss.signature.cades / dss-document
CAdES implementation of DocumentSignatureService.
DSSDocument (I) / *.dss.signature / dss-spi
Interface representing any document (signed or to be signed).
DocumentSignatureService (I) / *.dss.signature / dss-document
This interface provides operations to sign (also extend) and to verify a document.
FileDocument (C) / *.dss.signature / dss-document
Document implementation stored on file-system
InMemoryDocument (C) / *.dss.signature / dss-document
In memory representation of a document
MockTSLCertificateSource(C) / cookbook / CookBook facility classes
A utility test class that simulates the use of TSL.
MockTSPSource(C) / cookbook / CookBook facility classes
A utility test class that simulates the use of TSP.
PAdESLevelBaselineLTA (C) / *.dss.signature.pades / dss-document
Extends a PAdES signature by incorporating an archive timestamp.
PAdESService (IC) / *.dss.signature.pades / dss-document
PAdES implementation of the DocumentSignatureService.
SignatureLevel (E) / *.dss.signature / dss-document
All signature levels handled by the framework
SignaturePackaging (E) / *.dss.signature / dss-document
Packaging method of the signature
SignatureParameters (C) / *.dss.signature / dss-document
Parameters driving the signature creation/extension
SignedDocumentValidator (C) / *.dss.validation102853 / dss-document
Validates the signed document
CommonCertificateVerifier (C) / *.dss.validation102853 / dss-document
Verifies the status of a certificate using provided sources of information.
XAdESService (C) / *.dss.signature.xades / dss-document
XAdES implementation of DocumentSignatureService
AbstractSignatureTokenConnection / *.dss.signature.token / dss-spi
(AC) Sometimes, the signature process has to be split in two phases: the digest phase and the encryption phase. This separation is useful when the file and the SSCD are not on the same hardware. Four implementations of this abstract class are provided.
CertificateSource (I) / *.dss.validation102853 / dss-spi
The validation of a certificate requires accessing some other certificates from multiple sources (Trusted List, Trust Store, the signature itself). This interface provides an abstraction for accessing a certificate, regardless of the source.
DigestAlgorithm (E) / *.dss / dss-spi
Models a list of digest algorithms. Not all of them are supported.
DSSPrivateKeyEntry (I) / *.dss.signature.token / dss-spi
This interface represents a PrivateKey.
KeyStoreCertificateSource (C) / *.dss.validation102853 / dss-spi
Implements a CertificateSource using a JKS KeyStore.
Pkcs12SignatureToken (C) / *.dss.signature.token / dss-spi
Class holding all PKCS#12 file access logic.
SignatureTokenConnection (I) / *.dss.signature.token / dss-spi
This interface represents a connection through available API to the SSCD (SmartCard, MSCAPI, PKCS#12, MOCCA)
CommonsHttpDataLoader (C) / *.dss.validation.https / dss-service
Implementation of HTTPDataLoader using HttpClient. More flexible for HTTPS without having to add the certificate to the JVM TrustStore.
OnlineCRLSource (C) / *.dss.validation.crl / dss-service
This Online CRL repository implementation downloads the CRLs from the given CRL URIs.
OnlineTSPSource (C) / *.dss.validation.tsp / dss-service
Class encompassing a RFC 3161 TSA, accessed through HTTP(S) to a given URI
TrustedListsCertificateSource (C) / *.dss.validation102853.tsl / dss-service
Certificates coming from the Trusted List

3Signature’s Profile simplification

The different formats of the digital signature make possible to cover a wide range of real live cases of use of this technique. Thus we distinguish the following formats: XAdES, CAdES, PAdES and ASIC. To each one of them a specific standard is dedicated. The wide variety of options, settings and versions of the standards makes their interoperability very difficult. This is the main reason for which new standards commonly called «baseline profiles» were published. Their goal is to limit the number of options and variants thereby making possible a better interoperability between different actors.