|
libdigidocpp 4.5.0
|
|
libdigidocpp 4.5.0
|
Libdigidocpp is a C++ library for creating applications that create and verify digital signatures. Digitally signed files are created as Associated Signature Containers (ASiC), using the .asice file extension and XML Advanced Electronic Signatures (XAdES) standardized by the European Telecommunications Standards Institute (ETSI).
Additionally, the libdigidocpp library can create, save, read, validate, and extend digitally timestamped containers (using the .asics file extension) with a single data file and RFC 3161 time-stamp tokens. ASiC containers with CAdES signatures, PDF, and DDOC files can be validated with the SiVa service.
Development of the library can be monitored in GitHub environment: https://github.com/open-eid/libdigidocpp.
Changes by version are listed on the separate Release Notes page.
Libdigidocpp library forms a part of the wider DigiDoc system framework which offers a full-scale architecture for digital signature and documents, consisting of software libraries (C++ and Java), SiVa service and end-user applications such as DigiDoc4 according to the following figure:
It is easy to integrate DigiDoc components into existing applications in order to allow for creation, handling, forwarding and verification of digital signatures. All applications share common digitally signed file formats.
Actively used digitally signed file formats in DigiDoc system are:
The following chapters provide an overview of the ASiC-E (XAdES) digitally signed file format, which is the preferred format for creating signed documents with Libdigidocpp.
The ETSI standard EN 319 162-1 defines a container format for encapsulating signed files, signatures, and supporting information. ASiC-E documents use the Extended form and contain signatures conforming to XAdES EN 319 132-1.
ASiC-E container is a ZIP file consisting of the following objects:
When ASiC-E container is signed then all files in the container are signed, except of the mimetype file and files in META-INF subdirectory.
Original files (which were signed) along with the signature(s), timestamp(s), validation confirmation(s) and certificates are encapsulated within the container. As a result, it is possible to verify signature validity without any additional external information – the verifier should trust the issuer of signer’s certificate, TS Authority and the OCSP responder’s certificate.
The format of the BDOC 2.1 digitally signed file is based on ETSI XAdES TS 101 903 standard. The XAdES standard defines formats for advanced electronic signatures that remain valid over long periods of time. The ETSI standard TS 103 171 "XAdES Baseline Profile" further profiles the XAdES signature by putting limitations on choices.
BDOC 2.1 specification defines two profiles of qualified BDOC signatures: BDOC with time-mark and BDOC with time-stamp. Both of the profiles offer long-term validation possibility by incorporating the necessary validation data in the signature. Both of the profiles are compliant to XAdES LT-Level requirements.
The BDOC signature with time-mark is based XAdES-EPES signature (Explicit Policy based Electronic Signature, see XAdES).
In order to offer long time validation, it is necessary to obtain proof of validity of the signer’s X.509 digital certificate issued by a certificate authority (CA) at the time of signature creation. In case of BDOC with time-marks (TM profile), the proof is obtained with a single OCSP response that has a specific "nonce" field’s value (i.e. the time-mark).
The hash of the created signature (the <SignatureValue> element’s contents) is sent within the OCSP request’s and received back within the response’s "nonce" field. The OCSP request’s and response’s "nonce" field is a DER-encoding of the following ASN.1 data structure:
The element digest is a hash value of the binary value of the <SignatureValue> element’s contents, element algorithm determines the used hash algorithm as defined in RFC 5280 clause 4.1.1.2.
The time-mark provides proof of the following:
It is important to notice that additional time-stamps are not necessary as time of signing and time of obtaining validity information is indicated in the OCSP response (i.e. the time-mark).
To achieve long-time validity of digital signatures, a secure log system is employed within the model. All OCSP responses and changes in certificate validity are securely logged to preserve digital signature validity even after private key compromise of CA or OCSP responder.
The BDOC signature with time-stamp is based on XAdES-BES signature (Basic Electronic Signature, see XAdES).
In order to offer long time validation, it is necessary to obtaining proof of validity of the signer’s X.509 digital certificate issued by a certificate authority (CA) at the time of signature creation.
In case of BDOC with time-stamp (TS profile), the proof is provided as follows:
In addition to the Associated Signature Extended form (ASiC-E), the ETSI standard EN 319 162-1 defines a Simple form which is used for encapsulating a single data file and a signature or time-stamp token associated with it.
An ASiC-S container is a ZIP file consisting of the following objects:
Since version 3.17.0, libdigidocpp can open and locally validate ASiC-S containers containing XAdES signatures in META-INF/signatures.xml. This variant is read-only: creating, adding signatures to, and saving ASiC-S/XAdES containers are not supported.
The library also supports local creation and validation of ASiC-S containers with a time-stamp token (the container includes META-INF/timestamp.tst). The time-stamp token is a binary representation of TimeStampToken as defined in RFC 3161. The time-stamp is obtained from a time-stamping service and is calculated over the entire binary content of the data object. Since both the original file and time-stamp are included in the container, it is possible to verify that the timestamped file existed at a certain point of time.
An existing time-stamp token can be extended by adding an ASiC archive manifest and a new time-stamp token. Each new layer protects the data object and the preceding time-stamp information. See Extending container validity for the high-level validity-extension workflow.
| BDOC2.1:2013 | BDOC – Format for Digital Signatures. Version 2.1:2013 https://www.skidsolutions.eu/repository/bdoc-spec21.pdf |
| DigiDoc format | DigiDoc file format https://www.id.ee/wp-content/uploads/2020/08/digidoc_format_1.3.pdf |
| XML-DSIG | IETF RFC 3275: "XML-Signature Syntax and Processing" |
| XML-DSIG 1.1 | XML Signature Syntax and Processing. Version 1.1 |
| XAdES | ETSI EN 319 132-1 V1.3.1 (2024-07) - Building blocks and XAdES baseline signatures https://www.etsi.org/deliver/etsi_en/319100_319199/31913201/01.03.01_60/en_31913201v010301p.pdf |
| XAdES Validation | ETSI TS 102 853 V1.1.2 (2012-10) – Signature validation procedures and policies http://www.etsi.org/deliver/etsi_ts/102800_102899/102853/01.01.02_60/ts_102853v010102p.pdf |
| CAdES EN | ETSI EN 319 122-1 V1.2.1 (2021-10) - Building blocks and CAdES baseline signatures https://www.etsi.org/deliver/etsi_en/319100_319199/31912201/01.02.01_60/en_31912201v010201p.pdf |
| PKWARE ZIP | ZIP File Format Specification |
| OpenDocument | OASIS "Open Document Format for Office Applications. Version 1.2 Part 3: Packages" http://docs.oasis-open.org/office/v1.2/cs01/OpenDocument-v1.2-cs01-part3.html#__RefHeading__752803_826425813 |
| ASiC | ETSI EN 319 162-1 V1.1.1 (2016-04) - Associated Signature Containers http://www.etsi.org/deliver/etsi_en/319100_319199/31916201/01.01.01_60/en_31916201v010101p.pdf |
| PDF (PAdES) | ETSI EN 319 142-1 V1.1.1 (2016-04) - PAdES digital signatures https://www.etsi.org/deliver/etsi_en/319100_319199/31914201/01.01.01_60/en_31914201v010101p.pdf |
| RFC 2045 | Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies |
| RFC 2253 | Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names. Obsoleted by RFC 4514. |
| RFC 4514 | Lightweight Directory Access Protocol: String Representation of Distinguished Names |
| RFC 3161 | Internet X.509 Public Key Infrastructure Time-Stamp Protocol (TSP) The TSTInfo |
| RFC 3739 | Internet X.509 Public Key Infrastructure: Qualified Certificates Profile |
| RFC 3986 | Uniform Resource Identifier (URI): Generic Syntax |
| RFC 4051 | Additional XML Security Uniform Resource Identifiers. Obsoleted by RFC 6931. |
| RFC 6931 | Additional XML Security Uniform Resource Identifiers. Obsoletes RFC 4051 and is obsoleted by RFC 9231. |
| RFC 9231 | Additional XML Security Uniform Resource Identifiers |
| RFC 4519 | Lightweight Directory Access Protocol: Schema for User Applications |
| RFC 5035 | Enhanced Security Services (ESS) Update: Adding CertID Algorithm Agility |
| RFC 5280 | Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile |
| RFC 6960 | X.509 Internet Public Key Infrastructure Online Certificate Status Protocol (OCSP) |
| RFC 8954 | Online Certificate Status Protocol (OCSP) Nonce Extension |
| Trusted Lists | ETSI TS 119 612 V2.2.1 (2016-04) https://www.etsi.org/deliver/etsi_ts/119600_119699/119612/02.02.01_60/ts_119612v020201p.pdf |
| SiVa | Digital signature validation web service that provides SOAP and JSON API to validate files |
| Release notes | Libdigidocpp library’s release notes |
| ETSI TS 102 280 (V1.1.1) | X.509 V3 Certificate Profile for Certificates Issued to Natural Persons http://www.etsi.org/deliver/etsi_ts/102200_102299/102280/01.01.01_60/ts_102280v010101p.pdf |
| QC Certificate Profiles | ETSI EN 319 412-1 V1.7.1 – Certificate Profiles; Part 1: Overview and common data structures http://www.etsi.org/deliver/etsi_en/319400_319499/31941201/01.07.01_60/en_31941201v010701p.pdf |
| QC Certificate Policy | ETSI EN 319 411-2 V2.6.1 – Policy requirements for Trust Service Providers issuing EU qualified certificates http://www.etsi.org/deliver/etsi_en/319400_319499/31941102/02.06.01_60/en_31941102v020601p.pdf |
| DigiDoc libraries | https://www.id.ee/en/rubriik/digidoc-libraries/ |
| ID-software GitHub project | https://github.com/open-eid |
| Libdigidocpp GitHub project | https://github.com/open-eid/libdigidocpp |
| ASiC | Associated Signature Containers |
| ASiC-E | Extended Associated Signature Containers. A type of ASiC container. |
| ASiC-S | Associated Signature Container Simple form. A type of ASiC container. |
| BDOC 2.1 (.bdoc) | Term is used to denote a digitally signed file format which is a profile of XAdES and follows container packaging rules based on OpenDocument and ASiC standards. The document format has been defined in BDOC2.1:2013, an overview is provided in chapter Format of digitally signed file of the current document. |
| CRL | Certificate Revocation List, a list of certificates (or more specifically, a list of serial numbers for certificates) that have been revoked, and therefore should not be relied upon. |
| DIGIDOC-XML (.ddoc) | The term is used to denote a DigiDoc document format that is based on the XAdES standard and is a profile of that standard. The current version is 1.3 which has been described in DigiDoc format. |
| ECDSA | Elliptic Curve Digital Signature Algorithm. Digital Signature Algorithm (DSA) which uses elliptic curve cryptography. Used as an alternative to RSA algorithm. |
| OCSP | Online Certificate Status Protocol, an Internet protocol used for obtaining the revocation status of an X.509 digital certificate |
| OCSP Responder | OCSP Server, maintains a store of CA-published CRLs and an up-to-date list of valid and invalid certificates. After the OCSP responder receives a validation request (typically an HTTP or HTTPS transmission), the OCSP responder either validates the status of the certificate using its own authentication database or calls upon the OCSP responder that originally issued the certificate to validate the request. After formulating a response, the OCSP responder returns the signed response, and the original certificate is either approved or rejected, based on whether or not the OCSP responder validates the certificate. |
| PAdES (.pdf) | Term is used to denote a digitally signed PDF file format which is based on PAdES standards. |
| SK | SK ID Solutions AS. Certificate Authority in Estonia |
| time-mark | Mechanism used for adding certificate validity and signing time information with the signature. The information is provided with a special OCSP confirmation (also referred to as time-mark) - hash value of the binary value of the signature (along with hash algorithm identifier in case of BDOC 2.1 document format) must be present in the "nonce" field of the OCSP confirmation. In this case, signature creation time is the issuance time of the OCSP confirmation (producedAt value in the confirmation), additional time-stamp service is not required. The respective signature profile is TM profile (supported in case of DIGIDOC-XML 1.3 and BDOC 2.1 document formats). |
| time-stamp | Mechanism used for adding certificate validity and signing time information with the signature. The certificate validity information is added to the signature with an OCSP confirmation; the signing time information is added with a time-stamp token retrieved form a time-stamping service. In this case, signature creation time is the issuance time (RFC 3161 TSTInfo.genTime) of the time-stamp token. The respective signature profile is TS profile. |
| archive time-stamp | Mechanism used for providing long term validity of a XAdES signature. The signature and validation data values are time-stamped. The respective signature profile is TSA profile. |
| TSA | Time-Stamping Authority. Time-stamping service provider. |
| TSL | Trust Service status List. Signed list that provides information about the status and the status history of the trust services (including certification, OCSP confirmation and time-stamping services). Used as a trust anchor in case of signature creation and validation to check the trustworthiness of the certificates that are included in the signature. See also Trusted Lists |
| X.509 | an ITU-T standard for a public key infrastructure (PKI) and Privilege Management Infrastructure (PMI) which specifies standard formats for public key certificates, certificate revocation lists, attribute certificates, and a certification path validation algorithm |
| XAdES | XML Advanced Electronic Signatures, a set of extensions to XML-DSIG recommendation making it suitable for advanced electronic signature. Specifies precise profiles of XML-DSIG for use with advanced electronic signature in the meaning of European Union Directive 1999/93/EC. |
| XML-DSIG | a general framework for digitally signing documents, defines an XML syntax for digital signatures and is defined in the W3C recommendation XML Signature Syntax and Processing |
Libdigidocpp is a library of C++ classes offering the functionality of handling digitally signed files in supported DigiDoc formats. The following functions are implemented:
The following table gives overview of functional features that are supported with Libdigidocpp.
| Feature | Supported values |
|---|---|
| DigiDoc document format |
|
| Signature profile | Signature profiles are based on the profiles defined by XAdES (XAdES).
|
| Trust anchors | Information of trusted CA certificates (trust anchors) is used to validate the trustworthiness of certificates used in the signature. The signer certificate's CA, OCSP responder certificate and time-stamping service's certificate (in case of TS signature profile) must be trusted. Trusted certificates' information is obtained from TSL list (Trust Service status list), the trusted certificates' list is retrieved from a signed TSL list that provides information about the status and the status history of the trust services (including certification, OCSP confirmation and time-stamping services). The European Commission's TSL list is used, more information of which can be found from https://ec.europa.eu/information_society/policy/esignature/trusted-list/. For the TSL specification document, see also Trusted Lists. For more information about the TSL implementation and configuration possibilities in Libdigidocpp library, see TSL list usage in Libdigidocpp and Trust anchor/TSL settings. |
| Signature creation module |
|
| Cryptographic token type |
|
| Public-key algorithm |
|
The figure below describes the architecture of software and hardware components that are used when creating signatures with Libdigidocpp library.
| Component | Description |
|---|---|
| PKCS#11 | Widely adopted platform-independent API to cryptographic tokens (HSMs, smart cards and USB tokens), a standard management module of the cryptographic token and its certificates |
| CryptoAPI | Microsoft Cryptography API. Programming API for implementing cryptographic functions in Windows environment. |
| PC/SC | Standard communication interface between the computer and the smart card, a cross-platform API for accessing smart card readers |
| IFDHandler | Interface Device Handler for CCID readers |
| CCID | USB driver for Chip/Smart Card Interface Devices |
| Reader | Device used for communication with a smart card |
Libdigidocpp library depends on the software libraries listed below.
| Base Component | Required/optional | Description |
|---|---|---|
| OpenSSL | required | Used for validating certificates and digest values. |
| libxml2 | required | Used for validating the documents according to XML Schema, reading and writing XML. |
| xmlsec | required | Used for handling signature related components. |
| ZLIB | required | Used when compressing and extracting ASiC files in ZIP format. |
| Minizip | required | Used when creating and opening ZIP container for ASiC file. If the component is not found from system then bundled version with source code is used. Forms a part of ZLIB component. |
| PKCS11 | optional | Used for searching for default PKCS#11 driver in the system so that its path could be registered in configuration entries. |
| Doxygen | optional | Used for generating API documentation from source code. |
| SWIG | optional | Used for creating C#, Java, and Python bindings. |
Several XML schemas are used when creating digitally signed documents in ASiC file format and validating their structure. The schemas are included in etc/schema/ subdirectory of the Libdigidocpp distribution package, their description is given in the table below.
| Schema file | Description |
|---|---|
| OpenDocument_manifest.xsd | OASIS OpenDocument v1.2 (OpenDocument) Defines the structure of META-INF/manifest.xml file in ASiC container. https://docs.oasis-open.org/office/v1.2/csd06/OpenDocument-v1.2-csd06-manifest-schema.rng |
| OpenDocument_dsig.xsd | OASIS OpenDocument v1.2 (OpenDocument) Defines the structure of META-INF/signature.xml file in ADOC container. https://docs.oasis-open.org/office/v1.2/csd06/OpenDocument-v1.2-csd06-dsig-schema.rng |
| en_31916201v010101.xsd | Associated Signature Containers (ASiC) Defines the format of container for encapsulating the signed documents, signatures and additional information. http://www.etsi.org/deliver/etsi_ts/102900_102999/102918/01.02.01_60/ |
| xmldsig-core-schema.xsd | XML Signature Core Schema Instance (XML-DSIG) Defines XML syntax for digital signatures. http://www.w3.org/TR/2008/REC-xmldsig-core-20080610/xmldsig-core-schema.xsd |
| XAdES01903v132-201601.xsd | XML Advanced Electronic Signatures (XAdES EN) Defines a set of extensions to XML-DSIG making it suitable for advanced electronic signature. http://uri.etsi.org/01903/v1.3.2/XAdES01903v132-201601.xsd |
| XAdES01903v141-201601.xsd | Defines XML syntax for additional elements of XAdES signatures that were added with version 1.4.1 of the (XAdES EN) standard. Used for XAdES archive time-stamps, including the ArchiveTimeStamp element. http://uri.etsi.org/01903/v1.4.1/XAdES01903v141-201601.xsd |
| ts_119612v020201_201601xsd.xsd ts_119612v020101_additionaltypes_xsd.xsd ts_119612v020101_sie_xsd.xsd | Defines the format of Trust Service status Lists (TSL) that contain information about trusted CA, OCSP and TSA certificates. |
| conf.xsd | Configuration properties’ schema. Defines the Libdigidocpp configuration file’s digidocpp.conf structure (see also Configuring Libdigidocpp). |
The following figure describes dependencies between the abovementioned schemas (direction of the arrow indicates the direction of dependency).
The following section describes modifications that have been made to XML schemas used in Libdigidocpp. The library uses several XML schemas when creating digitally signed documents and validating their structure. The schemas are included in etc/schema/ subdirectory of the Libdigidocpp distribution package, their description has been provided in section XML Schemas.
Modifications are marked between xml comment tags.
Schema en_31916201v010101.xsd
1) The schema’s location has been altered so that the imported schema file is looked up from the local file system.
2) Additional schema’s location imports has been added so that the imported schema file is looked up from the local file system.
Schema xmldsig-core-schema.xsd
1) The XMLSchema.dtd reference has been commented out due to implementation issues (otherwise a warning message would be produced).
2) The initial integer data type used in the original schema is converted into long data type when generating C++ source code from the current schema. However, as the SK issued certificates’ serial numbers are too long to fit into long type variable then the data type has been changed to string.
Schema XAdES01903v132-201601.xsd
1) The schema’s location has been modified so that the file is looked up from the local file system.
2) The "type" attribute has been added, otherwise a warning message would be produced.
3) The "type" attribute has been added, otherwise a warning message would be produced.
4) Change child elements of type SignedSignaturePropertiesType from "xsd:sequence" to "xsd:all" in order to allow the child elements to be listed in any order.
5) Change child elements of type SignatureProductionPlaceType from "xsd:sequence" to "xsd:all" in order to allow the child elements to be listed in any order.
Schema XAdES01903v141-201601.xsd
1) The schema's location has been modified so that the file is looked up from the local file system.
Schema ts_119612v020201_201601xsd.xsd
1) The schemas' locations have been modified so that the file is looked up from the local file system.
2) The schemas' locations have been added so that TSL extension content can be validated through lax processing.
Schema ts_119612v020101_sie_xsd.xsd
1) The schemas' locations have been modified so that the file is looked up from the local file system.
Schema ts_119612v020101_additionaltypes_xsd.xsd
1) The schemas' locations have been modified so that the file is looked up from the local file system.
Libdigidocpp uses XML configuration file named digidocpp.conf. Configuration file's structure is defined with XML schema "conf.xsd" - the file is included in etc/schema/ subdirectory of Libdigidocpp package. For a sample configuration file, see Sample configuration file.
It is possible to use two types of configuration files: global and user's file. Global file can be used to determine system-wide settings that cannot be altered by a user's file – it can be done separately for each parameter in the file by setting the parameter's "lock" attribute value to "true". User's file can be used to determine user-specific parameter values.
It is possible to use only one configuration file (either global or user's file) or two files in parallel. In the latter case, the matching user file's parameter entries overwrite global file's entries, if the respective parameter is not defined as locked in the global file.
By default, the configuration file's settings are loaded during the library's initialization – Libdigidocpp looks for global and user configuration files from their default locations depending on the environment:
It is also possible to load global configuration file from a non-default location. In this case, call out the configuration file's initialization method before initializing the library:
Local configuration settings can also be set or modified during runtime by calling out the respective set methods of XmlConf class. The digidoc::XMLConf class must be used in order to access all the configuration methods that are available.
Configuration file's elements and their attribute names are defined in conf.xsd file. Below is a description of the configuration file's parameters. The attribute "lock", when set to "true" can optionally be used to determine parameter values which should not be overwritten by another configuration file (e.g. when using global and user's configuration files in parallel; see also the previous section for more information).
| Parameter name | Comments |
|---|---|
| log.file | Location of the log file where the logging output is written, e.g. /tmp/digidocpp.log or C:\Temp\digidocpp.log If left unspecified then the logging output is written to standard output stream. |
| log.level | Used for controlling the level of detail of the logging output messages, higher number value indicates higher level of detail. Possible values are: 1 – error messages, 2 – warning messages, 3 – info messages, 4 – debug messages. |
| Parameter name | Comments |
|---|---|
| ts.url | Specifies the URL of the time-stamping service that is used during signature creation, needed only in case of TS signature profile. By default, the RIA's time-stamping service is used by the library (https://eid-dd.ria.ee/ts) |
| Parameter name | Comments |
|---|---|
| verify.serivceUri | Specifies the URL of the signature-verify service that is used during signature validation. By default, the RIA's signature-verify service is used by the library (https://siva.eesti.ee/V3/validate) |
| Parameter name | Comments |
|---|---|
| pkcs11.driver.path | PKCS#11 driver library to be used when communicating with the smart card. With Estonian ID cards for example, the following PKCS#11 libraries are used: opensc-pkcs11.so (used in Linux environment) opensc-pkcs11.dll (used in Windows environment) |
Information of trusted CA certificates (trust anchors) is used to validate the trustworthiness of certificates used in the signature during signing and signature validation processes. The signer certificate's CA, OCSP responder certificate and time-stamping service's certificate (also referred to as time-stamping authority, TSA) must be trusted.
Libdigidocpp library uses Trust Service Status List (TSL) as a source of trust anchor information (see also TSL list usage in Libdigidocpp and TSL standard for more information). A TSL list is a signed XML file that contains data of trusted CA certificates, OCSP responder service and time-stamping service certificates. Note that since v3.10, only TSL lists' based trust anchors are supported by the library.
By default, the trusted certificates' information is obtained from European Commission's official TSL list (https://ec.europa.eu/tools/lotl/eu-lotl.xml). The default TSL behaviour can be changed by altering the configuration parameters listed below.
| Parameter name | Comments |
|---|---|
| tsl.autoupdate | Determines if TSL validity is checked during every initialization of the library and if new TSL lists are downloaded if the existing list is expired. By default, the automatic update functionality is enabled and can be disabled by setting the parameter's value to "false". Note that when setting the parameter to "false" then you should copy the necessary TSL files to the "tsl.cache" location manually. |
| tsl.cache | Directory in the file system where the TSL lists are saved and read in by the library. Set this parameter with your own value to change the default directories:
|
| tsl.onlineDigest | Additional feature to optimize TSL updating process. By default, the value is "true", meaning that during each initialization of the library, it is checked if there is a newer TSL list published, even if the existing TSL list is not yet expired. The check is based on the TSL list's HTTP HEAD request ETag field or SHA-256 digest value.
|
| tsl.timeOut | TSL downloading timeout for each TSL list. The default value is 10 seconds. |
| Parameter name | Comments |
|---|---|
| proxy.host | Specifies the proxy hostname, e.g. proxy.example.net |
| proxy.port | Specifies the proxy port, e.g. 8080 |
| proxy.user | Specifies the proxy username. |
| proxy.pass | Specifies the proxy password. |
| proxy.tunnelSSL | May be used to enable downloading TSL-s in case of HTTPS connections and proxy. If enabled, the library tries to download use the proxy tunnel also for the HTTPS session. |
| proxy.forceSSL | May be used to enable downloading TSL-s in case of HTTPS connections and proxy. If enabled then the library tries to pass by the proxy connection in case of HTTPS sessions. |
| Parameter name | Comments |
|---|---|
| signer.signatureDigestUri | Specifies the digest algorithm that is used when calculating the hash that is being signed. By default, the SHA-256 algorithm (with URI http://www.w3.org/2001/04/xmlenc#sha256) is used |
| signer.digestUri | Specifies the digest algorithm that is used for calculating all the hash values in the signature. By default, the SHA-256 algorithm is used |
The default OCSP responder that the library uses for retrieving the OCSP confirmation during signature creation depends on the signer's certificate chain. In case of no issuer is configured AIA extension is used for OCSP responder settings
You change the default behaviour in the configuration file with the following parameter.
| Parameter name | Comments |
|---|---|
| ocsp issuer | The "issuer" parameter's name stands for the signer certificate issuer's Common Name (CN) value, e.g. ESTEID-SK 2015. The element's value specifies OCSP responder server's URL address that is used for certificates issued from the respective CA chain. |
Note that Libdigidocpp uses internal memory buffers in case of all the operations, so that intermediary data is not written to temporary files on the disk. Also, the data files to be added to a DigiDoc container can be read from a data stream and later extracted from the container to a stream so that the data can be kept in memory.
All std::string values passed to or returned from the API are UTF-8 encoded. This applies to file paths, media types, and all other string parameters and return values throughout the library.
Libdigidocpp's initialization method conducts the following operations:
If you would like to use non-default configuration settings then call out the configuration file's initialization before initializing the library, for example:
The digidoc::XmlConf class must be used in order to access all the configuration methods that are available.
Create a new container object and specify the DigiDoc document's type, for example:
Container class is used to incorporate the data of a DigiDoc document.
Create an ASiC-S container by using an .asics or .scs output file name. An ASiC-S TimeStampToken container supports exactly one data file and one initial RFC 3161 time-stamp token.
ASiC-S TimeStampToken creation uses the one-step digidoc::Container::sign method. External two-step signing with digidoc::Container::prepareSignature is not supported for this format. Additional archive-manifest time-stamp layers can be added with the workflow described in Extending container validity.
Data files can be added to a DigiDoc container in two alternative ways:
Parameter mediaType in the methods above stands for a MIME type of the data file, for example "text/plain" or "application/msword". Value "application/octet-stream" is used by default. Calling out any of the methods listed above shall create a new DataFile object and add it to the DigiDoc container's data file collection. Note that in order to add a data file to a container, the container has to be unsigned and there shouldn't be an existing data file with the same name in the container. If a container is signed then it is possible to add data files to it only after the signatures are removed.
The stream overload's fileName is the name stored inside the container. It must be a single non-empty path component: ".", "..", forward slashes, and backslashes are rejected. The file-system overload accepts a source path and stores only its base name. When an existing ASiC-E container is opened, safe relative subdirectories separated by forward slashes are accepted, but absolute paths, backslashes, trailing slashes, and empty, ".", or ".." path segments are rejected. ASiC-S data files must be at the container root.
It is possible to add a signature to a container only if it contains at least one data file, multiple signatures can be added to a single container. The signer's certificate and PIN code to access the private signature key are required during signing.
Signing can be done by using PKCS#11 module for accessing the signature token. PKCS#11 module is the default module for singing with smart card (e.g. Estonian ID card or any other smart card provided that you have the external native language PKCS#11 driver for it). See also PKCS#11 settings.
If you would like to add PIN insertion dialog window for the signer to enter the PIN code then you can write a new class which extends the PKCS11Signer class, overwrite the std::string pin(const X509Cert &cert) method and write your own PIN dialog implementation code there.
The supported signature profiles are (see also Supported functional properties, under "Signature profiles"):
If the signature profile value is not specified then then a "time-stamp" profile is used by default.
Set the profile value as follows:
Signature production place and signer role are optional signed meta-data about the signature. If left unspecified then the respective elements in the signatures*.xml file are created with no contents.
By default, the hash that is being signed is calculated with SHA-256 algorithm. You can also use a different digest algorithm for calculating the hash that is signed (this does not affect calculating other hash values). For that, use the digidoc::Signer::setMethod(const std::string &method) method.
The signing method also adds validation data from external services (OCSP and time-stamping servers). Note that the OCSP responder and time-stamping server settings (in case of TS profile) should be configured before calling out the following method (see also Initialization and Configuration parameters). By default, the RIA's time-stamping service https://eid-dd.ria.ee/ts is used. Container holds the Signature object reference and there is no need cleanup memory.
After the signature has been added to the container, it should be validated before writing the signed container to an output file. For validating the signature, do as follows:
The validation method above validates the signed data files', signer certificate's and OCSP confirmation's correspondence to the signature value. Note that the validation method above does not validate other signatures which may belong to the same container.
After the signature has been added and validated, container changes should be saved (Reading and writing DigiDoc documents):
External signing (two-step signing) can be used in case of signing in web applications, where the signature value is calculated externally, via a browser plug-in or extension.
In order to conduct web signing with Libdigidocpp library, do as follows: Container holds the Signature object reference and there is no need cleanup memory.
In order to read an existing DigiDoc file from the file system, do as follows:
The method above reads in the DigiDoc file from the specified location in file system and creates the respective Container object representing the document's data. The file's structure is also validated during its parsing according to the corresponding standards.
Write a DigiDoc file (represented with a Container object) to file system with the following method:
Validation of a signed DigiDoc document consists of three main steps:
You can validate a signature and its validation data - OCSP confirmation and time-stamp (in case of TS profile) - with method:
If an exception is thrown from the validation method then the signature can be either INVALID or VALID WITH WARNINGS; otherwise the signature is VALID. Before determining the final validation status, additional errors must be checked, as described in the following chapters.
If an exception is thrown then its causes can be retrieved with the following method:
There is a validation case that is not checked in the default validation method of the library, instead, separate method for checking this specific situation has to be implemented by the library’s user. In Libdigidocpp library, checking for an old file format must be done separately.
The following subchapter describes how this check can be implemented. After checking for old signature format errors/warnings, collect all of the error codes and continue with determining the validation status as described in the next chapter. It is possible to check the source code of digidoc-tool or DigiDoc desktop application, accessible from https://github.com/open-eid/DigiDoc4-Client.
After validating the signed DigiDoc document, the validation result must be determined by the library's user. Final validation result must be one of the possible validation statuses that are described in the table below, the status must be chosen according to its priority. The validation status priorities have to be applied in two cases:
| Priority | Status | Error code | Description |
|---|---|---|---|
| 1 | INDETERMINATE/UNKNOWN | 10 CertificateIssuerMissing (signer's certificate is unknown) 6 CertificateUnknown (OCSP responder certificate is unknown) | Validation process determines that one or more of the certificates included in the document are unknown or not trusted, i.e. the certificates have been issued by an unknown Certificate Authority (the CA has not been added to trusted list). Notes:
Suggested warning message (also displayed in DigiDoc desktop application): "Signature status is displayed as unknown if you don't have all validity confirmation service certificates and/or certificate authority certificates available in TSL"
|
| 2 | INVALID | All errors except of the ones that are regarded as warnings by the library's user. | Validation process returns error(s), the errors have not been explicitly determined as minor error(s) by the library's user. |
3
VALID WITH WARNINGS
See the next section.
Validation process returns error(s) that have been previously explicitly categorized (by the library's user) as minor technical errors. Note that this status is used only in exceptional cases, more details of which are given in the next chapter.
4
VALID
N/A
Validation process returns no errors. The signature is legally valid.
The error codes described in the table above are defined in Exception.h source file.
Sample code of DigiDoc file validation can be found from digidoc-tool.cpp utility program, from the following method:
In special cases, validation errors can be regarded as minor technical errors and the file's validation status can be regarded as VALID WITH WARNINGS instead.
It is recommended to use the validation status VALID WITH WARNINGS in case of the error situations that are included in the table below - these error situations are regarded as VALID WITH WARNINGS in DigiDoc applications and software libraries, including:
Table 1. Validation error codes recommended to be handled as VALID WITH WARNINGS
| Error code | Related DigiDoc file format | Description |
|---|---|---|
| 12 RefereneceDigest Weak 13 SignatureDigestWeak | BDOC 2.1 / ASiC | Weaker digest method (SHA-1) has been used than recommended when calculating either <Reference> or <Signature> element's digest value. Suggested warning message (also displayed in DigiDoc desktop application): "The current DigiDoc container uses weaker encryption method than officially accepted in Estonia."
|
| 16 ProducedATLateWarning | BDOC 2.1 TS / ASiC | The difference between the time-stamp issuance time (RFC 3161 TSTInfo.genTime) and the OCSP response's issuance time (producedAt value) exceeds 15 minutes but is less than 24 hours. Suggested warning message: "Time-stamp and OCSP issuance time difference is over 15 minutes."
|
| 14 DataFileNameSpaceWarning | DDOC 1.0 DDOC 1.1 DDOC 1.2 DDOC 1.3 | <DataFile> element's xmlns attribute is missing. Suggested warning message (also displayed in DigiDoc desktop application): "This DigiDoc documents has not been created according to specification, but the digital signatures is legally valid. You are not allowed to add or remove signatures to this container." More info: https://www.id.ee/en/article/digital-signing-and-electronic-signatures/
|
| 15 IssuerNameSpace Warning | DDOC 1.1 DDOC 1.2 DDOC 1.3 | <IssuerSerial><X509IssuerName> and/or <IssuerSerial><X509SerialNumber> element's xmlns attribute is missing. Suggested warning message (also displayed in DigiDoc desktop application): "This DigiDoc documents has not been created according to specification, but the digital signatures is legally valid. You are not allowed to add or remove signatures to this container." More info: https://www.id.ee/en/article/digital-signing-and-electronic-signatures/
|
| N/A (Separate error code has not been determined. | DDOC 1.0 DDOC 1.1 DDOC 1.2 | DigiDoc file's version is older than currently supported. Note that the error situation affects only the container and not the signatures, therefore, in DigiDoc libraries, it is returned and displayed only at container level. Suggested warning message (also displayed in DigiDoc desktop application): "The current file is a DigiDoc container that is not supported officially any longer. You are not allowed to add or remove signatures to this container" More info: https://www.id.ee/en/article/digidoc-container-format-life-cycle-2/
|
Overview of validation activities is as follows:
For formats validated through SiVa, archive time-stamp information returned by the service is available through digidoc::Signature::ArchiveTimeStamps in the same way as locally validated archive time-stamps.
Since version 4.5.0, digidoc::Container::extendContainerValidity provides the high-level workflow for extending the validity evidence of a container. The method sets the required signer profile automatically and uses the following strategy:
Only signatures with an Estonian signing certificate are considered for in-place extension, and e-seal signatures are skipped. A container with no applicable Estonian signatures, or with only T-level signatures lacking OCSP validation data, cannot be extended by this workflow.
The returned unique pointer is empty when extension was performed in place. It contains the new ASiC-S container when wrapping was necessary; in that case extendedCount is zero. The caller must save the modified or newly returned container.
The generated language bindings expose the same workflow with language-specific return values:
In every binding, replace the original container with the returned container when the return value is not null/None, then save the resulting container. A null/None result means the original object was modified in place.
A data file can be extracted from container and written to the specified location in the file system or to an output stream.
List of all the document’s data files can be retrieved with the following method:
For example, read in a DigiDoc document and write its data files to file system as follows:
In order to remove a signature from DigiDoc document, use the following method:
Data files can be removed from a container only after all of its signatures have been removed. Use the following method to remove a data file from DigiDoc container:
The index parameters of the methods above are the signature and data file sequence numbers in the container, starting from zero.
After finishing work with Libdigidocpp, then the last task is to shut down the library:
The termination method closes libraries used in Libdigidocpp implementation and deletes temporary files that may have been written to disk when working with the library.
The Libdigidocpp library may throw exceptions that are instances of Exception class (defined in Exception.h source file). The code which uses Libdigidocpp’s API should be wrapped in a try/catch block as follows:
An Exception instance thrown by the library may contain a stack trace of the hierarchy of exceptions. For example, to parse the whole stack trace, do as follows:
The command line utility program digidoc-tool.exe which is included in the Libdigidocpp distribution can be used to test the library or simply use it directly to handle digitally signed documents.
The general format for executing the program is:
Available optional options on all commands:
| --nocolor | Disable terminal colors |
| --loglevel=[0,1,2,3,4] | Log level: 0 - none, 1 - error, 2 - warning, 3 - info, 4 - debug |
| --logfile= | File to log, empty to console |
Command "create" can be used to create a new DigiDoc container, add data files, optionally some meta-info about the signer and sign the document. The output extension selects ASiC-E (.asice or .sce) or ASiC-S (.asics or .scs). ASiC-S creation requires exactly one data file and the TimeStampToken signature profile. General form of the command is:
Available options:
| --file= | Required | Data file(s) to be signed. The option can occur multiple times.
|
| --mime= | Optional | Specifies the data file's mime-type value. When used then must be written right after the "--file" parameter. If left unspecified then the default mime-type value "application/octet-stream" is used.
|
| --dontsign | Optional | Don't sign the newly created container. |
Additional options for the "create" command are the same as for "sign" command (see Adding signatures).
Sample commands for creating and signing DigiDoc files:
Command "createBatch" Takes folder as argument folder/content/to/sign and sign them separate containers.
For additional options look sign command.
Command "add" for adding additional files to existing unsigned container.
Available options are –file and –mime look "create" command for info.
Command "websign" can be used to create a new DigiDoc container, add data files, optionally some meta-info about the signer and sign the document. Documents can be created only in ASiC-E format. External signing use case may be used when signing is done in web applications, the communication with the signer's token and signing the hash is done via a web browser's signing module (plug-in or extension). See also https://web-eid.eu for implementing signing in browser environment.
External signing process with websign command is as follows:
General form of the command is:
Available options:
| --cert= | Required | Signer's certificate, in PEM format. |
| --file= | Required | Data file(s) to be signed. The option can occur multiple times. |
| --mime= | Optional | Specifies the data file's mime-type value. When used then must be written right after the "--file" parameter. If left unspecified then the default mime-type value "application/octet-stream" is used. |
Additional options for the "websign" command are the same as for "sign" command (see Adding signatures).
Sample command for creating and external signing of ASiC-E files:
Command "open" reads an existing document, prints its contents and validates its signatures. The –extractAll option extracts data files to disk. Supported ASiC-E, ASiC-S and legacy BDOC 2.1 variants are handled locally. PDF, legacy DDOC and ASiC containers with CAdES signatures are sent to the SiVa Online Service for validation; –offline disables that fallback, so those service-backed formats cannot be opened offline. BDOC 1.0 is not supported. General form of the command is:
Available options:
| --extractAll | Optional | If set, then all of the input container’s data files are extracted and written to disk without validating signatures. If an output directory is not specified with the value of this parameter then the extracted files are written to the same directory where the input file is located. |
| –validateOnExtract | Optional | If set, then validates container before extracting files. |
| --offline | Optional | open container offline (eg. Don't send to SiVa) |
--warnings= (ignore, warning, error) | Optional | Enables to choose the displaying of validation warnings (if present) of the file being opened. Can be used to test the warnings system of the utility program (see also "Validation status VALID WITH WARNINGS"). The options include:
|
Output of the default command contains the following data of the container:
Sample commands for validating signatures and extracting data files:
Command "sign" enables adding XAdES signatures to existing ASiC-E and legacy BDOC 2.1 containers. The same signing options are used by "create" to add the initial RFC 3161 TimeStampToken to a new ASiC-S container; an existing ASiC-S container cannot receive another ordinary signature.
| --pin= | Optional | If PIN is not provided with this parameter value and (the default) PKCS#11 module is used for signing then the utility program asks for the user to insert PIN code to command line during the program’s execution time. |
| --profile= | Optional | Profile of the signature. Possible values are:
|
| --XAdESEN | Optional | Use XAdES EN profile. |
| --city= | Optional | City where the signature is created. |
| --street= | Optional | streetAddress of production place in XAdES EN profile. |
| --state= | Optional | State or province where the signature is created. |
| --postalCode= | Optional | Postal code of the place where the signature is created. |
| --country= | Optional | Country of origin. ISO 3166-type 2-character country codes are used (e.g. EE) |
| --role= | Optional | Signer’s role(s). The option can occur multiple times. |
| --sha(224,256,384,512) | Optional | Used for testing purposes. Specifies the hash function that is used when calculating digest values. If not specified then SHA-256 is used by default. |
| --sigsha(224,256,384,512) | Optional | Used for testing purposes. Specifies the hash function that is used for calculating the hash that is being signed. If not specified then SHA-256 is used by default. |
| --sigpsssha(224,256,384,512) | Optional | Used for testing purposes. With RSA keys RSA-PSS padding is used. Specifies the hash function that is used for calculating the hash that is being signed. If not specified then SHA-256 is used by default. Same as --sigsha* with --rsapss |
| --rsapkcs15 | Optional | Option to change RSA Signature padding (RSA PKCS1.5). |
| --rsapss | Optional | Option to change RSA Signature padding (RSA PSS). |
| --tsurl= | Optional | Option to change TS URL. |
| --userAgent= | Optional | Additional application information sent to the TSA or OCSP service. |
| --dontValidate | Optional | Don't validate container on signature creation. |
Options for specifying module used for accessing the signing token - possible alternatives are PKCS#11, CryptoAPI/CNG and PKCS#12 (for testing purposes). When signing module is not specified then PKCS#11 module is used by default.
| --pkcs11[=] | Optional | Signing is done via PKCS#11 module - the default module for singing with smart card in Linux and macOS. When signing via PKCS#11 module then the parameter’s value can be used to specify the path and filename of PKCS#11 driver in your file system. For example, "opensc-pkcs11.dll" in Windows environment and "opensc-pkcs11.so" in Linux and OSX. If the parameter’s value is left unspecified then PKCS#11 driver’s location is looked up from configuration file (see also chap. Configuration parameters). |
| --cng | Optional | Set the parameter to sign via Microsoft CNG API (in Windows environment). If "--pin" parameter’s value is not set then PIN insertion dialog is displayed to the user. Parameter "--cng" may optionally be used along with parameter "--selectFirst" or "--thumbprint". |
| --selectFirst | Optional | Additional parameter that can optionally be used along with parameter "–cng". When the parameter is set then the first certificate in Windows certificate store is chosen for signature creation. If the parameter is not set then certificate selection dialog window is displayed to user. |
| --thumbprint | Optional | Additional parameter that can optionally be used along with parameter "–cng". When the parameter is set then the certificate by thumbprint in Windows certificate store is chosen for signature creation. If the parameter is not set then certificate selection dialog window is displayed to user. |
| --pkcs12= | Optional | Signing is done via PKCS#12 module - can be used for testing purposes. Enables to use a PKCS#12 software token (containing the signing certificate and private key) for signature creation. Note that the created signature is not a valid signature and it is not equal to handwritten signature as the PKCS#12 software token is not considered a secure signature creation device. |
Sample commands for adding signatures:
Command "extend" adds new validity evidence and saves the result. Without –signature, it calls the high-level digidoc::Container::extendContainerValidity workflow: eligible ASiC-E or ASiC-S signatures are extended in place, or the original container is wrapped in a new timestamped ASiC-S container when necessary.
When one or more –signature options are specified, only those zero-based signature indexes are extended directly with digidoc::Signature::extendSignatureProfile. In this mode –profile selects the target profile and –dontValidate skips validation after each extension.
| --signature= | Optional | Zero-based signature index to extend directly. The option can occur multiple times. |
| --profile= | Optional | Target profile for direct per-signature extension: TS, TSA, time-stamp or time-stamp-archive. The high-level workflow chooses the required profile automatically when –signature is omitted. |
| --dontValidate | Optional | Do not validate a directly extended signature after extension. |
Signatures and data files can be removed from a DigiDoc container with the command "remove". Note that it is possible to remove data files only from an unsigned container (i.e all signatures must be removed before removing data files). The command is supported with DigiDoc formats BDOC 2.1 and ASiC-E. General format of the command is:
Available options:
| --document= | Optional | Specifies the sequence number of the data file that is removed from the container. The sequence numbers are counted from zero. |
| --signature= | Optional | Specifies the sequence number of the signature that is removed from the container. The sequence numbers are counted from zero. |
Sample commands for removing signatures and data files:
Libdigidocpp library uses Trust Service status Lists (TSL) as trust anchors. TSL lists are a standardized way to add support for cross-border trust-service providers, e.g. CA's that issue qualified certificates, OCSP service and time-stamping service providers (see also TSL specification). TSL list is a digitally signed a document in XML format, the list is accompanied with a TSL signing certificate that is used to validate the list's signature.
Libdigidocpp library uses the European Commission’s TSL list as the basis of retrieving data of trusted certificates. The European Commission's TSL list is also referred to as List of Trusted Lists (LOTL), meaning that it is central list that contains references to other TSL lists, in this case the national TSL lists of the European Union's member states.
Each of the national TSL list contains data (including the certificates) of the trust service providers that are approved in this particular country. Libdigidocpp supports all national TSL lists that are referred to in the LOTL (more than 30 countries).
TSL lists' initialization process is done during each initialization of the library. By default, the TSL itself and its freshness is checked on-line:
Libdigidocpp library supports the following identity tokens:
The library is also tested with the following tokens (indirectly via the DigiDoc desktop application that uses Libdigidocpp as a base component):
Automated cross-usability tests of digitally signed and encrypted files are periodically carried out between different DigiDoc software libraries:
The interoperability tests are executed through the command line utility tools of the software libraries (for example, in case of Libdigidocpp library, the utility program which is described in chapter Libdigidocpp utility program of the current document).
The following section describes properties of a BDOC 2.1 file that are not strictly defined in the BDOC 2.1 specification BDOC2.1:2013 but are used in Libdigidocpp library’s implementation (and also in other DigiDoc software libraries) of the file format.
1.9.8