v3.11.0 and 3.10.3 rel notes updated, documentation updates, CSharp readme translated to English

Author: metsma

README.md

@@ -36,12 +36,13 @@
 6. Execute
 
         /usr/local/bin/digidoc-tool
-        
+
 ### OSX
 
 1. Install dependencies from
-   * [XCode](https://itunes.apple.com/en/app/xcode/id497799835?mt=12)
-   * [http://www.cmake.org](http://www.cmake.org)
+	* [XCode](https://itunes.apple.com/en/app/xcode/id497799835?mt=12)
+	* [http://www.cmake.org](http://www.cmake.org)
+
 2. Fetch the source
 
         git clone --recursive https://github.com/open-eid/libdigidocpp
@@ -72,13 +73,15 @@
 ### Windows
 
 1. Install dependencies from
-    * [Visual Studio Express 2013 for Windows Desktop](http://www.visualstudio.com/en-us/products/visual-studio-express-vs.aspx)
+	* [Visual Studio Express 2013 for Windows Desktop](http://www.visualstudio.com/en-us/products/visual-studio-express-vs.aspx)
 	* [http://www.cmake.org](http://www.cmake.org)
 	* [Xerces-c](http://mirror.cogentco.com/pub/apache//xerces/c/3/sources/xerces-c-3.1.1.zip)
 	* [Xerces-c MSVC2012 Project files](https://issues.apache.org/jira/secure/attachment/12548623/xerces_vc11proj.zip)
 	* [XML-Security-C](http://www.apache.org/dyn/closer.cgi?path=/santuario/c-library/xml-security-c-1.7.2.tar.gz)
 	* [OpenSSL Win32 binaries](https://slproweb.com/products/Win32OpenSSL.html) or [OpenSSL source](https://www.openssl.org/source/)
 	* [ZLib source](http://zlib.net/zlib128.zip)
+	* [swigwin-3.0.5.zip](http://swig.org/download.html) - Optional, for C# bindings
+
 2. Fetch the source
 
         git clone --recursive https://github.com/open-eid/libdigidocpp
@@ -90,6 +93,14 @@
         cd build
         cmake ..
 
+   Optional CMake parameters:
+
+       -DSWIG_EXECUTABLE=C:/swigwin-3.0.5/swig.exe
+
+   After running the cmake build, digidoc_csharp.dll along with the C# source files will be created, more info at
+   [README.md](https://github.com/open-eid/libdigidocpp/blob/master/examples/DigiDocCSharp/README.md).
+
+
 4. Build
 
         make

RELEASE-NOTES.txt

@@ -1,22 +1,32 @@
 Libdigidocpp library 3.11.0 release notes
 --------------------------------------
 Changes compared to ver 3.10.3
-- Improve EC signature size calculation
-- Improve HTTP traffic usage by using gzip Content-Encoding
-- TimeStampArchive support
-- Option to specify signature digest other than standard digest
-- Resolve relative PKCS11 config parameter to library path, instead current working directory
 
+- 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.
+
+List of known issues: https://github.com/open-eid/libdigidocpp/wiki/Known-issues
 
 
 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
-- On signature validation at least one DataFile should be signed
-- Disable OCSP time slot check – local computer time against OCSP server time
+- 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.
 
 
 

examples/DigiDocCSharp/README.md

@@ -1,27 +1,27 @@
 ## C-SHARP
-Kasutab [http://swig.org/](http://swig.org/) vahendeid bindingu genereerimise jaoks.
+Uses [http://swig.org/](http://swig.org/) tools for generating bindings. 
 
-Alla tuleb laadida [swigwin-3.0.5.zip](http://swig.org/download.html)
+## Setting up the sample C# application
 
-Teegi ehitamise juhise leiab [https://github.com/open-eid/libdigidocpp/blob/master/README.md](README.md) kus tuleb lisaks määrata cmake build parameeter
+For compiling and running the DigiDocCSharp sample C# project, do as follows:
 
-    -DSWIG_EXECUTABLE=C:/swigwin-3.0.5/swig.exe'
+1. Install the "Eesti_ID_kaart-CPP-teek-arendajale" (Estonian ID-card Libdigidocpp library for developers) package, version 3.10.3-beta or higher. The installation packages are available from https://github.com/open-eid/libdigidocpp/releases
+2. Open the C# sample project from source\examples\DigiDocCSharp folder located in the installation directory
+3. Add the C# source files files from include\digidocpp_csharp folder to the digidoc folder of the opened project (in Solution Explorer view, right click on the digidoc folder, choose Add->Existing item)
+4. Build the solution, DigiDocCSharp.exe executable is created
+4. Libdigidocpp library's binaries (in the x64 or x86 folder of the "Eesti_ID_kaart-CPP-teek-arendajale" package's installation directory) need to be accessible for running the DigiDocCSharp executable. You can either copy the DigiDocCSharp.exe to the x64 or x86 folder, depending on the platform or set the working directory of the project accordingly or add the binaries' folder to PATH variable.
+5. Run the DigiDocCSharp.exe sample program with the commands described in the next section
 
-Millega ehitatakse digidoc_csharp.dll ja PInvoke jaoks failid swig/csharp kataloogi, mis tuleb importida C# projekti.
-
-Binaarsel kujul olev dll on sadaval
-[https://github.com/open-eid/libdigidocpp/releases/tag/v3.10.3-beta](installi pakis)
+## Commands of the sample application Program.cs
+* DigiDocCSharp.exe -version
+* DigiDocCSharp.exe -help
+* DigiDocCSharp.exe -verify test.bdoc
+* DigiDocCSharp.exe -sign text.txt test.bdoc
+* DigiDocCSharp.exe -extract=0 test.bdoc
 
 ## API
 * [digidoc.initialize()](http://open-eid.github.io/libdigidocpp/namespacedigidoc.html#ada31d19121d7a6d98b04267f3ed8cc8f)
 * [Container](http://open-eid.github.io/libdigidocpp/classdigidoc_1_1Container.html)
 * [DataFile](http://open-eid.github.io/libdigidocpp/classdigidoc_1_1DataFile.html)
 * [Signature](http://open-eid.github.io/libdigidocpp/classdigidoc_1_1Signature.html)
 * [digidoc.terminate()](http://open-eid.github.io/libdigidocpp/namespacedigidoc.html#a121f0363627f62f3972ac4b445986598)
-
-## Näidisrakenduse Program.cs käsud
-* DigiDocCSharp.exe -version
-* DigiDocCSharp.exe -help
-* DigiDocCSharp.exe -verify test.bdoc
-* DigiDocCSharp.exe -sign text.txt test.bdoc
-* DigiDocCSharp.exe -extract=0 test.bdoc

src/index.dox

@@ -240,6 +240,9 @@ The information is provided with a special OCSP confirmation (also referred to a
 </td></tr><tr><td>
 time-stamp	</td><td>Mechanism used for adding certificate validity and signing time information with the signature. The certificate validity information is added to the signature with an OCSP confirmation; the signing time information is added with a time-stamp token retrieved form a time-stamping service. In this case, signature creation time is the issuance time (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).
 </td></tr>
+tr><td>
+archive time-stamp	</td><td>Mechanism used for providing long term validity of a XAdES signature. The signature and validation data values are time-stamped. The respective signature profile is TSA profile (supported only in case of BDOC 2.1 document format).
+</td></tr>
 <tr><td>
 TSA	</td><td>Time-Stamping Authority. Time-stamping service provider.
 </td></tr>
@@ -289,6 +292,8 @@ The following table gives overview of functional features that are supported wit
 <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 OCSP confirmation; the signing time information is added with a time-stamp token (see also \ref RFC6960 "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 \ref BDOC "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 \ref BDOC "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.
 </td>
 </tr>
 <tr><td>Trust anchors</td>
@@ -667,8 +672,35 @@ By default, the trusted certificates' information is obtained from European Comm
   <td>proxy.pass</td>
   <td>Specifies the proxy password.</td>
 </tr>
+<tr>
+  <td>proxy.forceSSL</td>
+  <td>May be used to enable downloading TSL-s over proxy in case of HTTPS connections. </td>
+</tr>
+<tr>
+  <td>proxy.tunnelSSL</td>
+  <td>May be used to enable downloading TSL-s over proxy in case of HTTPS connections. </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, supported only with BDOC 2.1 format. By default, the SHA-256 algorithm (with URI http://www.w3.org/2001/04/xmlenc#sha256) is used (except of SHA-224 in case of older generation of Estonian ID-cards)</td>
+</tr>
+<tr>
+  <td>signer.digestUri</td>
+  <td>Specifies the digest algorithm that is used for calculating all the hash values in the signature, supported only with BDOC 2.1 format. By default, the SHA-256 algorithm is used</td>
+</tr>
 </table>
 
+
+
 \subsubsection ocspsigning-settings Settings for signing OCSP requests
 Whether you need to sign the OCSP requests sent to your OCSP responder or not depends on your responder. Some OCSP servers require that the OCSP request is signed. To sign the OCSP request, you need to obtain and specify the PKCS#12 token, which will be used for signing.
 
@@ -768,6 +800,11 @@ xsi:noNamespaceSchemaLocation="schema/conf.xsd">
 <ocsp issuer="TEST of ESTEID-SK 2011">http://www.openxades.org/cgi-bin/ocsp.cgi</ocsp>
 <ocsp issuer="TEST of KLASS3-SK 2010">http://www.openxades.org/cgi-bin/ocsp.cgi</ocsp>
 
+<!--Digest algorithm settings-->
+<!--<param name="signer.digestUri" lock="false">http://www.w3.org/2001/04/xmlenc#sha256</param>-->
+<!--<param name="signer.signatureDigestUri" lock="false">http://www.w3.org/2001/04/xmlenc#sha256</param>-->
+  
+
 </configuration>	
 \endcode
 
@@ -872,6 +909,10 @@ Signature production place and signer role are optional signed meta-data about t
     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 in case of BDOC documents and SHA-1 algorithm in case of DDOC 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.
+
 
 \paragraph API-sign-create Specify the signature profile and create the signature
 The supported signature profiles are (see also \ref Supported, under "Signature profiles"):
@@ -1462,7 +1503,11 @@ Signer’s role(s). The option can occur multiple times.
 --sha(1,224,
 256,384,512)	</td><td>Optional
 
-Used for testing purposes. Specifies the hash function that is used for calculating digest values. If not specified then SHA-256 is used by default.
+Used for testing purposes. Specifies the hash function that is used when calculating digest values, supported only in case of BDOC documents. If not specified then SHA-256 is used by default.
+</td></tr><tr><td>
+--sigsha(1,224,256,384,512)	</td><td>Optional
+
+Used for testing purposes. Specifies the hash function that is used for calculating the hash that is being signed, supported only in case of BDOC format. If not specified then SHA-256 is used by default.
 </td></tr>
 </table>