libdigidocpp.dox

/*! @mainpage

Libdigidocpp is a C++ library for creating, signing, and verifying digitally signed documents according to the XML Advanced Electronic Signatures (\ref XAdES "XAdES") and Associated Signature Containers (\ref ASiC "ASiC") standards.

Development of the library can be monitored in GitHub environment: <a href="https://github.com/open-eid/libdigidocpp">https://github.com/open-eid/libdigidocpp</a>

Additional documentation about the library can be found from GitHub wiki section, see https://github.com/open-eid/libdigidocpp/wiki
*/

/*! \page manual Libdigidocpp Programmer's Guide

\section introduction Introduction
Libdigidocpp is a C++ library for creating applications that create and verify digital signatures. Digitally signed files are created as Associated Signature Containers (\ref ASiC "ASiC"), using the .asice file extension and XML Advanced Electronic Signatures (\ref XAdES "XAdES") standardized by the European Telecommunications Standards Institute (ETSI).

Additionally, the libdigidocpp library can create, save, read, validate, and extend digitally timestamped containers (using the .asics file extension) with a single data file and \ref RFC3161 "RFC 3161" time-stamp tokens. ASiC containers with \ref CAdES "CAdES" signatures, \ref PDF "PDF", and \ref DDOC "DDOC" files can be validated with the \ref SiVa service.

Development of the library can be monitored in GitHub environment: <a href="https://github.com/open-eid/libdigidocpp">https://github.com/open-eid/libdigidocpp</a>.

\anchor releasenotes
Changes by version are listed on the separate \ref release_notes "Release Notes" page.

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

\image html digidoc_framework.svg "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. All applications share common digitally signed file formats.






\subsection format Format of digitally signed file
Actively used digitally signed file formats in DigiDoc system are:
- ASiC-E - default format for files in Libdigidocpp library, described in \ref ASiC "The ETSI standard ETSI EN 319 162-1";
- BDOC 2.1 - legacy format, described in \ref BDOC "BDOC2.1:2013", The library implements only read-only support for the format;
- ASiC-S - simple signature container, described in \ref ASiC "The ETSI standard ETSI EN 319 162-1". The library supports opening and validating containers with XAdES signatures. For containers with \ref RFC3161 "RFC 3161" time-stamp tokens, creating, saving, reading, validating, and archive-manifest time-stamp extension are supported.

The following chapters provide an overview of the ASiC-E (XAdES) digitally signed file format, which is the preferred format for creating signed documents with Libdigidocpp.



\subsubsection container ASiC-E (XAdES) container format
The ETSI standard \ref ASiC "EN 319 162-1" defines a container format for encapsulating signed files, signatures, and supporting information. ASiC-E documents use the Extended form and contain signatures conforming to \ref XAdES "XAdES EN 319 132-1".

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 ASiC-E container is signed then all files in the container are signed, except of the mimetype file and files in META-INF subdirectory.

Original files (which were signed) along with the signature(s), timestamp(s), validation confirmation(s) and certificates are encapsulated within the container. As a result, it is possible to verify signature validity without any additional external information – the verifier should trust the issuer of signer’s certificate, TS Authority and the OCSP responder’s certificate.

\image html asic.svg "ASiC-E container's contents"




\subsubsection profiles Legacy BDOC signature profiles

The format of the BDOC 2.1 digitally signed file is based on ETSI \ref XAdES "XAdES TS 101 903" standard. The XAdES standard defines formats for advanced electronic signatures that remain valid over long periods of time. The ETSI standard \ref XAdES "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.


\paragraph BDOC-TM BDOC signature with time-mark
The BDOC signature with time-mark is based XAdES-EPES signature (Explicit Policy based Electronic Signature, see \ref XAdES "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 &lt;SignatureValue&gt; 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:
\code{.cpp}
	TBSDocumentDigest ::= SEQUENCE {
		algorithm AlgorithmIdentifier,
		digest OCTET STRING
	}
\endcode
The element digest is a hash value of the binary value of the &lt;SignatureValue&gt; element’s contents, element algorithm determines the used hash algorithm as defined in \ref RFC5280 "RFC 5280" clause 4.1.1.2.


<b>The time-mark provides proof of the following:</b>
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).

\note 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.

\image html security.svg "Security model of time-marking mechanism"


\paragraph BDOC-TS BDOC signature with time-stamp

The BDOC signature with time-stamp is based on XAdES-BES signature (Basic Electronic Signature, see \ref 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. A time-stamp compliant with \ref RFC3161 "RFC 3161" is obtained from a time-stamping service. The hash of the created signature (&lt;SignatureValue&gt; 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. An \ref RFC6960 "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.

\note The \ref RFC3161 "RFC 3161 TSTInfo.genTime" field records when the TSA created the time-stamp token. This issuance time is regarded as the time of signature creation.

\subsubsection asics ASiC-S container format
In addition to the Associated Signature Extended form (ASiC-E), the \ref ASiC "ETSI standard EN 319 162-1" defines a Simple form which is used for encapsulating a single data file and a signature or time-stamp token associated with it.

An ASiC-S container is a ZIP file consisting of the following objects:
- an optional file named "mimetype", containing only the following value: application/vnd.etsi.asic-s+zip
- data object (file) in original format.
- one signature form:
  - META-INF/signatures.xml containing XAdES signatures; or
  - META-INF/timestamp.tst containing the initial \ref RFC3161 "RFC 3161" time-stamp token.
- for the time-stamp-token form, optional META-INF/ASiCArchiveManifest*.xml and META-INF/timestamp*.tst files containing additional archive-manifest time-stamp layers.

Since version 3.17.0, libdigidocpp can open and locally validate ASiC-S containers containing XAdES signatures in META-INF/signatures.xml. This variant is read-only: creating, adding signatures to, and saving ASiC-S/XAdES containers are not supported.

The library also supports local creation and validation of ASiC-S containers with a time-stamp token (the container includes META-INF/timestamp.tst). The time-stamp token is a binary representation of TimeStampToken as defined in \ref RFC3161 "RFC 3161". The time-stamp is obtained from a time-stamping service and is calculated over the entire binary content of the data object.
Since both the original file and time-stamp are included in the container, it is possible to verify that the timestamped file existed at a certain point of time.

An existing time-stamp token can be extended by adding an ASiC archive manifest and a new time-stamp token. Each new layer protects the data object and the preceding time-stamp information. See \ref extend-validity for the high-level validity-extension workflow.


\section overview Overview






\subsection Supported 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.
<table>
<tr>
  <th>Feature</th>
  <th>Supported values</th>
</tr>
<tr>
  <td>DigiDoc document format</td>
  <td>
- ASiC-E - the main document format to be used.
- ASiC-S - a single-data-file container. Opening and validating XAdES signatures are supported; this variant is read-only. For \ref RFC3161 "RFC 3161" TimeStampToken containers, creation, saving, validation, and archive-manifest time-stamp extension are supported.
- BDOC 2.1 - legacy read-only compatibility.

\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/).
</td>
</tr>
<tr><td>Signature profile</td>
<td>Signature profiles are based on the profiles defined by XAdES (\ref XAdES "XAdES").
- time-stamp (TS) - signature profile in case of which the certificate validity information is added to the signature with an \ref RFC6960 "RFC 6960" OCSP confirmation; the signing time information is added with an \ref RFC3161 "RFC 3161" time-stamp token retrieved from a time-stamping service. In this case, signature creation time is regarded as the issuance time of the time-stamp token (\ref RFC3161 "RFC 3161 TSTInfo.genTime").
- 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 (TSA/LTA) - the signature and its accompanying validation data are time-stamped to provide long-term validity. Eligible ASiC-E XAdES signatures receive an ArchiveTimeStamp element. ASiC-S TimeStampToken signatures are extended with an ASiC archive manifest and another \ref RFC3161 "RFC 3161" time-stamp token.
</td>
</tr>
<tr><td>Trust anchors</td>
<td>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 \ref TSL "Trusted Lists". For more information about the TSL implementation and configuration possibilities in Libdigidocpp library, see \ref TSL-overview and \ref CA-settings.
</td>
</tr>
<tr><td>Signature creation module</td>
<td>
- 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.
</td>
<tr>
<td>Cryptographic token type</td>
<td>
- Smart card, e.g. Estonian ID card. Supported signature creation modules are PKCS#11 and Windows CryptoAPI.
\note Usage of SafeNet USB tokens with a Digital Stamp certificate (https://www.skidsolutions.eu/en/services/Digital-stamp) has been tested indirectly with Libdigidocpp through the DigiDoc desktop application, which uses Libdigidocpp as a base layer.
</td>
</tr>
<tr><td>Public-key algorithm</td>
<td>
- RSA
- ECDSA
</td>
</tr>
</table>




\subsection Component Component model
The figure below describes the architecture of software and hardware components that are used when creating signatures with Libdigidocpp library.
\image html components.svg "Components used in Libdigidocpp implementation when signing with smart card"
<table>
<tr><th>Component</th><th>Description</th></tr>
<tr><td>PKCS#11</td><td>Widely adopted platform-independent API to cryptographic tokens (HSMs, smart cards and USB tokens), a standard management module of the cryptographic token and its certificates</td></tr>
<tr><td>CryptoAPI</td><td>Microsoft Cryptography API. Programming API for implementing cryptographic functions in Windows environment.</td></tr>
<tr><td>PC/SC</td><td>Standard communication interface between the computer and the smart card,  a cross-platform API for accessing smart card readers</td></tr>
<tr><td>IFDHandler</td><td>Interface Device Handler  for CCID readers</td></tr>
<tr><td>CCID</td><td>USB driver  for Chip/Smart Card Interface Devices </td></tr>
<tr><td>Reader</td><td>Device used for communication with a smart card</td></tr>
</table>



\subsection Dependencies Dependencies
\subsubsection libraries Software libraries
Libdigidocpp library depends on the software libraries listed below.
<table>
<tr><th>Base Component</th><th>Required/optional</th><th>Description</th></tr>
<tr><td>OpenSSL</td><td>required</td><td>Used for validating certificates and digest values.</td></tr>
<tr><td>libxml2</td><td>required</td><td>Used for validating the documents according to XML Schema, reading and writing XML.</td></tr>
<tr><td>xmlsec</td><td>required</td><td>Used for handling signature related components.</td></tr>
<tr><td>ZLIB</td><td>required</td><td>Used when compressing and extracting ASiC files in ZIP format.</td></tr>
<tr><td>Minizip</td><td>required</td><td>Used when creating and opening ZIP container for ASiC file. If the component is not found from system then bundled version with source code is used. Forms a part of ZLIB component.</td></tr>
<tr><td>PKCS11</td><td>optional</td><td>Used for searching for default PKCS#11 driver in the system so that its path could be registered in configuration entries.</td></tr>
<tr><td>Doxygen</td><td>optional</td><td>Used for generating API documentation from source code.</td></tr>
<tr><td>SWIG</td><td>optional</td><td>Used for creating C#, Java, and Python bindings.</td></tr>
</table>



\subsubsection Schemas XML Schemas
Several XML schemas are used when creating digitally signed documents in ASiC file format and validating their structure. The schemas are included in etc/schema/ subdirectory of the Libdigidocpp distribution package, their description is given in the table below.

\note Some modifications have been made to some of the schemas. Differences in comparison with the original schemas are listed in section \ref schema-modification of the current document.

<table>
<tr><th>Schema file</th><th>Description</th>
</tr><tr><td>OpenDocument_manifest.xsd</td><td>OASIS OpenDocument v1.2 (\ref OpenDocument "OpenDocument")
Defines the structure of META-INF/manifest.xml file in ASiC container.
https://docs.oasis-open.org/office/v1.2/csd06/OpenDocument-v1.2-csd06-manifest-schema.rng
</td></tr><tr><td>OpenDocument_dsig.xsd</td><td>OASIS OpenDocument v1.2 (\ref OpenDocument "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
</td></tr><tr><td>en_31916201v010101.xsd</td><td>Associated Signature Containers (\ref ASiC "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/
</td></tr><tr><td>xmldsig-core-schema.xsd</td><td>XML Signature Core Schema Instance (\ref XML-DSIG "XML-DSIG")
Defines XML syntax for digital signatures.
http://www.w3.org/TR/2008/REC-xmldsig-core-20080610/xmldsig-core-schema.xsd
</td></tr><tr><td>XAdES01903v132-201601.xsd</td><td>XML Advanced Electronic Signatures (\ref XAdES "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
</tr><tr><td>XAdES01903v141-201601.xsd</td><td>Defines XML syntax for additional elements of XAdES signatures that were added with version 1.4.1 of the (\ref XAdES "XAdES EN") standard. Used for XAdES archive time-stamps, including the ArchiveTimeStamp element.
http://uri.etsi.org/01903/v1.4.1/XAdES01903v141-201601.xsd
</td></tr><tr><td>ts_119612v020201_201601xsd.xsd<br />ts_119612v020101_additionaltypes_xsd.xsd<br />ts_119612v020101_sie_xsd.xsd</td><td>Defines the format of Trust Service status Lists (\ref TSL) that contain information about trusted CA, OCSP and TSA certificates.
</td></tr><tr><td>conf.xsd</td><td>Configuration properties’ schema. Defines the Libdigidocpp configuration file’s digidocpp.conf structure (see also \ref conf).
</td></tr>
</table>

The following figure describes dependencies between the abovementioned schemas (direction of the arrow indicates the direction of dependency).
\image html schemas.svg "Dependencies between XML Schemas"

\paragraph schema-modification 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 \ref Schemas.

Modifications are marked between xml comment tags.

<b>Schema en_31916201v010101.xsd</b>

1) The schema’s location has been altered so that the imported schema file is looked up from the local file system.
\code{.xml}
<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" -->
\endcode
2) Additional schema’s location imports has been added so that the imported schema file is looked up from the local file system.
\code{.xml}
<xsd:import namespace="http://uri.etsi.org/01903/v1.3.2#" schemaLocation="XAdES01903v132-201601.xsd"/>
<xsd:import namespace="http://uri.etsi.org/01903/v1.4.1#" schemaLocation="XAdES01903v141-201601.xsd"/> 
\endcode

<b>Schema xmldsig-core-schema.xsd</b>

1) The XMLSchema.dtd reference has been commented out due to implementation issues (otherwise a warning message would be produced).
\code{.xml}
<!--
<!DOCTYPE schema
  PUBLIC "-//W3C//DTD XMLSchema 200102//EN" "http://www.w3.org/2001/XMLSchema.dtd"
 [
   <!ATTLIST schema
     xmlns:ds CDATA #FIXED "http://www.w3.org/2000/09/xmldsig#">
   <!ENTITY dsig 'http://www.w3.org/2000/09/xmldsig#'>
   <!ENTITY % p ''>
   <!ENTITY % s ''>
  ]>
-->
\endcode
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.
\code{.xml}
<complexType name="X509IssuerSerialType">
  <sequence>
    <element name="X509IssuerName" type="string"/>
    <element name="X509SerialNumber" type="string"/> <!-- originally type="integer" -->
  </sequence>
</complexType>
\endcode

<b>Schema XAdES01903v132-201601.xsd</b>

1) The schema’s location has been modified so that the file is looked up from the local file system.
\code{.xml}
<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" -->
\endcode
2) The "type" attribute has been added, otherwise a warning message would be produced.
\code{.xml}
  <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>
\endcode
3) The "type" attribute has been added, otherwise a warning message would be produced.
\code{.xml}
  <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>
\endcode
4) Change child elements of type SignedSignaturePropertiesType from "xsd:sequence" to "xsd:all" in order to allow the child elements to be listed in any order.
\code{.xml}
<xsd:complexType name="SignedSignaturePropertiesType">
  <xsd:all>
    <xsd:element ref="SigningTime" minOccurs="0"/>
    <xsd:element ref="SigningCertificate" minOccurs="0"/>
    <xsd:element ref="SigningCertificateV2" minOccurs="0"/>
    <xsd:element ref="SignaturePolicyIdentifier" minOccurs="0"/>
    <xsd:element ref="SignatureProductionPlace" minOccurs="0"/>
    <xsd:element ref="SignatureProductionPlaceV2" minOccurs="0"/>
    <xsd:element ref="SignerRole" minOccurs="0"/>
    <xsd:element ref="SignerRoleV2" minOccurs="0"/>
    <xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
  </xsd:all>
  <xsd:attribute name="Id" type="xsd:ID" use="optional"/>
</xsd:complexType>
\endcode
5) Change child elements of type SignatureProductionPlaceType from "xsd:sequence" to "xsd:all" in order to allow the child elements to be listed in any order.
\code{.xml}
<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>
\endcode

<b>Schema XAdES01903v141-201601.xsd</b>

1) The schema's location has been modified so that the file is looked up from the local file system.
\code{.xml}
<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" -->
\endcode

<b>Schema ts_119612v020201_201601xsd.xsd</b>

1) The schemas' locations have been modified so that the file is looked up from the local file system.
\code{.xml}
<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" -->
\endcode
2) The schemas' locations have been added so that TSL extension content can be validated through lax processing.
\code{.xml}
<xsd:import namespace="http://uri.etsi.org/TrstSvc/SvcInfoExt/eSigDir-1999-93-EC-TrustedList/#" schemaLocation="ts_119612v020101_sie_xsd.xsd"/>
<xsd:import namespace="http://uri.etsi.org/02231/v2/additionaltypes#" schemaLocation="ts_119612v020101_additionaltypes_xsd.xsd"/>
\endcode

<b>Schema ts_119612v020101_sie_xsd.xsd</b><br />
1) The schemas' locations have been modified so that the file is looked up from the local file system.
\code{.xml}
<xsd:import namespace="http://uri.etsi.org/01903/v1.3.2#" schemaLocation="XAdES01903v132-201601.xsd"/>
<!-- originally "http://uri.etsi.org/01903/v1.3.2/XAdES.xsd" -->
\endcode

<b>Schema ts_119612v020101_additionaltypes_xsd.xsd</b><br />
1) The schemas' locations have been modified so that the file is looked up from the local file system.
\code{.xml}
<xsd:import namespace="http://uri.etsi.org/02231/v2#" schemaLocation="ts_119612v020201_201601xsd.xsd"/>
<!-- originally "http://uri.etsi.org/19612/v1.2.1/tsl.xsd" -->
<xsd:import namespace="http://uri.etsi.org/01903/v1.3.2#" schemaLocation="XAdES01903v132-201601.xsd"/>
<!-- originally "http://uri.etsi.org/01903/v1.3.2/XAdES.xsd" -->
\endcode





\section conf Configuring Libdigidocpp

\tableofcontents

\subsection loading 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 \ref sample-conf.

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:
\code{.cpp}
	// Initialize global configuration settings from a non-default location
	digidoc::Conf::init(new digidoc::XmlConf("<file-path-and-name>"));
	// then initialize the library
	digidoc::initialize();
\endcode
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.

\subsection parameters 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).

\subsubsection logging-settings Logging settings
<table>
<tr>
  <th>Parameter name</th>
  <th>Comments</th>
</tr>
<tr>
  <td>log.file</td>
  <td>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.
</td>
</tr>
<tr>
  <td>log.level</td>
  <td>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.
</td>
</tr>
</table>

\subsubsection TS-settings Time-stamping service settings
<table>
<tr>
  <th>Parameter name</th>
  <th>Comments</th>
</tr>
<tr>
  <td>ts.url</td>
  <td>Specifies the URL of the time-stamping service that is used during signature creation, needed only in case of TS signature profile. By default, the RIA's time-stamping service is used by the library (https://eid-dd.ria.ee/ts)
</td>
</tr>
</table>

\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/article/trust-services-timestamping-service/.


\subsubsection VerifyService-settings Signature Verify Service settings
<table>
<tr>
  <th>Parameter name</th>
  <th>Comments</th>
</tr>
<tr>
  <td>verify.serivceUri</td>
  <td>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)
</td>
</tr>
</table>


\subsubsection pkcs11-settings PKCS#11 settings
<table>
<tr>
  <th>Parameter name</th>
  <th>Comments</th>
</tr>
<tr>
  <td>pkcs11.driver.path</td>
  <td>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)
</td>
</tr>
</table>

\subsubsection CA-settings 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 \ref TSL-overview and \ref TSL "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 \ref initialization.
- When using digidoc-tool utility program then it is possible to specify necessary TSL parameters on the command line. See also \ref digidoc-tool.
- For information about using test TSL lists with Libdigidocpp library, please refer to https://github.com/open-eid/libdigidocpp/wiki/Using-test-TSL-lists

<table>
<tr>
  <th>Parameter name</th>
  <th>Comments</th>
</tr>
<tr>
  <td>tsl.autoupdate</td>
  <td>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.</td>
</tr>
<tr>
  <td>tsl.cache</td>
  <td>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
  </td>
</tr>
<tr>
  <td>tsl.onlineDigest</td>
  <td>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.</td>
</tr>
<tr>
  <td>tsl.timeOut</td>
  <td>TSL downloading timeout for each TSL list. The default value is 10 seconds.</td>
</tr>
</table>





\subsubsection proxy-settings HTTP proxy settings
<table>
<tr>
  <th>Parameter name</th>
  <th>Comments</th>
</tr>
<tr>
  <td>proxy.host</td>
  <td>Specifies the proxy hostname, e.g. proxy.example.net</td>
</tr>
<tr>
  <td>proxy.port</td>
  <td>Specifies the proxy port, e.g. 8080</td>
</tr>
<tr>
  <td>proxy.user</td>
  <td>Specifies the proxy username.</td>
</tr>
<tr>
  <td>proxy.pass</td>
  <td>Specifies the proxy password.</td>
</tr>
<tr>
  <td>proxy.tunnelSSL</td>
  <td>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. </td>
</tr>
<tr>
  <td>proxy.forceSSL</td>
  <td>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. </td>
</tr>
</table>


\subsubsection digest-settings Digest type settings
<table>
<tr>
  <th>Parameter name</th>
  <th>Comments</th>
</tr>
<tr>
  <td>signer.signatureDigestUri</td>
  <td>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</td>
</tr>
<tr>
  <td>signer.digestUri</td>
  <td>Specifies the digest algorithm that is used for calculating all the hash values in the signature. By default, the SHA-256 algorithm is used</td>
</tr>
</table>



\subsubsection ocspresponder-settings 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.

<table>
<tr>
  <th>Parameter name</th>
  <th>Comments</th>
</tr>
<tr>
  <td>ocsp issuer</td>
  <td>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.
</td>
</tr>
</table>

\subsection sample-conf Sample configuration file
\includelineno src/digidocpp.conf






\section usage Using Libdigidocpp API

\tableofcontents
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.

\subsection string-encoding String encoding
All <tt>std::string</tt> values passed to or returned from the API are UTF-8 encoded. This applies to file paths, media types, and all other string parameters and return values throughout the library.

\subsection initialization Initialization
Libdigidocpp's initialization method conducts the following operations:
1. initializes dependent libraries (see also \ref libraries)
2. loads configuration settings from default configuration files
3. initializes trust anchors: initializes TSL lists. See \ref TSL-init 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:
\code{.cpp}
    // Optionally initialize global configuration file to use non-default settings
    digidoc::Conf::init(new digidoc::XmlConf("<file-path-and-name>"));
    // Initialize the library
    digidoc::initialize();
\endcode

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.





\subsection creating Creating and signing a DigiDoc document (local signing)

\subsubsection containercreate Creating a DigiDoc container
Create a new container object and specify the DigiDoc document's type, for example:
\code{.cpp}
    auto doc = digidoc::Container::createPtr("<output-file's-path>"); // create new container
\endcode
Container class is used to incorporate the data of a DigiDoc document.


\subsubsection asics-create Creating and timestamping an ASiC-S container
Create an ASiC-S container by using an .asics or .scs output file name. An ASiC-S TimeStampToken container supports exactly one data file and one initial \ref RFC3161 "RFC 3161" time-stamp token.

\code{.cpp}
auto doc = digidoc::Container::createPtr("timestamped-document.asics");
doc->addDataFile("document.txt", "text/plain");

digidoc::Signer *signer = ...;
signer->setProfile("TimeStampToken"); // "time-stamp-token" is also accepted
digidoc::Signature *timestamp = doc->sign(signer);
timestamp->validate();
doc->save();
\endcode

ASiC-S TimeStampToken creation uses the one-step digidoc::Container::sign method. External two-step signing with digidoc::Container::prepareSignature is not supported for this format. Additional archive-manifest time-stamp layers can be added with the workflow described in \ref extend-validity.




\subsubsection adddatafile 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):
\code{.cpp}
    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
\endcode
2. adding the data by reading the it from file system
\code{.cpp}
    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
\endcode

Parameter mediaType in the methods above stands for a MIME type of the data file, for example "text/plain" or "application/msword". Value "application/octet-stream" is used by default.
Calling out any of the methods listed above shall create a new DataFile object and add it to the DigiDoc container's data file collection.
Note that in order to add a data file to a container, the container has to be unsigned and there shouldn't be an existing data file with the same name in the container. If a container is signed then it is possible to add data files to it only after the signatures are removed.

The stream overload's fileName is the name stored inside the container. It must be a single non-empty path component: ".", "..", forward slashes, and backslashes are rejected. The file-system overload accepts a source path and stores only its base name. When an existing ASiC-E container is opened, safe relative subdirectories separated by forward slashes are accepted, but absolute paths, backslashes, trailing slashes, and empty, ".", or ".." path segments are rejected. ASiC-S data files must be at the container root.

\warning - It is important to pay attention that the data file's mime type value in manifest.xml file and in signatures*.xml file's &lt;DataObjectFormat&gt;&lt;MimeType&gt; 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 ASiC-E 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.


\warning - Data file’s mime-type value must be formatted as specified in \ref RFC2045 "RFC 2045", section 5.1, i.e. the "type" and "subtype" values must be separated with a forward slash character.


\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 \ref RFC3986 "RFC 3986".

\note By default, it is recommended to use data file mime-type value "application/octet-stream" for all file types.

\note For resource-exhaustion protection, structural and other non-data ZIP entries, such as manifests and signature XML, are limited to 10 MiB when read into memory. HTTP service responses are also limited to 10 MiB after decompression. Data files use a separate streaming and temporary-file strategy and are not subject to the 10 MiB metadata limit.



\subsubsection API-add-sign 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 Libdigidocpp library uses TSL lists (Trust Service Status list) to obtain information about trusted certificates during signature creation process. See also \ref TSL-overview "TSL overview", \ref TSL "TSL standard" and \ref CA-settings "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 \ref pkcs11-settings.
\code{.cpp}
    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);
\endcode
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.


\paragraph API-sign-profile Optionally specify the signature profile
The supported signature profiles are (see also \ref Supported, 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 recorded in the token's \ref RFC3161 "RFC 3161 TSTInfo.genTime" field.

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

Set the profile value as follows:
\code{.cpp}
std::string profile = "time-stamp"; // or "time-stamp-archive"
signer->setProfile(profile);
\endcode


\paragraph API-sign-data 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.
\code{.cpp}
    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
\endcode

\paragraph API-signature-hash Optionally specify signature digest method
By default, the hash that is being signed is calculated with SHA-256 algorithm.
You can also use a different digest algorithm for calculating the hash that is signed (this does not affect calculating other hash values). For that, use the digidoc::Signer::setMethod(const std::string &method) method.


\paragraph API-sign-create Create the signature
The signing method also adds validation data from external services (OCSP and time-stamping servers). Note that the OCSP responder and time-stamping server settings (in case of TS profile) should be configured before calling out the following method (see also \ref initialization and \ref parameters). By default, the RIA's time-stamping service https://eid-dd.ria.ee/ts is used.
Container holds the Signature object reference and there is no need cleanup memory.

\code{.cpp}
Signature *signature = doc->sign(signer);
\endcode



\paragraph validatesig 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:
\code{.cpp}
    signature->validate();
\endcode
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 \ref validate about more information for validating existing signatures and signature containers.



\paragraph savesig Save container changes
After the signature has been added and validated, container changes should be saved (\ref containeropen):
\code{.cpp}
    doc->save();
\endcode



\subsection websigning 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:
\code{.cpp}
Signature *signature = doc->prepareSignature(signer);
\endcode

2. In Signature class, get the hash to be signed in browser:
\code{.cpp}
std::vector<unsigned char> dataToSign = signature->dataToSign();
std::vector<unsigned char> signatureMethod = signature->signatureMethod();
std::string id = signature->id();
\endcode
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 <a href="https://github.com/open-eid/hwcrypto.js">hwcrypto.js library</a>)

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.
\code{.cpp}
std::vector<unsigned char> signatureValue = ...;
signature->setSignatureValue(signatureValue);
\endcode

5. Add time-stamp and OCSP data to Signature object, according to the signature's profile (see also section \ref API-sign-profile for more information):
\code{.cpp}
signature->extendSignatureProfile(signer);
\endcode

6. Write the document to output, as specified in section \ref containeropen


\subsection containeropen Reading and writing DigiDoc documents
In order to read an existing DigiDoc file from the file system, do as follows:
\code{.cpp}
    auto doc = digidoc::Container::openPtr("<input-file's-path>");
\endcode
The method above reads in the DigiDoc file from the specified location in file system and creates the respective Container object representing the document's data. The file's structure is also validated during its parsing according to the corresponding standards.

Write a DigiDoc file (represented with a Container object) to file system with the following method:
\code{.cpp}
    digidoc::Container::save("<output-file's-path>");
\endcode

\note ASiC-S containers with TimeStampToken signatures can be saved. Saving a read-only format or an unsupported ASiC-S signature variant throws a digidoc::Exception.

\subsection validate 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).



\subsubsection main-method 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:
\code{.cpp}
void digidoc::Signature::validate();
\endcode
If an exception is thrown from the validation method then the signature can be either <b>INVALID</b> or <b>VALID WITH WARNINGS</b>; 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:
\code{.cpp}
std::vector<digidoc::Exception> digidoc::Exception::causes();
\endcode

\subsubsection additional 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.


\subsubsection validation-status 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. <b>Returning a validation result of a single signature:</b><br>
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. <b>Returning a validation result of the whole DigiDoc container:</b><br>
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.

\note The user of the library has to determine the validation status according to the error code returned by the library's validation method.
<table>
<tr>
  <th>Priority</th>
  <th>Status</th>
  <th>Error code</th>
  <th>Description</th>
</tr>
<tr>
  <td>1</td>
  <td>INDETERMINATE/UNKNOWN</td>
  <td><b>10</b> CertificateIssuerMissing (signer's certificate is unknown)<br/>
    <b>6</b> CertificateUnknown (OCSP responder certificate is unknown)</td>
  <td>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 available in TSL"<br/>

- Sample file: unknown_CA_TS.asice (BDOC 2.1, time-stamp profile)
- Sample file: unknown_CA_TM.asice (BDOC 2.1, time-mark profile)</td>
</tr>
<tr>
  <td>2</td>
  <td>INVALID</td>
  <td>All errors except of the ones that are regarded as warnings by the library's user.</td>
  <td>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.</td>
</tr>
<tr>
  <td>3</td>
  <td>VALID WITH WARNINGS</td>
  <td>See the next section.</td>
  <td>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.</td>
</tr>
<tr>
  <td>4</td>
  <td>VALID</td>
  <td>N/A</td>
  <td>Validation process returns no errors. The signature is legally valid.</td>
</tr>
</table>
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:
\code{.cpp}
    open(int argc, char* argv[]); //utility program's command "open"
\endcode

\paragraph validatewarnings 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.

<b>Table 1. Validation error codes recommended to be handled as VALID WITH WARNINGS</b>

<table>
<tr>
  <th>Error code</th>
  <th>Related DigiDoc file format</th>
  <th>Description</th>
</tr>
<tr>
  <td><b>12</b> RefereneceDigest Weak<br>
    <b>13</b> SignatureDigestWeak</td>
  <td>BDOC 2.1 / ASiC</td>
  <td>Weaker digest method (SHA-1) has been used than recommended when calculating either &lt;Reference&gt; or &lt;Signature&gt; element's digest value.

  Suggested warning message (also displayed in DigiDoc desktop application):
"The current DigiDoc container uses weaker encryption method than officially accepted in Estonia."

- Sample file: weak-sha1-warning-TS.asice (time-stamp profile)
- Sample file: weak-sha1-warning-TM.bdoc (time-mark profile)</td>
</tr>
<tr>
  <td><b>16</b> ProducedATLateWarning</td>
  <td>BDOC 2.1 TS / ASiC</td>
  <td>The difference between the time-stamp issuance time (\ref RFC3161 "RFC 3161 TSTInfo.genTime") and the OCSP response's issuance time (producedAt value) exceeds 15 minutes but is less than 24 hours.

  Suggested warning message: "Time-stamp and OCSP issuance time difference is over 15 minutes."

- Sample file: TS_OCPS_difference_exceeds_15min.asice</td>
</tr>
<tr>
  <td><b>14</b> DataFileNameSpaceWarning</td>
  <td>DDOC 1.0<br>
DDOC 1.1<br>
DDOC 1.2<br>
DDOC 1.3</td>
  <td>&lt;DataFile&gt; 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</td>
</tr>
<tr>
  <td><b>15</b> IssuerNameSpace Warning</td>
  <td>DDOC 1.1<br>
DDOC 1.2<br>
DDOC 1.3</td>
  <td>&lt;IssuerSerial&gt;&lt;X509IssuerName&gt; and/or &lt;IssuerSerial&gt;&lt;X509SerialNumber&gt; 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</td>
</tr>
<tr>
  <td>N/A (Separate error code has not been determined.</td>
  <td>DDOC 1.0<br>
DDOC 1.1<br>
DDOC 1.2</td>
  <td>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
</td>
</tr>
</table>

\subsubsection validation-info	Additional information about validation
\paragraph validation-overview 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 &lt;Reference&gt; 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 &lt;SignedInfo&gt; element block;
4. case of time-stamp corresponds to the signature value (by comparing the digest value of &lt;SignatureValue&gt; 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 &lt;SignatureValue&gt; 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 \ref TSL-overview "TSL overview", \ref TSL "TSL standard" and \ref CA-settings "Configuring TSL settings".

For formats validated through SiVa, archive time-stamp information returned by the service is available through digidoc::Signature::ArchiveTimeStamps in the same way as locally validated archive time-stamps.


\subsection extend-validity Extending container validity
Since version 4.5.0, digidoc::Container::extendContainerValidity provides the high-level workflow for extending the validity evidence of a container. The method sets the required signer profile automatically and uses the following strategy:
- eligible ASiC-E LT-level signatures are extended in place with archive time-stamps;
- an ASiC-S TimeStampToken is extended in place with an ASiC archive manifest and a new time-stamp token;
- when in-place extension is unsuitable, the original container is embedded as the data file of a new timestamped ASiC-S container.

Only signatures with an Estonian signing certificate are considered for in-place extension, and e-seal signatures are skipped. A container with no applicable Estonian signatures, or with only T-level signatures lacking OCSP validation data, cannot be extended by this workflow.

\code{.cpp}
auto doc = digidoc::Container::openPtr("signed-document.asice");
digidoc::Signer *signer = ...;
std::size_t extendedCount = 0;

if(auto wrapped = digidoc::Container::extendContainerValidity(*doc, signer, extendedCount))
    doc = std::move(wrapped); // original container was wrapped in a new ASiC-S container
// Otherwise doc was extended in place and extendedCount contains the number
// of signatures that received new validity evidence.
doc->save();
\endcode

The returned unique pointer is empty when extension was performed in place. It contains the new ASiC-S container when wrapping was necessary; in that case extendedCount is zero. The caller must save the modified or newly returned container.

The generated language bindings expose the same workflow with language-specific return values:
- C#: Container.extendContainerValidity(doc, signer, out ulong extendedCount) returns the wrapping container, or null for an in-place extension.
- Python: Container.extendContainerValidity(doc, signer) returns a tuple (wrapping_container_or_None, extended_count).
- Java: Container.extendContainerValidity(doc, signer) returns the wrapping container, or null for an in-place extension; the count is not exposed.

In every binding, replace the original container with the returned container when the return value is not null/None, then save the resulting container. A null/None result means the original object was modified in place.


\subsection extracting 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:
\code{.cpp}
void digidoc::DataFile::saveAs(std::ostream &os) const;
\endcode

2.	The file can be written to file system with the following method:
\code{.cpp}
void digidoc::DataFile::saveAs(const std::string &path) const;
\endcode

List of all the document’s data files can be retrieved with the following method:
\code{.cpp}
std::vector<digidoc::DataFile *> digidoc::Container::dataFiles() const;
\endcode

For example, read in a DigiDoc document and write its data files to file system as follows:
\code{.cpp}
auto doc = digidoc::Container::openPtr("<input-file's-path>");
for(const digidoc::DataFile *file: doc->dataFiles()) {
	try {
		std::string dst = file->fileName();
		file->saveAs(dst);
	} catch(const digidoc::Exception &e) {
		printf("  Document %s extraction: FAILED\n", file->fileName().c_str());
	}
}
\endcode

\subsection removing Removing signatures and data files
In order to remove a signature from DigiDoc document, use the following method:
\code{.cpp}
void digidoc::Container::removeSignature(unsigned int index);
\endcode

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:
\code{.cpp}
void digidoc::Container::removeDataFile(unsigned int index);
\endcode

The index parameters of the methods above are the signature and data file sequence numbers in the container, starting from zero.
\note Directly modifying the data file or initial signature of an existing ASiC-S container is not supported. Adding archive-manifest time-stamp layers through digidoc::Container::extendContainerValidity is supported.


\subsection shutting-down Shutting down the library
After finishing work with Libdigidocpp, then the last task is to shut down the library:
\code{.cpp}
digidoc::terminate();
\endcode

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.

\subsection exceptions 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:
\code{.cpp}
try {

// code implementation

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

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:
\code{.cpp}
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
}
\endcode


\section supported-tokens National and cross-border support

\subsection TSL-overview TSL list usage in Libdigidocpp
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 \ref TSL "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 <b>European Commission’s TSL list </b> 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 <b>all national TSL lists that are referred to in the LOTL (more than 30 countries). </b>

\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



\subsubsection TSL-init 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 \ref CA-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.

\note 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 \ref CA-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 &lt;NextUpdate&gt; 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.


\subsection	tokens 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
- SafeNet eToken 5110 with SK issued certificates for organizations











\section testing Interoperability testing
\subsection cross-usability DigiDoc framework cross-usability tests
Automated cross-usability tests of digitally signed and encrypted files are periodically carried out between different \ref DD-libs "DigiDoc software libraries":
- Cross-usability of ASiC-E 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 on the \ref digidoc-tool page).





\section implementation-notes 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 \ref BDOC "BDOC2.1:2013" but are used in Libdigidocpp library’s implementation (and also in other DigiDoc software libraries) of the file format.


\subsection signature-notes 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 &lt;SignaturePolicyIdentifier&gt; element is present (\ref BDOC "BDOC2.1:2013", chap. 5.2). The basic BDOC-TS profile is XAdES-BES as the &lt;SignaturePolicyIdentifier&gt; 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 (\ref BDOC "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 &lt;SignaturePolicyIdentifier&gt; 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 &lt;SignatureValue&gt; 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:
	\code{.cpp}
			TBSDocumentDigest ::= SEQUENCE {
				algorithm AlgorithmIdentifier,
				digest OCTET STRING
			}
	\endcode
	-	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.	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 &lt;ClaimedRole&gt; element in the signature, which contains the signer’s role and optionally the signer’s resolution. If the &lt;ClaimedRole&gt; 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.	XML namespace prefixes are used in case of all XML elements (e.g. "asic:", "ds:", "xades:").
10.	The data file’s MIME type that is used in case of Libdigidocpp’s utility program is always "application/octet-stream" for testing purposes.
11.	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.
12. signatures*.xml file's XML structure validation is done on the basis of XAdES XML Schema (\ref XAdES), however, there are additional checks to determine any unsupported elements that are allowed by the XAdES specification. The unsupported elements are CounterSignature, AttributeCertificateRefs, AttributeRevocationRefs, RefsOnlyTimeStamp, AttrAuthoritiesCertValues, AttributeRevocationValues, CommitmentTypeIndicationType, AllDataObjectsTimeStamp, IndividualDataObjectsTimeStampType.
13. Special characters in URI attribute values are handled according to \ref RFC3986 "RFC 3986" (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.
14. When validating a BDOC-TS document then the difference between the OCSP validity confirmation's production time (producedAt field) and the time-stamp token's creation time (\ref RFC3161 "RFC 3161 TSTInfo.genTime") is checked. An exception is thrown if the OCSP confirmation's time is earlier than the time-stamp's time. If the OCSP confirmation's time is later than the time-stamp's time by more than 15 minutes then a warning is returned. If the difference is more than 24 hours then an exception is thrown.
15. During 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.

\subsection cert-notes 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:
	-	\ref nat-cert "ETSI EN 319 412-2 V2.4.1": "Certificate Profiles; Part 2: Certificate profile for certificates issued to natural persons"; chap. 5.4.3;
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 time in TSA response or case time-mark profile producedAt field in OCSP response).
	
\subsection container-notes Container related notes
1.	ASiC-E files are created with .asice or .sce file extension.
2.	Signatures are stored in META-INF/signatures*.xml files where ‘*’ is a sequence number, counting is started from zero.
3.	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.
4.	All data files in the container must be signed. All signatures in the container must sign all of the data files.
5.	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.
6.	The ZIP container’s comment field contains application name 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.
7.	"mimetype" file is not compressed in the ASiC-E file’s ZIP container as the results of ASiC plug-tests event shows that this solution is most widely used.
8.	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.


*/