libdigidocpp  3.18.0
Libdigidocpp Programmer's Guide

Table of Contents

Introduction

Libdigidocpp is the C++ library for creating applications handling digital signatures, their creation and verification. The digitally signed files are created in "DigiDoc format" (with .bdoc or .asice file extensions), compliant to XML Advanced Electronic Signatures (XAdES), technical standard published by European Telecommunication Standards Institute (ETSI).

Additionally the libdigidocpp library can be used to read and verify the digitally timestamped containers (using .asics file extension) with a single datafile. There is possible to validate PDF and legacy container formats with SiVa service.

Development of the library can be monitored in GitHub environment: https://github.com/open-eid/libdigidocpp

About DigiDoc

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, C++ and Java), SiVa service and end-user applications such as DigiDoc4 Client according to the following figure:

DigiDoc framework

It is easy to integrate DigiDoc components into existing applications in order to allow for creation, handling, forwarding and verification of digital signatures and support file encryption/decryption. All applications share common digitally signed file formats.

Format of digitally signed file

Actively used digitally signed file formats in DigiDoc system are:

  • BDOC 2.1 - default format for files in Libdigidocpp library, described in BDOC2.1:2013;
  • ASiC-S - timestamped container, described in The ETSI standard TS 102 918. The library implements only read-only support for the format.

The following chapters provides an overview of BDOC 2.1 digitally signed file format which is the preferred format for creating signed documents in Libdigidocpp library.

BDOC container format

The ETSI standard TS 102 918 called Associated Signature Containers (ASiC) defines format of container for encapsulation of signed files and signatures with extra information. The ETSI TS 103 174 "ASiC Baseline Profile" profiles in further on. The container type used in case of BDOC 2.1 documents is Associated Signature Extended form (ASiC-E).

ASiC-E container is a ZIP file consisting of the following objects:

  • a file named "mimetype", containing only the following value: application/vnd.etsi.asic-e+zip
  • data files in original format.
  • META-INF subdirectory, consisting of:
    • manifest.xml – a file containing list of all files in the container. The list does not contain the "mimetype" file and files in META-INF subdirectory.
    • signatures*.xml – one file for each signature, ‘*’ in the file’s name denotes the sequence number of a signature (counting starts from zero). The signatures*.xml file also incorporates certificates, validity confirmation and meta-data about the signer.

When BDOC 2.1 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), 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 and the OCSP responder’s certificate.

BDOC 2.1 container's contents

BDOC signature profiles

The format of the BDOC 2.1 digitally signed file is based on ETSI TS 101 903 standard called XML Advanced Electronic Signatures ("XAdES"). 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.

BDOC signature with time-mark

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:

TBSDocumentDigest ::= SEQUENCE {
algorithm AlgorithmIdentifier,
digest OCTET STRING
}

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:

  1. The signature value existed at a certain point of time (issuance time of the OCSP confirmation) – the verifier can calculate the hash of the signature and check its conformance to the OCSP response’s "nonce" field.
  2. The signer’s certificate was valid (provided that the OCSP response is positive and does indeed confirm the certificate’s validity) at a certain point of time

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

NB! The issuance time (producedAt field’s value) of the OCSP response (the time-mark) is regarded as the time of signature creation.

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.

Security model of time-marking mechanism

BDOC signature with time-stamp

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:

  1. RFC3161 compliant time-stamp is obtained from a time-stamping service. The hash of the created signature (<SignatureValue> element block) is sent to the time-stamping server. The server’s response contains a time-stamp token with the same hash value that can later be used to validate that the time-stamp was indeed issued for the respective signature. The time-stamp token received from the server is added to the signature providing a proof from a trusted source that the signature value existed at a certain point of time.
  2. RFC 6960 compliant OCSP confirmation is obtained from an OCSP service. The OCSP response received from the server is used as a trusted source to confirm that the signer’s certificate was valid at a certain point of time (producedAt field’s value in the OCSP response).
  3. The verifier must check the time-stamp token’s and OCSP confirmation’s time difference. If the difference is acceptable then it can stated that the signer’s certificate was valid at the time of signature creation.

NB! The issuance time (getTime field’s value) of the time-stamp token (received with the response from time-stamping server) is regarded as the time of signature creation.

ASiC-S container format

In addition to the Associated Signature Extended form (ASiC-E) the ETSI standard TS 102 918 defines a Simple form which is used for encapsulating a single datafile and signature or time-stamp token associated with it.

ASiC-S container is a ZIP file consisting of the following objects:

  • an optional file named "mimetype", containing only the following value: application/vnd.etsi.asic-s+zip
  • data object (file) in original format.
  • META-INF subdirectory with one of the following files:
    • signatures.p7s
    • signatures.xml
    • timestamp.tst

The libdigidocpp library supports only containers with time-stamp token (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; it 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.

The library can be used only for reading the content of the container and validating that the time-stamp was indeed issued for the data object included in the container.

Release Notes

Libdigidocpp library [3.17.0](https://github.com/open-eid/libdigidocpp/releases/tag/v3.17.0) release notes
--------------------------------------
- Update libraries and platform support (#549, #554, #558, #553)
- Improve signature and container compatibility (#543, #545, #559, #561, #552)
- Other fixes and optimizations (#542, #550, #557, #544, #551, #555)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.16.0...v3.17.0)
Libdigidocpp library [3.16.0](https://github.com/open-eid/libdigidocpp/releases/tag/v3.16.0) release notes
--------------------------------------
- Update libraries and platform support (#530, #477, #534, #535)
- Improve signature and container compatibility (#528)
- Other fixes and optimizations (#529, #533, #532, #536)
- Removed time-mark signature creation support (#527, #539)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.15.0...v3.16.0)
Libdigidocpp library [3.15.0](https://github.com/open-eid/libdigidocpp/releases/tag/v3.15.0) release notes
--------------------------------------
- Update libraries and platform support (#525, #522, #515, #503, #511, #514, #516, #517, #523, #505)
- Improve code quality and documentation (#526, #521, #524, #520, #501)
- Improve signature and container compatibility (#506, #504, #502, #491)
- Other fixes and optimizations (#435, #481, #508, #433, #519, #497)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.14.11...v3.15.0)
Libdigidocpp library [3.14.12](https://github.com/open-eid/libdigidocpp/releases/tag/v3.14.12) release notes
--------------------------------------
- Fix digidoc-tool file extraction
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.14.11...v3.14.12)
Libdigidocpp library [3.14.11](https://github.com/open-eid/libdigidocpp/releases/tag/v3.14.11) release notes
--------------------------------------
- Update libraries (#472, #495, #490, #500)
- TSL parsing improvementsa (#492, #495, #499)
- Fix memory leaks (#488)
- Prefer PSS padding with RSA key (#437)
- Code fixes and improvements (#478, #487, #513)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.14.10...v3.14.11)
Libdigidocpp library [3.14.10](https://github.com/open-eid/libdigidocpp/releases/tag/v3.14.10) release notes
--------------------------------------
- Trust intermediate certificates in trust store (#476)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.14.9...v3.14.10)
Libdigidocpp library [3.14.9](https://github.com/open-eid/libdigidocpp/releases/tag/v3.14.9) release notes
--------------------------------------
- TSL parsing improvements (#475, #451, #465, #464, #463, #439, #443)
- Allow validate signatures with TimeStampValidationData (#455)
- Build python bindings (#456)
- OpenSSL 3.0 support and minimum supported 1.1.1 (#468, #461, #453)
- Update documentation (#434)
- Fix parameter locking when false is defined (#448)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.14.8...v3.14.9)
Libdigidocpp library [3.14.8](https://github.com/open-eid/libdigidocpp/releases/tag/v3.14.8) release notes
--------------------------------------
- Update TSL signer certificates (#438)
- Optimize signing process (#404, #417, #430)
- Improve SiVa validation (#419, #426, #429)
- Remove SK OCSP proxy URL (#427)
- Improve signature validation (#383, #420, #432, #444)
- Updates for libraries and examples (#423, #424, #381, #425)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.14.7...v3.14.8)
Libdigidocpp library [3.14.7](https://github.com/open-eid/libdigidocpp/releases/tag/v3.14.7) release notes
--------------------------------------
- Remove libdigidoc support (#393)
- Build macOS arm64 (#392)
- Improve compatibility where Xerces-C is configured uint16_t (#391)
- Use same length digest as ECC key (#406)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.14.5...v3.14.7)
Libdigidocpp library [3.14.6](https://github.com/open-eid/libdigidocpp/releases/tag/v3.14.6) release notes
--------------------------------------
- Update TSL signer certificates
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.14.5...v3.14.6)
Libdigidocpp library [3.14.5](https://github.com/open-eid/libdigidocpp/releases/tag/v3.14.5) release notes
--------------------------------------
- Use nlohmann json library (#380)
- Add canonicalization algorithm to time-stamp (#369)
- Add PSS signature support (#366)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.14.4...v3.14.5)
Libdigidocpp library [3.14.4](https://github.com/open-eid/libdigidocpp/releases/tag/v3.14.4) release notes
--------------------------------------
- Use unique_ptr on Container::create/open (#355)
- Deprecate std::istream *is method and add std::unique_ptr<std::istream> alternative
- Fix encoding on macOS when LC_ALL is defined (#346)
- Use 64 bit stat on windows (#349)
- Implement SiVa V3 changes (#354)
- Documentation updates and code fixes
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.14.3...v3.14.4)
Libdigidocpp library [3.14.3](https://github.com/open-eid/libdigidocpp/releases/tag/v3.14.3) release notes
--------------------------------------
- Change SiVa URL (#335)
- Split user-agent and application name handling (#333)
- Update OpenSSL 1.1.1g and Xerces-C 3.2.3 (#347)
- Workaround OpenSSL 1.1.1f issues (#348)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.14.2...v3.14.3)
Libdigidocpp library [3.14.2](https://github.com/open-eid/libdigidocpp/releases/tag/v3.14.2) release notes
--------------------------------------
- Check that OCSP producedAt is later than TimeStamp (#324)
- Update documentation (#326)
- Other code and build cleanups
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.14.1...v3.14.2)
Libdigidocpp library [3.14.1](https://github.com/open-eid/libdigidocpp/releases/tag/v3.14.1) release notes
--------------------------------------
- Fix LGTM and Coverity warnings and errors
- Add TSUrl parameter to digidoc-tool (#293)
- Update OpenSSL to 1.1.1
- Add stricter validation rules (#317, #295)
- SiVa V3 compatibility
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.14.0...v3.14.1)
Libdigidocpp library [3.14.0](https://github.com/open-eid/libdigidocpp/releases/tag/v3.14.0) release notes
--------------------------------------
- Update LOTL URL (#304)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.13.9...v3.14.0)
Libdigidocpp library [3.13.9](https://github.com/open-eid/libdigidocpp/releases/tag/v3.13.9) release notes
--------------------------------------
- Update dependencies (#285, #275, #274, #268, #266, #265, #258)
- Optimize TSL loading and SiVa request (#271, #252, #280)
- Update TSL trust certificates (#287)
- Improve C# and java bindings (#282, #278, #272, #270)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.13.8...v3.13.9)
Libdigidocpp library [3.13.8](https://github.com/open-eid/libdigidocpp/releases/tag/v3.13.8) release notes
--------------------------------------
- Use ETag instead Last-Modified to verify cached file (#238)
- Fix signature verify with OpenSSL 1.1 (#240)
- Check OCSP TM OID (#247)
- Handle TSA error code 429 and cleanup some code (#250)
- Upload artifacts to AWS (#253)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.13.7...v3.13.8)
Libdigidocpp library [3.13.7](https://github.com/open-eid/libdigidocpp/releases/tag/v3.13.7) release notes
--------------------------------------
- Remove compiler warnings
- Change SiVa service URL to https://siva.eesti.ee/V2/validate
- Update Xml-Security-C 2.0.1 (#224), OpenSSL 1.0.2p (#222)
- Fix crashes #223, #228, #221 and memory leaks #224
- Code cleanups and warning fixes
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.13.6...v3.13.7)
Libdigidocpp library [3.13.6](https://github.com/open-eid/libdigidocpp/releases/tag/v3.13.6) release notes
--------------------------------------
- Add new OCSP access certificate and use when old is expired (#205)
- Build java bindings on desktop platforms (#204)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.13.5...v3.13.6)
Libdigidocpp library [3.13.5](https://github.com/open-eid/libdigidocpp/releases/tag/v3.13.5) release notes
--------------------------------------
- Add TSL cert tl-mp5 and generate headers dynamically (#174)
- Use case sensitive zip file compare (#175)
- Android build improvements (#179, #180)
- SiVa service validation improvements (#185, #184)
- Update Xerces-C to 3.2.1 (#187)
- Optimize TSL loading (#192)
- PDF Experimental backend (#57)
- Build fixes and improvements
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.13.3...v3.13.5)
Libdigidocpp library [3.13.4](https://github.com/open-eid/libdigidocpp/releases/tag/v3.13.4) release notes
--------------------------------------
- Add TSL cert tl-mp5 and generate headers dynamically (#174)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.13.3...v3.13.4)
Libdigidocpp library [3.13.3](https://github.com/open-eid/libdigidocpp/releases/tag/v3.13.3) release notes
--------------------------------------
- SiVa V2 support (#166)
- Android build fixes (#167, #164)
- Fix loading unsigned TM signatures (#161)
- Don't terminate TSL parsing when TakenOvertByType extension is found (#160)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.13.2...v3.13.3)
Libdigidocpp library [3.13.2](https://github.com/open-eid/libdigidocpp/releases/tag/v3.13.2) release notes
--------------------------------------
- Implement ECDSA token support (#152)
- Fix issuer name with UTF-8 characters (#146)
- Check mimetype format (#150)
- Update xerces-c to 3.2.0 (#149)
- Take OCSP URL from AIA extension (#138)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.13.1...v3.13.2)
Libdigidocpp library [3.13.1](https://github.com/open-eid/libdigidocpp/releases/tag/v3.13.1) release notes
--------------------------------------
- Restore compatibility with jdigidoc 3.11
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.13.0...v3.13.1)
Libdigidocpp library [3.13.0](https://github.com/open-eid/libdigidocpp/releases/tag/v3.13.0) release notes
--------------------------------------
- Relax validation of BDOC to accept sub-elements of SignatureProductionPlace in any order
- Speed up signing large files by handling them as file stream instead of in-memory
- Improved compatability with Latvian/Lithuanian ASiC-E documents
- XAdES EN support
- Better handling of malicious zip files
- Added ASiC-S validation support
- Improve TSL parsing
- Improve compatibilty with EIDAS
- Disable External Entities parsing
- Use SiVa service for parsing PDF and DDoc (on platforms where libdigidoc backend is missing)
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.12.2...v3.13.0)
Libdigidocpp library [3.12.3](https://github.com/open-eid/libdigidocpp/releases/tag/v3.12.3) release notes
--------------------------------------------
- Verify signing certificate QCSD OID-s
[Full Changelog](https://github.com/open-eid/libdigidocpp/compare/v3.12.2...v3.12.3)
Libdigidocpp library 3.12.2 release notes
--------------------------------------
Changes compared to ver 3.12.1
- Fix issues found by coverity
- digidoc-tool improvements
- API option to verify PDF validator service SSL certificate
- Added new TSL signing certificates
Libdigidocpp library 3.12.1 release notes
--------------------------------------
Changes compared to ver 3.12.0
- Added Container::prepareWebSignature for C# bindings
- Documentation updates
- Fix crash parsing References without ID attribute
- Handle TSL v5 service status parameters
Libdigidocpp library 3.12.0 release notes
--------------------------------------
Changes compared to ver 3.11.1
- Fix download TSL-s over proxy in case of HTTPS connections
- Behaviour change, proxy tunnel SSL option is now default on
- Export PKCS12Signer class
- Update C# bindings
- Find OCSP certificate from TSL list
- On loading TSL lists, verify HTTP result is 200
- Major API changes, SO version increased to 1. Applications need to adopt new changes and recompile applications.
- Added support for signing in web browser
- Example projects for iOS and Android
- Disable SHA1 support on signature creation
- OCSP nonce compatibility with other digest info headers
List API changes https://github.com/open-eid/libdigidocpp/wiki/API-changes-(v3.12)
List of known issues: https://github.com/open-eid/libdigidocpp/wiki/Known-issues
Libdigidocpp library 3.11.1 release notes
--------------------------------------
Changes compared to ver 3.11.0
- Verify HTTP result before processing TSL lists
- Include cdigidoc.exe
List of known issues: https://github.com/open-eid/libdigidocpp/wiki/Known-issues
Libdigidocpp library 3.11.0 release notes
--------------------------------------
Changes compared to ver 3.10.3
- Improved ECDSA signature size calculation
- Optimized HTTP download speed (e.g. when updating TSL lists) by compressing the traffic (using gzip Content-Encoding)
- Added support for validating BDOC 2.1 time-stamp signatures with archive time-stamps
- Added option to specify different digest algorithm for the signature value than the default algorithm used in case of other digest values in the signature.
- Added API methods Signer::setMethod(), Signer::method(), XmlConfV4::signatureDigestUri()
- Added configuration parameters signer.digestUri and signer.signatureDigestUri
- Added parameter -sigsha(1,224,256,384,512) to digidoc-tool utility program
- Improved OCSPserver access certificate usage, relative pkcs12.cert configuration parameter value is now resolved to the library's installation path, instead of current working directory
- Added option to download TSL-s over proxy in case of HTTPS connections
- Added API methods XmlConfV4::proxyForceSSL(), XmlConfV4::proxyTunnelSSL()
- Added configuration file parameters forceSSL and tunnelSSL
- Fixed OCSP certificate verification, the verification is now done based on the OCSP poducedAt field's time.
Libdigidocpp library 3.10.3 release notes
--------------------------------------
Changes compared to ver 3.10.0
- Updated experimental .NET C# wrapper swig configuration file to recent API
- Included C# wrapper files in Windows installer package
- Filter out CA certificates in PKCS11Signer implementation to support Finland ID-card signing in digidoc-tool
- Improved signature validation, it is now checked that at least one data file is signed
- Disabled OCSP time slot check when requesting OCSP confirmation, the local computer time difference compared to OCSP server time is not checked.
Libdigidocpp library 3.10.0 release notes
--------------------------------------
Changes compared to ver 3.9
- Changed the default BDOC signature profile to BDOC-TS (ASiC-E LT signature with time-stamp) for new signatures. To create a BDOC-TM (LT_TM, i.e. time-mark) signature, specify the "time-mark" profile value in Container::sign(Signer *signer, const string &profile) method call.
- Fixed time zone usage when validating signer certificate validity period's starting time. Previously, "Not yet valid" error message was displayed even if the certificate was actually already valid.
- Improved BDOC signatures*.xml file's XML structure validation. Transforms XML element is now allowed to enhance interoperability.
- Improved TSL functionality
- In case of BDOC format, checking the trustworthiness of trust services (CA, OCSP, time-stamping services) is now possible only by using TSL lists. Previously used certificate store functionality is no longer supported.
- Removed country-specific filtering of the national TSLs that are referenced in the European Commission's central TSL list.
- Added possibility to use multiple parallel European Commission's TSL signing certificates to enable transition to a new certificate, if needed.
- Added checking of the TSL's officially published SHA-256 digest value online to determine if a newer version of the TSL is available.
- Added configuration parameter "tsl.onlineDigest" that enables to disable the TSL online SHA-256 digest check.
- Removed configuration file parameters "tsl.url" and "tsl.cert". The respective values can be set directly from the library's API.
- Added TSL downloading timeout, the value is set to 10 seconds for each TSL. Added configuration parameter "tsl.timeOut" that can be used to configure the timeout value.
- Improved TSL loading when proxy is used, proxy settings are ignored in case of HTTPS connections.
- Changed the XmlConf class to deprecated, use XmlConfV2 instead.
- Changed the OCSP responder URL for EID-SK 2011 certificates, http://ocsp.sk.ee is now used.
- Fixed error message text that appears when data file's mime-type in BDOC manifest.xml does not conform with mime-type value in signatures*.xml file. Previously, the displayed mime-type values were interchanged between the signatures*.xml and manifest.xml files.
- The library's release notes is now also copied to the library's documentation: http://open-eid.github.io/libdigidocpp/manual.html#releasenotes
- Development of the software can now be monitored in GitHub environment: https://github.com/open-eid/libdigidocpp
Libdigidocpp library 3.9 release notes
--------------------------------------
Changes compared to ver 3.8
- Added support for creating and validating BDOC signatures with time-stamps (BDOC-TS profile).
- By default, there is no time-stamping service support configured.
- Added new parameter "ts.url" to digidocpp.conf configuration file that specifies the time-stamping service used during signature creation.
- Added support for "time-stamp" profile value for digidoc::Container::sign(Signer *signer, const std::string &profile) method when creating BDOC-TS signature via API.
- Added time-stamp (TS) profile support for digidoc-tool utility program's "sign" and "create" commands. TS profile can be set with "--profile=TS" parameter.
- The signature creation time of BDOC-TS signature is the time-stamp's creation time (in case of a signature with time-stamp, the OCSP validity confirmation's creation time is the signing time).
- Added validation check for difference between OCSP validity confirmation's production time and time-stamp's production time. An exception is thrown if the OCSP confirmation's time is earlier than time-stamp's time. If the OCSP confirmation's time is later than time-stamp's time by more than 15 minutes then a warning is returned. If the difference is more than 24 hours then exception is thrown.
- Added support for using TSL (Trusted Service List) list as trust anchor when checking certificates' trustworthiness during signature creation and validation.
- By default, European Commission TSL list is used (https://ec.europa.eu/information_society/policy/esignature/trusted-list/tl-mp.xml) as source for finding country-specific TSL lists. Finnish, Estonian, Latvian and Lithuanian country-specific TSL lists are used by default.
- Added TSL usage configuration possibilities to digidocpp.conf file. Use "tsl.autoupdate", "tsl.cache", "tsl.cert" and "tsl.url" configuration parameters to change the default TSL settings.
- Added command "tsl" to digidoc-tool utility program, the command prints out TSL diagnostics and validates the list.
- Added possibility to disable all TSL functionality in the library by setting CMake USE_TSL parameter to "false" when building the library.
- Added class XmlConfV2 that should be used instead of XmlConf class if it is needed to configure time-stamp and TSL related configuration properties.
- Added Xalan library for processing TSL files.
- Added support for adding OCSP confirmation to signature if the signer's certificate is issued by "VRK CA for Qualified Certificates - G2" or "VRK Gov. CA for Citizen Qualified Certificates - G2".
- Improved BDOC document's validation, it is now checked that the data file mime-type value in manifest.xml file and the respective value in signatures*.xml file in <DataObjectFormat><MimeType> element are the same.
- Added "--mime=" parameter to digidoc-tool utility program's "create" command. The parameter can be used along with "--file=" parameter to set the mime-type value of a data file. If not set then the default value "application/octet-stream" is used.
- Improved BDOC document's validation, added check for weak hash algorithm (SHA-1) usage in case of ECDSA signatures.
- Improved BDOC signatures*.xml file's XML structure validation. It is now additionally checked that unsupported elements CounterSignature, CompleteCertificateRefs, CompleteRevocationRefs, AttributeCertificateRefs, AttributeRevocationRefs, SigAndRefsTimeStamp, RefsOnlyTimeStamp, AttrAuthoritiesCertValues, AttributeRevocationValues, CommitmentTypeIndicationType, AllDataObjectsTimeStamp, IndividualDataObjectsTimeStampType would not exist in the file.
- Improved processing of special characters in URI attribute values according to RFC3986. Special characters in URI are percent-encoded, except of unreserved characters and delimiters. Both percent-encoded and non-percent-encoded characters are supported during signature's validation. Note that as a result, the files that contain special characters in URI values and have been created with v3.9 might not be compatible with v3.8 of the library.
- Fixed problem that caused erroneous signatures if the data file's name contained colon character.
- Fixed digidoc-tool utility program "extract" command's "--extractAll" parameter functionality. Now, if the parameter is present but there is no extraction directory specified then the files are extracted to the working directory.
- Fixed digidoc-tool utility program's error that caused the program to exit unexpectedly when trying to create or sign a DDOC file.
- Changed Libdigidoc wrapper to fix error which occurred when parsing DDOC document's data file name that contains some specific special characters. Previously, the special characters were erroneously displayed in escaped form.
- Fixed problem in Libdigidoc wrapper when calculating data file's size in the course of parsing a DDOC file. Previously, a wrong data file size was returned occasionally.
- Added XAdESv141.xsd schema support for implementing BDOC archive time-stamp profile in the future.
- Started using libc++ library instead of libstdc++ on OSX platform. The libc++ provides full c++11 support.
- All Libdigidocpp documentation is now available in HTML format (see /documentation/html/index.html in the base directory). Updated the existing HTML-based API documentation, transformed the contents of "Libdigidocpp Programmer's Guide" PDF/Word document to HTML format. Removed the previously used PDF/Word documents.
- Used coverity.com static analysis tool to find source code defects and vulnerabilities.
Known issues:
- Version 3.8 of the library cannot open BDOC documents that are created with version 3.9 or higher and contain special characters in the signed data file's name due to changes in special character percent-encoding method.
Libdigidocpp library 3.8 release notes
--------------------------------------
3.8 is first public release of libdigidocpp as library. API is changed and not compatible compared to 3.7.1 version when libdigidocpp was not yet public library but internal component used by Digidoc3 client.
Known issues:
- If a data file with a colon character in its name is added to a BDOC container then the created signature will be erroneous. Thus, colon characters must not be used in data file names.

Overview

References and additional resources

BDOC2.1:2013

BDOC – Format for Digital Signatures. Version 2.1:2013

https://www.skidsolutions.eu/repository/bdoc-spec21.pdf
Other releases:
https://www.skidsolutions.eu/repository/bdoc-spec20.pdf
https://www.skidsolutions.eu/repository/bdoc-spec212.pdf
https://www.id.ee/wp-content/uploads/2020/08/bdoc-spec21-est.pdf
https://www.id.ee/wp-content/uploads/2020/01/bdoc-spec212-est.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"

http://www.ietf.org/rfc/rfc3275.txt

XML-DSIG 1.1

XML Signature Syntax and Processing. Version 1.1

http://www.w3.org/TR/xmldsig-core1/

XAdES

ETSI TS 101 903 V1.4.2 (2010-12) – XML Advanced Electronic Signatures

http://www.etsi.org/deliver/etsi_ts/101900_101999/101903/01.04.02_60/ts_101903v010402p.pdf
Other versions:
http://www.etsi.org/deliver/etsi_ts/101900_101999/101903/01.04.01_60/ts_101903v010401p.pdf
http://www.etsi.org/deliver/etsi_ts/101900_101999/101903/01.03.02_60/ts_101903v010302p.pdf

XAdES Baseline Profile

ETSI TS 103 171 V2.1.1 (2012-03) - XAdES Baseline Profile

http://www.etsi.org/deliver/etsi_ts/103100_103199/103171/02.01.01_60/ts_103171v020101p.pdf

XAdES EN

ETSI EN 319 132-1 V1.1.1 (2016-04) - XAdES digital signatures

http://www.etsi.org/deliver/etsi_en/319100_319199/31913201/01.01.01_60/en_31913201v010101p.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

PKWARE ZIP

ZIP File Format Specification

http://www.pkware.com/documents/casestudies/APPNOTE.TXT

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
Other versions:
http://docs.oasis-open.org/office/v1.0/OpenDocument-v1.0-os.pdf

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
Other versions:
http://www.etsi.org/deliver/etsi_ts/102900_102999/102918/01.03.01_60/ts_102918v010301p.pdf
http://www.etsi.org/deliver/etsi_ts/102900_102999/102918/01.01.01_60/ts_102918v010101p.pdf
http://www.etsi.org/deliver/etsi_ts/102900_102999/102918/01.02.01_60/ts_102918v010201p.pdf

ASiC Baseline Profile

ETSI TS 103 174 V2.1.1 (2012-03)

http://www.etsi.org/deliver/etsi_ts/103100_103199/103174/02.02.01_60/ts_103174v020201p.pdf
Other versions:
http://www.etsi.org/deliver/etsi_ts/103100_103199/103174/02.01.01_60/ts_103174v020101p.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

RFC6960

X.509 Internet Public Key Infrastructure Online Certificate Status Protocol – OCSP

http://tools.ietf.org/html/rfc6960

RFC3161

Internet X.509 Public Key Infrastructure Time-Stamp protocol

http://tools.ietf.org/html/rfc3161

RFC5280

Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile

http://tools.ietf.org/html/rfc5280

Trusted Lists

ETSI TS 119 612 V1.1.1 (2013-06)

http://www.etsi.org/deliver/etsi_ts/119600_119699/119612/02.02.01_60/ts_119612v020201p.pdf
Other versions:
http://www.etsi.org/deliver/etsi_ts/119600_119699/119612/01.01.01_60/ts_119612v010101p.pdf
http://www.etsi.org/deliver/etsi_ts/102200_102299/102231/03.01.02_60/ts_102231v030102p.pdf

SiVa

Digital signature validation web service that provides SOAP and JSON API to validate files

http://open-eid.github.io/SiVa/

DSA

Estonian Digital Signature Act

http://www.legaltext.ee/et/andmebaas/tekst.asp?loc=text&dok=X30081K6&keel=en&pg=1&ptyyp=RT&tyyp=X&query=digitaalallkirja

Release notesLibdigidocpp 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

DigiDoc librarieshttps://www.id.ee/en/rubriik/digidoc-libraries/
ID-software GitHub projecthttps://github.com/open-eid
Libdigidocpp GitHub projecthttps://github.com/open-eid/libdigidocpp

Terms and acronyms

ASiCAssociated Signature Containers
ASiC-EExtended Associated Signature Containers. A type of ASiC container.
ASiC-SAssociated 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.
CRLCertificate 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.
ECDSAElliptic Curve Digital Signature Algorithm. Digital Signature Algorithm (DSA) which uses elliptic curve cryptography. Used as an alternative to RSA algorithm.
OCSPOnline Certificate Status Protocol, an Internet protocol used for obtaining the revocation status of an X.509 digital certificate
OCSP ResponderOCSP 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.
SKSK ID Solutions AS. Certificate Authority in Estonia
time-markMechanism 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-stampMechanism 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 (genTime value in the time-stamp) of the time-stamp token. The respective signature profile is TS profile (supported only in case of BDOC 2.1 document format).
archive time-stampMechanism 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 (supported only in case of BDOC 2.1 document format).
TSATime-Stamping Authority. Time-stamping service provider.
TSLTrust 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.509an 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
XAdESXML 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-DSIGa 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

Supported functional properties

Libdigidocpp is a library of C++ classes offering the functionality of handling digitally signed files in supported DigiDoc formats. The following functions are implemented:

  • creating containers in supported DigiDoc formats and adding data files;
  • creating digital signatures using smart cards or other supported cryptographic tokens;
  • adding time marks and validity confirmations to digital signatures using OCSP and time-stamping protocols;
  • validating the digital signatures;
  • using trust service status lists (TSL) as trust anchors for certificate validation;
  • extracting data files from a container;
  • removing signatures and data files from a container.

The following table gives overview of functional features that are supported with Libdigidocpp.

Feature Supported values
DigiDoc document format
  • BDOC 2.1 - the main document format to be used, described in BDOC2.1:2013.
Note
BDOC 1.0 file format is not supported (more info can be found from https://www.id.ee/en/article/digidoc-container-format-life-cycle-2/).
Signature profile Signature profiles are based on the profiles defined by XAdES (XAdES).
  • time-stamp (TS) - signature profile in case of which the certificate validity information is added to the signature with an OCSP confirmation; the signing time information is added with a time-stamp token (see also RFC6960) retrieved from a time-stamping service. In this case, signature creation time is regarded as the issuance time of the time-stamp token (genTime value in the time-stamp). The profile is supported only in case of BDOC 2.1 document format, the "SignatureTimeStamp" element is added to the signature (see also BDOC2.1:2013). Supported since v3.9 of the library.
  • time-mark (TM) - certificate validity and signing time information is added to the signature with a time-mark - a special OCSP confirmation in case of which the 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 regarded as the issuance time of the OCSP confirmation (producedAt value in the confirmation), additional time-stamp token is not required.
  • archive time-stamp (LTA) - the signature and all the accompanying validation data is time-stamped in order to provide long term validity. The profile is supported only in case of BDOC 2.1 document format, the "ArchiveTimeStamp" element is added to the time-stamp or time-mark signature (see also BDOC2.1:2013). In Libdigidocpp, validation of BDOC 2.1 time-stamp signatures with archive time-stamps is supported since v3.11 of the library.
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. The TSL functionality is supported since v3.9 of the library.
Signature creation module
  • PKCS#11 – in Linux and macOS environments, the default module for singing with smart card (e.g. Estonian ID card or any other smartcard provided that you have the external native PKCS#11 driver for it).
  • Windows CryptoAPI – the default module for signing with smart card in Windows environment. By default, a dialog window is opened for the user to choose the signing certificate and enter PIN code.
Cryptographic token type
  • Smart card, e.g. Estonian ID card. Supported signature creation modules are PKCS#11 and Windows CryptoAPI.
    Note
    Usage of USB cryptostick (Aladdin eToken with Digital Stamp certificate (https://www.skidsolutions.eu/en/services/Digital-stamp)) has been tested indirectly with Libdigidocpp - testing has been carried out via DigiDoc desktop application which uses Libdigidocpp as a base layer.
Public-key algorithm
  • RSA
  • ECDSA

Component model

The figure below describes the architecture of software and hardware components that are used when creating signatures with Libdigidocpp library.

Components used in Libdigidocpp implementation when signing with smart card
ComponentDescription
PKCS#11Widely adopted platform-independent API to cryptographic tokens (HSMs, smart cards and USB tokens), a standard management module of the cryptographic token and its certificates
CryptoAPIMicrosoft Cryptography API. Programming API for implementing cryptographic functions in Windows environment.
PC/SCStandard communication interface between the computer and the smart card, a cross-platform API for accessing smart card readers
IFDHandlerInterface Device Handler for CCID readers
CCIDUSB driver for Chip/Smart Card Interface Devices
ReaderDevice used for communication with a smart card

Dependencies

Software libraries

Libdigidocpp library depends on the software libraries listed below.

Base ComponentRequired/optionalDescription
OpenSSLrequiredUsed for validating certificates and digest values.
XercesCrequiredUsed for validating the documents according to XML Schema, reading and writing XML.
XalanCrequiredUsed for handling XPath references in XML
XmlSecurityCrequiredUsed for handling signature related components.
XSDrequiredUsed for dynamically generating C++ source code according to XML Schemas, only used during building process of the library. Required when building the library from source code.
ZLIBrequiredUsed when compressing and extracting ASiC files in ZIP format.
MiniziprequiredUsed when creating and opening ZIP container for BDOC file. If the component is not found from system then bundled version with source code is used. Forms a part of ZLIB component.
PKCS11optionalUsed for searching for default PKCS#11 driver in the system so that its path could be registered in configuration entries.
DoxygenoptionalUsed for generating API documentation from source code.
SWIGoptionalUsed for creating C# and Java bindings.

XML Schemas

Several XML schemas are used when creating digitally signed documents in BDOC 2.1 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.

Note
Some modifications have been made to some of the schemas. Differences in comparison with the original schemas are listed in section XML schema modifications of the current document.
Schema fileDescription
OpenDocument_manifest.xsdOASIS OpenDocument v1.0 (OpenDocument) Defines the structure of META-INF/manifest.xml file in BDOC container. https://www.oasis-open.org/committees/download.php/12570/OpenDocument-manifest-schema-v1.0-os.rng
OpenDocument_dsig.xsdOASIS OpenDocument v1.0 (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.xsdAssociated 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.xsdXML 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.xsdXML 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
XAdES01903v132-201601-relaxed.xsdRelaxed version of XML Advanced Electronic Signatures (XAdES EN) Allows to list child elements of the SignatureProductionPlace element in any sequence. Schema is used when validating the BDOC documents in order to accept documents produced by DigiDoc4j library version 1.0.3 and earlier.
XAdES01903v141-201601.xsdDefines XML syntax for additional elements of XAdES signatures that were added with version 1.4.1 of the (XAdES EN) standard. Needed for implementing archive time-stamp support in the future. 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.xsdConfiguration 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).

Dependencies between XML Schemas

XML schema modifications

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.

<xsd:import namespace="http://www.w3.org/2000/09/xmldsig#"
schemaLocation="xmldsig-core-schema.xsd"/> <!-- originally "http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd" -->

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

ÊA7U
ÊA7U␎V
!␆ØU␎V
ÊA
ÊA7U␎V
7X³`␅
à¬áì©
ÊA7U␎V
ÊA7U␎V
ÊA7U
-->

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.

<complexType name="X509IssuerSerialType">
<sequence>
<element name="X509IssuerName" type="string"/>
<element name="X509SerialNumber" type="string"/> <!-- originally type="integer" -->
</sequence>
</complexType>

Schema XAdES01903v132-201601.xsd

1) The schema’s location has been modified so that the file is looked up from the local file system.

<xsd:import namespace="http://www.w3.org/2000/09/xmldsig#"
schemaLocation="xmldsig-core-schema.xsd"/> <!-- originally "http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd" -->

2) The "type" attribute has been added, otherwise a warning message would be produced.

<xsd:complexType name="SignaturePolicyIdentifierType">
<xsd:choice>
<xsd:element name="SignaturePolicyId" type="SignaturePolicyIdType"/>
<xsd:element name="SignaturePolicyImplied" type="AnyType"/> <!-- added type="AnyType" -->
</xsd:choice>
</xsd:complexType>

3) The "type" attribute has been added, otherwise a warning message would be produced.

<xsd:complexType name="CommitmentTypeIndicationType">
<xsd:sequence>
<xsd:element name="CommitmentTypeId" type="ObjectIdentifierType"/>
<xsd:choice>
<xsd:element name="ObjectReference" type="xsd:anyURI"
maxOccurs="unbounded"/>
<xsd:element name="AllSignedDataObjects" type="AnyType"/> <!-- added type="AnyType" -->
</xsd:choice>
<xsd:element name="CommitmentTypeQualifiers"
type="CommitmentTypeQualifiersListType" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>

Schema XAdES01903v132-201601-relaxed.xsd

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

<xsd:complexType name="SignatureProductionPlaceType">
<xsd:all>
<xsd:element name="City" type="xsd:string" minOccurs="0"/>
<xsd:element name="StateOrProvince" type="xsd:string" minOccurs="0"/>
<xsd:element name="PostalCode" type="xsd:string" minOccurs="0"/>
<xsd:element name="CountryName" type="xsd:string" minOccurs="0"/>
</xsd:all>
</xsd:complexType>

Schema XAdES01903v141-201601.xsd

1) The schema's location has been modified so that the file is looked up from the local file system.

<xsd:import namespace="http://uri.etsi.org/01903/v1.3.2#" schemaLocation="XAdES01903v132-201601.xsd"/> <!-- originally "http://uri.etsi.org/01903/v1.3.2/XAdES01903v132-201601.xsd" -->

Schema ts_119612v020201_201601xsd.xsd

1) The schemas' locations have been modified so that the file is looked up from the local file system.

<xsd:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="xml.xsd"/> <!-- originally "http://www.w3.org/2001/xml.xsd" -->
<xsd:import namespace="http://www.w3.org/2000/09/xmldsig#" schemaLocation="xmldsig-core-schema.xsd"/> <!-- originally http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd" -->

Configuring Libdigidocpp

Loading configuration settings

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:

  • in case of Windows environment:
    • the global configuration file is looked up from the directory where digidocpp.dll library file is located. If the directory doesn't contain /schema subdirectory then the configuration file is looked up from the current working directory.
    • user configuration file is looked up from the system directory containing application data for the current user: %APPDATA%\digidocpp\digidocpp.conf
  • in case of macOS:
    • the global configuration file is looked up from a location in the file system: digidocpp.framework/Resources/digidocpp.conf
    • user configuration file is looked up from $HOME/.digidocpp/digidocpp.conf
  • in case of Linux environment:
    • the global configuration file is looked up from a location in the file system: /etc/digidocpp/digidocpp.conf
    • user configuration file is looked up from $HOME/.digidocpp/digidocpp.conf

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:

// Initialize global configuration settings from a non-default location
digidoc::Conf::init(new digidoc::XmlConf("<file-path-and-name>"));
// then initialize the library
static void init(Conf *conf)
Definition: Conf.cpp:63
XML Configuration class.
Definition: XmlConf.h:30
DIGIDOCPP_EXPORT void initialize(const std::string &appInfo="libdigidocpp", initCallBack callBack=nullptr)
Definition: Container.cpp:111

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 parameters

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

Logging settings

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.

Time-stamping service settings

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 (http://dd-at.ria.ee/tsa)
Note
For testing purposes, the SK's test time-stamping service can be used. The service is available at http://demo.sk.ee/tsa/ additional information can be found at https://www.id.ee/en/rubriik/timestamping-service/.

Signature Verify Service settings

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)

PKCS#11 settings

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)

Trust anchor/TSL settings

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.

Note
- The TSL URL and TSL signing certificate values are not configurable via the digidocpp.conf configuration file. The default values are fixed in source code and can be accessed via methods digidoc::Conf::TSLCerts() and digidoc::Conf::TSLUrl(). The library's user has to create a subclass and override the methods in order to define other values. See also Initialization.
- When using digidoc-tool utility program then it is possible to specify necessary TSL parameters on the command line. See also Libdigidocpp utility program.
- For information about using test TSL lists with Libdigidocpp library, please refer to https://github.com/open-eid/libdigidocpp/wiki/Using-test-TSL-lists
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:
  • in Windows environment: %APPDATA%\digidocpp\tsl,
  • in Linux ja OSX environments: $HOME/.digidocpp/tsl
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.

  • HTTP HEAD request is made to TSL's URL to get remote ETag and if the value doesn't correspond with the existing local TSL's ETag value then a newer version of the TSL list is downloaded. Otherwise, the existing TSL is used.
  • SHA-256 digest that is (optionally) published online by the TSL's owner/manager. The URL of the digest matches the TSL's URL, but extension .sha2 is used instead of .xml. If the digest can be read and the value doesn't correspond with the existing local TSL's SHA-256 digest then a newer version of the TSL list is downloaded. Otherwise, the existing TSL is used.
tsl.timeOut TSL downloading timeout for each TSL list. The default value is 10 seconds.

HTTP proxy settings

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.

Digest type settings

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

OCSP responder settings

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.

Sample configuration file

1 <?xml version="1.0" encoding="UTF-8"?>
2 <configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="schema/conf.xsd">
3  <!--Logging settings-->
4  <!--<param name="log.level" lock="false">2</param>-->
5  <!--<param name="log.file" lock="false">/tmp/digidocpp.log</param>-->
6  <!--<param name="log.file" lock="false">C:\Users\All Users\Documents\digidocpp.log</param>-->
7 
8  <!--Digest algorithm settings-->
9  <!--<param name="signer.digestUri" lock="false">http://www.w3.org/2001/04/xmlenc#sha256</param>-->
10  <!--<param name="signer.signatureDigestUri" lock="false">http://www.w3.org/2001/04/xmlenc#sha256</param>-->
11 
12  <!--PKCS#11 driver’s location, if not using default driver-->
13  <!--<param name="pkcs11.driver.path" lock="false">opensc-pkcs11.so</param>-->
14 
15  <!--HTTP proxy settings, if needed-->
16  <!--<param name="proxy.forceSSL" lock="false">false</param>-->
17  <!--<param name="proxy.tunnelSSL" lock="false">true</param>-->
18  <!--<param name="proxy.host" lock="false"></param>-->
19  <!--<param name="proxy.port" lock="false"></param>-->
20  <!--<param name="proxy.user" lock="false"></param>-->
21  <!--<param name="proxy.pass" lock="false"></param>-->
22 
23  <!--Time-stamping service settings-->
24  <!--<param name="ts.url" lock="false">http://dd-at.ria.ee/tsa</param>-->
25 
26  <!--TSL settings-->
27  <!--<param name="tsl.autoupdate" lock="false">true</param>-->
28  <!--<param name="tsl.cache" lock="false"></param>-->
29  <!--<param name="tsl.onlineDigest" lock="false">true</param>-->
30  <!--<param name="tsl.timeOut" lock="false">10</param>-->
31 
32  <!--Verify service settings-->
33  <!--<param name="verify.serivceUri" lock="false">https://siva.eesti.ee/V3/validate</param>-->
34 
35  <!--OCSP BDoc-TM validation settings-->
36  <!--<param name="ocsp.tm.profile" lock="false">1.3.6.1.4.1.10015.4.1.2</param>-->
37 
38  <!--OCSP responder URL-->
39  <!--<ocsp issuer="ISSUER NAME">http://ocsp.issuer.com</ocsp>-->
40 </configuration>

Using Libdigidocpp API

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.

Initialization

Libdigidocpp's initialization method conducts the following operations:

  1. initializes dependent libraries (see also Software libraries)
  2. loads configuration settings from default configuration files
  3. initializes trust anchors: initializes TSL lists. See TSL initialization process for more information about the TSL initialization process.

If you would like to use non-default configuration settings then call out the configuration file's initialization before initializing the library, for example:

// Optionally initialize global configuration file to use non-default settings
digidoc::Conf::init(new digidoc::XmlConf("<file-path-and-name>"));
// Initialize the library

The digidoc::XmlConf class must be used in order to access all the configuration methods that are available.

Note
If you would like to use different configuration values that are fixed as constants in the digidoc::Conf configuration class then it is possible to extend the class and override the values that need to be reset.

Creating and signing a DigiDoc document (local signing)

Creating a DigiDoc container

Create a new container object and specify the DigiDoc document's type, for example:

auto doc = digidoc::Container::createPtr("<output-file's-path>"); // create new container
static std::unique_ptr< Container > createPtr(const std::string &path)
Definition: Container.cpp:290

Container class is used to incorporate the data of a DigiDoc document.

Adding data files

Data files can be added to a DigiDoc container in two alternative ways:

  1. adding the data from an input stream (i.e. the data file contents can be read from internal memory buffer):
    std::unique_ptr<std::istream> is = ...;
    void digidoc::Container::addDataFile(std::move(is), // input stream
    const std::string &fileName, // file name that is written to the container
    const std::string &mediaType); // mime type of the data file
    virtual void addDataFile(const std::string &path, const std::string &mediaType)=0
  2. adding the data by reading the it from file system
    void digidoc::Container::addDataFile(const std::string &path, //data file's name and path in file system
    const std::string &mediaType); // mime type of the data file

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.

Warning
- In case of BDOC 2.1 documents, it is important to pay attention that the data file's mime type value in manifest.xml file and in signatures*.xml file's <DataObjectFormat><MimeType> element are the same, otherwise the signature is invalid! In case of the ordinary signature creation process, the library sets the correct value automatically. However, if you create a BDOC 2.1 container with Libdigidocpp library and want to add signatures*.xml file that you have received from another source then make sure that the data files' mime-type values in manifest-xml file and in signatures*.xml file are the same.
- Data file’s mime-type value must be formatted as specified in RFC2045, section 5.1 (https://tools.ietf.org/html/rfc2045#section-5.1), i.e. the "type" and "subtype" values must be separated with a forward slash character.
- It is recommended not to use special characters in the data file’s name, i.e. it is suggested to only use the characters that are categorized as "unreserved" according to RFC3986 (http://tools.ietf.org/html/rfc3986).
Note
By default, it is recommended to use data file mime-type value "application/octet-stream" for all file types.

Adding signatures

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.

Note
In case of BDOC 2.1 documents, Libdigidocpp library uses TSL lists (Trust Service Status list) to obtain information about trusted certificates during signature creation process. See also TSL overview, TSL standard and Configuring TSL settings.

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.

digidoc::PKCS11Signer *signer = new digidoc::PKCS11Signer("<PKCS11-driver-path>");
// optionally specify PKCS#11 driver's location. If left unspecified then location is
// looked up from configuration file's parameter "pkcs11.driver.path".
std::string pin = "<pin-code>"; //PIN2 in case of Estonian ID cards
signer->setPin(pin);
Implements Signer interface for ID-Cards, which support PKCS#11 protocol.
Definition: PKCS11Signer.h:27
void setPin(const std::string &pin)
Definition: PKCS11Signer.cpp:306

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.

Optionally specify the signature profile

The supported signature profiles are (see also Supported functional properties, under "Signature profiles"):

  • "time-stamp" (TS) - signature profile in case of which the certificate validity information is added to the signature with an OCSP confirmation (retrieved from OCSP server); the signing time information is added with a time-stamp token (retrieved from a time-stamping service). Signature creation time is the issuance time of the time-stamp token (value of the getTime field in the token). The profile is supported only in case of BDOC 2.1 document format, since v3.9 of the library.
Warning
When adding signature to an existing BDOC 2.1 container then the profile of the existing signature should be used for all of the new signatures in the same container. Signature's profile can be determined with method digidoc::Signature.profile().

If the signature profile value is not specified then then a "time-stamp" profile is used by default.

Set the profile value as follows:

std::string profile = "time-stamp"; // or "time-stamp-archive"
signer->setProfile(profile);
void setProfile(const std::string &profile)
Definition: Signer.cpp:164

Optionally specify additional signer's data

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.

std::string city, state, postalCode, country;
std::vector<std::string> roles;
signer->setSignatureProductionPlace(city, state, postalCode, country); // location where the signature is created
signer->setSignerRoles(roles); // role(s) of the signer
void setSignatureProductionPlace(const std::string &city, const std::string &stateOrProvince, const std::string &postalCode, const std::string &countryName)
Definition: Signer.cpp:75
void setSignerRoles(const std::vector< std::string > &signerRoles)
Definition: Signer.cpp:186

Optionally specify signature digest method

By default, the hash that is being signed is calculated with SHA-256 algorithm in case of BDOC documents. In case of BDOC format, 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.

Create the signature

The signing method also adds validation data from external services (OCSP and/or 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 http://dd-at.ria.ee/tsa is used. Container holds the Signature object reference and there is no need cleanup memory.

Signature *signature = doc->sign(signer);

Validating the created signatures

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:

signature->validate();

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.

Note
See also Validating signature containers and signatures about more information for validating existing signatures and signature containers.

Save container changes

After the signature has been added and validated, container changes should be saved (Reading and writing DigiDoc documents):

doc->save();

Creating and signing a DigiDoc document (external signing, e.g. in browser)

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.

  1. In Container class, prepare signature XML structure:
    Signature *signature = doc->prepareSignature(signer);
  2. In Signature class, get the hash to be signed in browser:
    std::vector<unsigned char> dataToSign = signature->dataToSign();
    std::vector<unsigned char> signatureMethod = signature->signatureMethod();
    std::string id = signature->id();
    ID can be used when container is saved with digidoc::Container::save and later reloaded to locate signature object.
  3. Sign the hash in browser (e.g. use the hwcrypto.js library)
  4. Add RSA or ECDSA signature value to the signature XML structure: When container was stored on disk before reload container with digidoc::Container::open and use digidoc::Container::signatures() to enumerate signatures to locate correct object with previosly selected ID.
    std::vector<unsigned char> signatureValue = ...;
    signature->setSignatureValue(signatureValue);
  5. Add time-stamp and OCSP data to Signature object, according to the signature's profile (see also section Optionally specify the signature profile for more information):
    signature->extendSignatureProfile(signer->profile());
    std::string profile() const
    Definition: Signer.cpp:145
  6. Write the document to output, as specified in section Reading and writing DigiDoc documents

Reading and writing DigiDoc documents

In order to read an existing DigiDoc file from the file system, do as follows:

auto doc = digidoc::Container::openPtr("<input-file's-path>");
static std::unique_ptr< Container > openPtr(const std::string &path)
Definition: Container.cpp:344

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 (see also for DIGIDOC XML 1.3 documents, for BDOC 2.1 documents and for BDOC 2.1.2 documents).

Write a DigiDoc file (represented with a Container object) to file system with the following method:

digidoc::Container::save("<output-file's-path>");
virtual void save(const std::string &path="")=0
Note
In case of read-only formats (e.g. ASiC-S documents), the save will throw a digidoc::Exception.

Validating signature containers and signatures

Validation of a signed DigiDoc document consists of three main steps:

  1. Call out the main validation method of the library. If there are multiple validation errors then get the errors list.
  2. Check for additional errors/warnings (separate implementation);
  3. Determine the validation status of the document (according to the returned error codes and validation status priorities).

Using the main validation method

You can validate a signature and its validation data - OCSP confirmation and time-stamp (in case of TS profile) - with method:

virtual void validate() const =0

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:

std::vector<digidoc::Exception> digidoc::Exception::causes();
Causes causes() const
Definition: Exception.cpp:183

Checking for additional errors/warnings

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.

Determining the validation status

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:

  1. Returning a validation result of a single signature:
    If there are more than one validation errors that occur when validating a single signature in DigiDoc container then the overall status of the signature should be chosen according to the status priorities.
  2. Returning a validation result of the whole DigiDoc container:
    If there are more than one signatures in a DigiDoc container and the signatures have different validation statuses or validation of the container structure returns a different status then the overall status of the DigiDoc file should be chosen according to the status priorities.

NB! User of the library has to determine the validation status according to the error code that is returned by the library's validation method.

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:

  • The file and signature(s) are not legally valid.
  • If the CA will later be added to the trusted list/trust store then the validation status can change to any of the other statuses described in the current table.

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 installed into your computer"

More info: https://www.id.ee/en/article/digidoc4-klient-viga-36-failed-to-validate-signature-libdigidoc-code-36-message-signers-cert-not-trusted-missing-ca-cert/

  • Sample file: unknown_CA_TS.asice (BDOC 2.1, time-stamp profile)
  • Sample file: unknown_CA_TM.asice (BDOC 2.1, time-mark profile)
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.

Note
  • The file and signature(s) are not legally valid.
  • No further alterations should be made to the file, i.e. no signatures should be added or removed.
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.
Note
  • The file and signature(s) are handled as legally valid.
  • The error(s) are regarded as validation warnings.
  • Validation warnings should be displayed to the user.
  • No further alterations should be made to the file, i.e. no signatures should be added or removed.
  • Creator of the file should be informed about the error situation.
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:

open(int argc, char* argv[]); //utility program's command "open"

Validation status VALID WITH WARNINGS

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.

Warning
User of the DigiDoc library has to decide on his/her own when to use VALID WITH WARNINGS status instead of INVALID: there may be different interpretations of the severity of validation errors in different information systems then the final decision when to use this status has to be made by the library's user according to the requirements of the specific information system.

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:

  • DigiDoc desktop application,
  • Libdigidocpp and DigiDoc4j software libraries' utility programs.

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

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 BDOC container uses weaker encryption method than officially accepted in Estonia."

  • Sample file: weak-sha1-warning-TS.asice (time-stamp profile)
  • Sample file: weak-sha1-warning-TM.bdoc (time-mark profile)
16 ProducedATLateWarning BDOC 2.1 TS

The difference between time-stamp issuance time (genTime value) and 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."

  • Sample file: TS_OCPS_difference_exceeds_15min.asice
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/

  • Sample file: datafile_xmlns_missing.ddoc
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/

  • Sample file: issuerserial_xmlns_missing.ddoc
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/

  • Sample file: old_digidoc_format_1.0.ddoc

Additional information about validation

Overview of validation activities

Overview of validation activities is as follows:

  1. checking that all the data files and signature’s meta-data (signer’s role, etc.) are included in the signature by calculating the data objects’ digest values and comparing them with the <Reference> element values in the signature;
  2. checking that the claimed signer’s certificate is the actual certificate that was used for signing; checking that the "Non-repudiaton" value is set in the "Key Usage" extension of the signer’s certificate;
  3. checking that the signature value is correct by decrypting the value with the signer’s public key and comparing the result with digest calculated from <SignedInfo> element block;
  4. case of time-stamp corresponds to the signature value (by comparing the digest value of <SignatureValue> element’s value and TS response’s digest value);
  5. checking that the OCSP response confirms the signer certificate’s validity and case of time-mark corresponds to the signature value (by comparing the digest value of <SignatureValue> element’s value and OCSP response’s nonce value);
  6. checking that the signer’s, TSA and OCSP responder’s certificates are trusted (i.e. the certificates’ issuers are registered in trust store).
Note
Libdigidocpp library uses TSL lists (Trust Service Status list) to obtain information about trusted certificates during signature validation process. See also TSL overview, TSL standard and Configuring TSL settings.

Extracting data files

A data file can be extracted from container and written to the specified location in the file system or to an output stream.

  1. You can write the data file to a stream and keep it in memory:
    void digidoc::DataFile::saveAs(std::ostream &os);
    virtual void saveAs(std::ostream &os) const =0
  2. The file can be written to file system with the following method:
    void digidoc::DataFile::saveAs(const std::string &path);

List of all the document’s data files can be retrieved with the following method:

std::vector<digidoc::DataFile> digidoc::Container::dataFiles();
virtual std::vector< DataFile * > dataFiles() const =0

For example, read in a DigiDoc document and write its data files to file system as follows:

digidoc::Container doc("<input-file’s-path>"); // read in a document
for(const digidoc::DataFile &file: doc.dataFiles()){ // get the data files’ list
try {
std::string dst = file.fileName(); // get the data file’s name
file.saveAs(dst); // save the data file to working directory
} catch(const digidoc::Exception &e) {
printf(" Document %s extraction: FAILED\n", file.fileName().c_str());
}
}
Offers functionality for handling data files and signatures in a container.
Definition: Container.h:49
Data file wrapper providing methods for handling signed files or files to be signed in Container.
Definition: DataFile.h:30
Base exception class of the digidoc implementation.
Definition: Exception.h:30

Removing signatures and data files

In order to remove a signature from DigiDoc document, use the following method:

virtual void removeSignature(unsigned int index)=0

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:

void digidoc::Container::removeDataFile(unsigned int id);
virtual void removeDataFile(unsigned int index)=0

"Id" parameters of the abovementioned methods represent the signature’s and data file’s sequence numbers in the container. The identifiers are determined when a data file or signature is added to the container, counting starts from zero.

Note
The functionality of modifying files in DigiDoc file format ASiC-S is not supported.

Shutting down the library

After finishing work with Libdigidocpp, then the last task is to shut down the library:

DIGIDOCPP_EXPORT void terminate()
Definition: Container.cpp:178

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.

Exception handling

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:

try {
// code implementation
} catch(const digidoc::Exception &e) {
printf("Exception:%s\n", parseException(e).c_str()); // Sample exception handling method
}

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:

std::string parseException(const digidoc::Exception &e)
{
std::string result = e.msg() + "\n"; // the error message is retrieved
// Iteration through the list of causes:
for(const digidoc::Exception &ex: e.causes())
result += parseException(ex); // Parsing the exceptions recursively
return result; // The error message is returned
}
std::string msg() const
Definition: Exception.cpp:173

Libdigidocpp utility program

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.

Note
The utility program is intended for testing and presentation of sample implementation of the library’s API. The interface of the utility program is not fixed and its long-term stability is not guaranteed.

The general format for executing the program is:

> digidoc-tool [command] [options] [input/output file]
Definition: Conf.h:29

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

Creating and signing a document (local signing)

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. Documents can be created only in BDOC 2.1 format. General form of the command is:

> digidoc-tool create --file=<data-file> <output-bdoc-file>

Available options:

--file= Required

Data file(s) to be signed. The option can occur multiple times.

Warning
It is recommended not to use special characters in the data file’s name, i.e. it is suggested to only use the characters that are categorized as "unreserved" according to RFC3986 (http://tools.ietf.org/html/rfc3986).
--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.

Warning
Data file’s mime-type value must be formatted as specified in RFC2045, section 5.1 (https://tools.ietf.org/html/rfc2045#section-5.1), i.e. the "type" and "subtype" values must be separated with a forward slash character.
--dontsign OptionalDon'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:

Sample: creating new BDOC file, adding multiple data files and signing via PKCS#11 driver
> digidoc-tool create --file=file1.txt --mime=text/plain --file=file2.pdf --mime=application/pdf --country=Estonia
--state=Harjumaa --city=Tallinn --postalCode=12345 --pkcs11 demo-container.bdoc
Input:
--file=file1.txt - a data file to be added to container
--mime=text/plain - data file 'file1.txt' mime-type
--file=file2.pdf - a data file to be added to container
--mime=application/pdf - data file 'file2.pdf' mime-type
--country=Estonia - country where the signature is created
--state=Harjumaa - state where the signature is created
--city=Tallinn - city where the signature is created
--postalCode=12345 - postal code of the signature creation location
--pkcs11 - signing is done via PKCS#11 module
demo-container.bdoc - container to be created (in BDOC 2.1 format)
Sample: creating new BDOC file on Windows, adding data file and signing via CNG API
> digidoc-tool create --file=file1.txt --cng demo-container.bdoc
Input:
--file=file1.txt - a data file to be added to container
--cng - CNG API is used for signing
demo-container.bdoc - container to be created (in BDOC 2.1 format)
Sample: creating new BDOC file on Windows, adding data file and signing via CNG API, dialog windows for certificate selection and PIN insertion are not displayed
> digidoc-tool create --file=file1.txt --cng --selectFirst --pin=01497 demo-container.bdoc
Input:
--file=file1.txt - a data file to be added to container
--cng - CNG API is used for signing
--selectFirst - the first signing certificate in store is used for signing
--pin=01497 - PIN code (PIN2 in case of Estonian ID cards)
demo-container.bdoc - container to be created (in BDOC 2.1 format)

Creating and signing multiple documents

Takes folder as argument folder/content/to/sign and sign them separate containers. For additional options look sign command.

Add additional files to container

Adding additional files to existing unsigned container. Available options are –file and –mime look create command for info.

Creating and signing a document (external signing, e.g. in browser)

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 BDOC 2.1 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://github.com/open-eid/hwcrypto.js for implementing signing in browser environment.

External signing process with websign command is as follows:

  1. After executing the websign command, the utility program outputs the value of hash to be signed (in HEX) to console and waits until user enters the respective signature value
  2. Send the hash to be signed to the signing token (e.g. by using the web signing demo page at https://open-eid.github.io/hwcrypto.js/sign.html)
  3. Conduct signing, enter PIN2, retireve the signed hash (signature value) from the signing token
  4. Enter the signature value (also in HEX) to the console
  5. Utility program continues with signing process and outputs the signed container

General form of the command is:

> digidoc-tool websign --cert=<signer-certificate> --file=<data-file> <output-bdoc-file>

Available options:

--cert= RequiredSigner's certificate, in PEM format.
--file= RequiredData file(s) to be signed. The option can occur multiple times.
--mime= OptionalSpecifies 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 BDOC files:

Sample: creating new BDOC-TS file, specifying signers certificate, adding data files and other meta-data and calculating the RSA signature value in browser
> digidoc-tool websign --cert=signer.cer --file=file1.txt --file=file2.pdf --country=Estonia --state=Harjumaa --city=Tallinn --postalCode=12345 --profile=time-stamp demo-container.bdoc
Input:
--cert=signer.cer - signers certificate
--file=file1.txt - a data file to be added to container
--file=file2.txt - a data file to be added to container
--profile=time-stamp - profile of the signature
--country=Estonia - country where the signature is created
--state=Harjumaa - state where the signature is created
--city=Tallinn - city where the signature is created
--postalCode=12345 - postal code of the signature creation location
demo-container.bdoc - container to be created (in BDOC 2.1 format)

Opening document, validating signatures and extracting data files

Command "open" enables to read in an existing DigiDoc document, print out a list of its contents and validate signatures. By specifying the additional option –extractaAll, then the data files are extracted from the container and stored on the disk. All DigiDoc file formats are supported with this command (except of BDOC1.0). General form of the command is:

> digidoc-tool open <input-container-file>

Available options:

--extractAll OptionalIf 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 OptionalIf set, then validates container before extracting files.
--policy=(POLv1,POLv2) Optional

Signature Validation Policy

Default POLv2

http://open-eid.github.io/SiVa/siva/appendix/validation_policy/

--offline Optionalopen container offline (eg. Don't send to SiVa)

--warnings=

(ignore, warning, error)

OptionalEnables 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:
  • warning – the default value used. The minor technical errors that are considered as warnings, are printed out as warnings.
  • error – the errors that are otherwise considered as warnings (by the utility program), are printed out as errors.
  • ignore – the errors that are otherwise considered as warnings (by the utility program), are not printed out. If there are any other errors present then these are treated as usual.

Output of the default command contains the following data of the container:

Container file: <container’s file name>
Container type: <container’s mime-type>
Documents (<number of data files in container>):
Document (<data file’s mime-type>): <file’s name> (<file’s size> bytes)
Signatures (<number of signatures in container>):
Signature <signature’s sequence number> (<signature’s profile>):
Validation: <signature validation result: OK/FAILED>
EPES policy: urn:oid: <signature policy identifier OID>
SPUri: <URL to the BDOC 2.1 specification document>
Signature method: <signature method URI>
Signing time: <signing time according to computer’s settings (not the official signing time)>
Signing cert: <subject CN field’s value>
Signed by: <subject CN field’s value>
Produced At: <time of OCSP response’s issuance, i.e. official signing time>
OCSP Responder: <OCSP responder certificate CN field’s value>
Message imprint (<length in bytes>): <OCSP responses nonce field’s or TSA messageImprint value (has to correspond to the &lt;SignatureValue&gt; element’s hash)>
TS: <TSA certificate CN field’s value>
TS time: <time of TSA issuance, i.e. official signing time>
TSA: <archive TSA certificate CN field’s value>
TSA time: <time of archive TSA issuance, i.e. official signing time>
Warnings: <possible validation related warnings (see explanation below)>
Note
By default, if the signature validation process discovered errors that are regarded as minor technical errors in digidoc-tool.cpp utility program then the document is considered as VALID WITH WARNINGS, the errors are printed out as warnings to the end user. See also chapter Determining the validation status.

Sample commands for validating signatures and extracting data files:

Sample: opening BDOC container, listing its contents and validating signatures
> digidoc-tool open demo-container.bdoc
Input:
demo-container.bdoc - input DigiDoc file which contents are listed and signatures validated
Output:
Container type: application/vnd.etsi.asic-e+zip
Documents (2):
Document (application/octet-stream): file1.txt (434 bytes)
Document (application/octet-stream): file2.pdf (476841 bytes)
Signatures (1):
Signature 0 (EPES/time-mark):
Validation: OK
EPES policy: urn:oid:1.3.6.1.4.1.10015.1000.3.2.1
SPUri: https://www.skidsolutions.eu/repository/bdoc-spec21.pdf
Signature method: http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
Signing time: 2013-03-13T08:48:13Z
Signing cert: MÄNNIK,MARI-LIIS,47101010033
Signed by: MÄNNIK,MARI-LIIS,47101010033
Produced At: 2013-05-14T23:41:20Z
OCSP Responder: TEST of SK OCSP RESPONDER 2011
Message imprint (51): 30 31 30 0D 06 09 60 86 48 01 65 03 04 02 01 05 00 04 20 10 35 D7 45 F1 42 C1 0C 4D 96 EA 1A 13 C4 34 28 B0 8A 0A 07 47 AA 96 72 0D 3B 1C C9 02 D0 4B 15
TS:
TS time:
TSA:
TSA time:
Sample: opening BDOC container, listing its contents and validating signatures (warnings are displayed as SHA-1 hash function is used in a BDOC file)
> digidoc-tool open weak-sha.bdoc
Input:
weak-sha.bdoc - input BDOC 2.1 file which contents are listed and signatures validated
Output:
Container type: application/vnd.etsi.asic-e+zip
Documents (1):
Document (application/octet-stream): test.txt (314 bytes)
Signatures (1):
Signature 0 (EPES/time-mark):
Validation: OK
EPES policy: urn:oid:1.3.6.1.4.1.10015.1000.3.2.1
SPUri: https://www.skidsolutions.eu/repository/bdoc-spec21.pdf
Signature method: http://www.w3.org/2000/09/xmldsig#rsa-sha1
Signing time: 2012-11-13T11:04:32Z
Signing cert: MÄNNIK,MARI-LIIS,47101010033
Signed by: MÄNNIK,MARI-LIIS,47101010033
Produced At: 2012-11-13T11:04:45Z
OCSP Responder: TEST of SK OCSP RESPONDER 2011
Message imprint (51): 30 31 30 0D 06 09 60 86 48 01 65 03 04 02 01 05 00 04 20 10 35 D7 45 F1 42 C1 0C 4D 96 EA 1A 13 C4 34 28 B0 8A 0A 07 47 AA 96 72 0D 3B 1C C9 02 D0 4B 15
TS:
TS time:
TSA:
TSA time:
Warnings: RefereneceDigestWeak, SignatureDigestWeak,
Sample: opening container, extracting its data files
> digidoc-tool open --extractAll demo-container.bdoc
Input:
--extractAll=demo - Extract all files into current folder
demo-container.bdoc - input DigiDoc file that is extracted
Output:
Extracting documents:
Document(application/octet-stream) extracted to file1.txt (434 bytes)
Document(application/octet-stream) extracted to file2.pdf (476841 bytes)
Sample: opening container, extracting its data files to a specific directory
> digidoc-tool open --extractAll=demo demo-container.bdoc
Input:
--extractAll=demo - Extract all files into folder "demo"
demo-container.bdoc - input DigiDoc file that is extracted
Output:
Extracting documents:
Document(application/octet-stream) extracted to demo/file1.txt (434 bytes)
Document(application/octet-stream) extracted to demo/file2.pdf (476841 bytes)

Adding signatures

Command "sign" enables adding signatures to existing DigiDoc containers. The supported DigiDoc document format is BDOC 2.1.

> digidoc-tool sign <modified-digidoc-container>
--pin= OptionalIf 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:

  • TS - a time-stamp and OCSP confirmation will be added to the signature as validation data.
  • TSA - a time-stamp and OCSP confirmation will be added to the signature as validation data. Additional time-stamp is added for notarize all certificate and revocation info.
Warning
When adding signature to an existing BDOC 2.1 container then the profile of the existing signature should be used for all of the new signatures in the same container.
--XAdESEN OptionalUse XAdES EN profile.
--city= OptionalCity where the signature is created.
--street= OptionalstreetAddress of production place in XAdES EN profile.
--state= OptionalState or province where the signature is created.
--postalCode= OptionalPostal code of the place where the signature is created.
--country= OptionalCountry of origin. ISO 3166-type 2-character country codes are used (e.g. EE)
--role= OptionalSigner’s role(s). The option can occur multiple times.
--sha(224,256,384,512) OptionalUsed 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) OptionalUsed 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) OptionalUsed 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 OptionalOption to change RSA Signature padding (RSA PKCS1.5).
--rsapss OptionalOption to change RSA Signature padding (RSA PSS).
--tsurl OptionalOption to change TS URL.
--dontValidate OptionalDon'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[=] OptionalSigning 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 OptionalSet 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".
--selectFirst OptionalAdditional 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 OptionalAdditional 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= OptionalSigning is done via PKCS#12 module - can be used for testing purposes, currently has been used for testing signature creation with ECC keys. 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:

Sample: adding a signature via PKCS#11 driver
> digidoc-tool sign --pkcs11 demo-container.bdoc
Input:
--pkcs11 - PKCS#11 module is used for signing
demo-container.bdoc - container to be modified
Sample: adding a signature via CNG API
> digidoc-tool sign --cng demo-container.bdoc
Input:
--cng - CNG API is used for signing
demo-container.bdoc - container to be modified
Sample: adding a signature via CNG API, no dialog windows are displayed
> digidoc-tool sign --cng --selectFirst --pin=12345 demo-container.bdoc
Input:
--cng - CNG API is used for signing
--selectFirst - the first signing certificate is used for signing
--pin=12345 - PIN code (PIN2 in case of Estonian ID cards)
demo-container.bdoc - container to be modified

Removing signatures and data files

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 DIGIDOC-XML 1.3 and BDOC 2.1. General format of the command is:

> digidoc-tool remove --document=<doc-id> --signature=<sig-id> <modified-digidoc-container>

Available options:

--document= OptionalSpecifies the sequence number of the data file that is removed from the container. The sequence numbers are counted from zero.
--signature= OptionalSpecifies 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:

Sample: removing signature from container
> digidoc-tool remove --signature=1 demo-container.bdoc
Input:
--signature=1 - sequence number of the signature that is removed
demo-container.bdoc - container to be modified
Sample: removing data files from container
> digidoc-tool remove --document=0 --document=1 demo-container.bdoc
Input:
--document=0 - sequence number of the data file that is removed
--document=1 - sequence number of the data file that is removed
demo-container.bdoc - container to be modified

National and cross-border support

TSL list usage in Libdigidocpp

In case of BDOC 2.1 documents, 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.

Note
The European Commission's TSL that contains URL's and certificates of the national TSL lists can be downloaded here: https://ec.europa.eu/tools/lotl/eu-lotl.xml

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

Note that TSL lists are supported since v3.9 of the library. Since v3.10 of the library, TSL lists are the only supported source of trusted certificates (i.e. in case of BDOC 2.1 document format).

Note
For information about using test TSL lists with Libdigidocpp library, please refer to https://github.com/open-eid/libdigidocpp/wiki/Using-test-TSL-lists

TSL initialization process

TSL lists' initialization process is done during each initialization of the library. By default, the TSL itself and its freshness is checked on-line:

  1. It is checked if LOTL (the master TSL list, tl-mp.xml) is present at the tsl.cache location
  2. If there is no such list present in the cache directory and the online updating mechanism is enabled (see Trust anchor/TSL settings, "tsl.autoupdate") then the TSL list is downloaded from the list's URL (https://ec.europa.eu/tools/lotl/eu-lotl.xml) and saved to tsl.cache directory
    Note
    tsl.autoupdate can be disabled but then the TSL list(s) must be manually saved to the tsl.cache location.
    the TSL lists are not distributed along with the library's installation package, meaning that during the first initialization of the library, the TSL lists need to be downloaded on-line or must be manually copied to the tsl.cache location.
  3. If there is an existing LOTL in the tsl.cache location and the tsl.onlineDigest check is enabled (see Trust anchor/TSL settings, "tsl.onlineDigest") then the freshness of the TSL list is checked based on the list's SHA-256 hash value:
    • The existing TSL list’s hash is calculated over the binary representation of the list
    • The officially published hash value is downloaded (from the same address as the TSL's URL but with .sha2 extension)
    • The hash of existing TSL and the value downloaded on-line are compared
      • If values are different then a new version of the TSL list is downloaded
      • If the hash values are the same or it was not possible to download the hash value from external URL then new version of the TSL is not downloaded. TSL parsing/validation process is continued.
  4. The LOTL is validated:
    • the list's validity is checked in by comparing the user's computer time with the list's <NextUpdate> value.
      • if the list is not valid then the library attempts to download a new list from the list's URL
    • the list's signature is validated by using its signing certificate
  5. National TSLs' data (URLs and certificates) are read from the LOTL.
  6. For each of the national TSL list, the following is done:
    • step 1-3 of the current process is repeated with the national TSL list
    • appropriate trust services are found from the national TSL lists, their certificates are added to the library's internal trusted certificates' store.

Identity tokens in Libdigidocpp

Libdigidocpp library supports the following identity tokens:

  • Estonian national eID card and Digi-ID

The library is also tested with the following tokens (indirectly via the DigiDoc desktop application that uses Libdigidocpp as a base component):

  • Finnish national eID card
  • Latvian national eID card
  • Lithuanian national eID card
  • Aladdin eToken USB authenticator with SK issued certificates for organizations

Interoperability testing

DigiDoc framework cross-usability tests

Automated cross-usability tests of digitally signed and encrypted files are periodically carried out between different DigiDoc software libraries:

  • Cross-usability of BDOC 2.1 (.bdoc or .asice) file format with TM (time-mark) profile is tested between DigiDoc4j and Libdigidocpp libraries.
  • Cross-usability of BDOC 2.1 (.bdoc or .asice) file format with Ts (time-stamp) profile is tested between DigiDoc4j and Libdigidocpp 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).

Libdigidocpp implementation notes

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.

Digital signature related notes

  1. The supported BDOC 2.1 signature profiles are BDOC-TM (XAdES-EPES signature with time-mark) and BDOC-TS (XAdES-BES signature with time-stamp and OCSP confirmation). The basic BDOC-TM profile is XAdES-EPES as BDOC 2.1 specification requires that <SignaturePolicyIdentifier> element is present (BDOC2.1:2013, chap. 5.2). The basic BDOC-TS profile is XAdES-BES as the <SignaturePolicyIdentifier> element is not supported in case of BDOC 2.1 signatures with time-stamps. It is expected that either a time-mark or time-stamp and OCSP confirmation have been added to the signature as according to BDOC 2.1 specification (BDOC2.1:2013, chap. 6) a signature is not considered complete or valid without validation data from external services (i.e. a time-mark or time-stamp).
  2. For better international compatibility reasons, the library also accepts BDOC-TS signatures that are based on XAdES-EPES basic profile during validation time (i.e. the signature contains <SignaturePolicyIdentifier> element and a time-stamp).
  3. One time-mark is allowed for each signature in case of TM profile; one time-stamp and one OCSP confirmation are allowed for each signature in case of TS profile (due to security reasons and in order to maintain testing efficiency).
  4. In case of BDOC signature with time-mark, the OCSP confirmation's (i.e. time-mark's) nonce field’s value is calculated as follows:
    • the contents of <SignatureValue> element (i.e. the value without XML tags) is taken and decoded from base64 encoding;
    • digest of the value found in the previous step is calculated by using SHA-256 algorithm.;
    • the digest value found in the previous step and the digest algorithm that was used are transformed as defined by the following ASN.1 structure:
      TBSDocumentDigest ::= SEQUENCE {
      algorithm AlgorithmIdentifier,
      digest OCTET STRING
      }
    • the ASN.1 block value produced in the previous step is included in the OCSP request’s "nonce" field and must be present in the respective field of the OCSP response.
  5. In case of signing with ECC keys (by using ECDSA algorithm), concatenation method is used for creating signature value.
  6. In case of BDOC 2.1 documents, SHA-256 hash function is used by default when calculating data file digests and the digest that is signed.
  7. When a hash function that is weaker than SHA-256 (or SHA-224 in the special case with pre-2011 ID-cards) has been used then a warning message about weak digest method is produced to the user. It is recommended to regard the error as a validation warning (identically to DigiDoc desktop application and digidoc-tool.cpp utility program).
  8. During signature creation, it is checked that there is only one <ClaimedRole> element in the signature, which contains the signer’s role and optionally the signer’s resolution. If the <ClaimedRole> element contains both role and resolution then they must be separated with a slash mark, e.g. "role / resolution". Note that when setting the resolution value then role must also be specified.
  9. The signature policy document’s hash value in <SigPolicyHash> element is checked during validation process (even though it is not mandatory according to BDOC 2.1 specification BDOC2.1:2013, chap. 5.2). The hash value must correspond to the hash value of the document that is located at https://www.skidsolutions.eu/repository/bdoc-spec20.pdf.
  10. <Transforms> element is allowed in the signature since v3.10 of the library for interoperability purposes. The transformation algorithms are not applied during signature validation.
  11. XML namespace prefixes are used in case of all XML elements (e.g. "asic:", "ds:", "xades:").
  12. The data file’s MIME type that is used in case of Libdigidocpp’s utility program is always "application/octet-stream" for testing purposes.
  13. The <ds:Signature> element’s Id attribute value is set to "S<seq_no>" during signature creation where sequence numbers are counted from zero. Other Id values that are used in the sub-elements of the <ds:Signature> element contain the signature’s Id value as a prefix. During verification, different Id attribute values are also supported but are not tested periodically.
  14. signatures*.xml file's XML structure validation is done on the basis of XAdES XML Schema (XAdES), however, there are additional checks to determine any unsupported elements that are allowed by the XAdES specification but are not allowed by the BDOC 2.1 specification (BDOC). The unsupported elements are CounterSignature, CompleteCertificateRefs, CompleteRevocationRefs, AttributeCertificateRefs, AttributeRevocationRefs, SigAndRefsTimeStamp, RefsOnlyTimeStamp, AttrAuthoritiesCertValues, AttributeRevocationValues, CommitmentTypeIndicationType, AllDataObjectsTimeStamp, IndividualDataObjectsTimeStampType.
  15. Special characters in URI attribute values are handled according to RFC3986 (since v3.9 of the library): the characters are percent-encoded, except of unreserved characters and delimiters. Both percent-encoded and non-percent-encoded characters are supported during signature's validation. Note that as a result, the files that contain special characters in URI values and have been created with v3.9 might not be compatible with v3.8 of the library.
  16. When validating a BDOC-TS document then the difference between OCSP validity confirmation's production time (producedAt field) and time-stamp's production time (getTime field) is checked. An exception is thrown if the OCSP confirmation's time is earlier than time-stamp's time. If the OCSP confirmation's time is later than time-stamp's time by more than 15 minutes then a warning is returned. If the difference is more than 24 hours then exception is thrown.
  17. During BDOC signature creation, it is checked that the difference between the signer's computer time and the OCSP response's production time (producedAt value) would not exceed 15 minutes. If the difference exceeds 15 minutes then an exception is returned and signing is cancelled.
  18. In case of BDOC-TS signature, the time-stamping authority's (TSA's) certificate is not added to the <CertificateValues> element (differently from the requirements of BDOC specification, chap 6) to avoid duplication of the certificate in the signature. It is expected that the TSA certificate is present in the time-stamp token itself.

Certificate related notes

  1. Valid signatures (qualified electronic signatures) can be created with a certificate that has "Non-repudiation" value (also referred to as "Content Commitment") in its "Key usage" field. The requirement is based on the following sources:
  2. Signature can be created with a certificate that doesn’t have "Non-repudiation" value in its "Key-Usage" field when specific parameters have been set but validation of such signature will produce a respective error message and the signature is not considered as a qualified electronic signature.
  3. During signature validation, it is checked that the validity periods of the signer’s certificate and all the certificates in its CA chain include the signature creation time (value of the producedAt field in OCSP response).

Container related notes

  1. BDOC 2.1 files are created with .bdoc file extension. Extensions .asice and .sce are supported and recognized only when reading in an existing BDOC 2.1 file which has the respective extension value.
  2. Signatures are stored in META-INF/signatures*.xml files where ‘*’ is a sequence number, counting is started from zero.
  3. There can be only one signature in one signatures*.xml file due to BDOC format’s legacy issues. Multiple signatures in one signatures*.xml file is not supported in order to maintain testing efficiency. The <ds:Signature> element’s Id attribute values in different signatures*.xml files are generated in the form of "S<seq_no>", the sequence numbers are always unique within one BDOC container.
  4. It is not allowed to add two data files with the same name to the container as the signed data file must be uniquely identifiable in the container.
  5. All data files in the container must be signed. All signatures in the container must sign all of the data files.
  6. The META-INF/manifest.xml file’s version attribute value is "1.0" (instead of "1.2") as the results of ASiC plug-tests event shows that version 1.0 is used only. The requirement of the OpenDocument version attribute value comes from OpenDocument standard which is referred to in ASiC standard.
  7. Relative file paths are used, for example "META-INF/signatures*.xml" and "document.txt" instead of "/META-INF/signatures*.xml" and "/document.txt" to ensure better interoperability with third party applications when validating signatures.
  8. The ZIP container’s comment field contains version number of the library that was used for creating the file. The value can be useful, for example, when trying to determine the origin of an erroneous file.
  9. "mimetype" file is not compressed in the BDOC 2.1 file’s ZIP container as the results of ASiC plug-tests event shows that this solution is most widely used.
  10. When a data file is added to the container then the modification time of the file (as it is registered in the file system) is preserved also in the ZIP container file. There is an exception if the file is added by reading it from an input stream - in that case, the current timestamp value is registered as "last modified" time in the ZIP file.