diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index 22edd9e8c..5f9399d5e 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -1,3 +1,5 @@ +# Release Notes {#release_notes} + Libdigidocpp library [4.5.0](https://github.com/open-eid/libdigidocpp/releases/tag/v4.5.0) release notes -------------------------------------- - Add `Container::extendContainerValidity` for adding archive timestamps to eligible ASiC-E and ASiC-S/TST containers, or wrapping a container in timestamped ASiC-S when in-place extension is unavailable @@ -331,7 +333,7 @@ Libdigidocpp library [3.12.3](https://github.com/open-eid/libdigidocpp/releases/ -Libdigidocpp library 3.12.2 release notes +Libdigidocpp library [3.12.2](https://github.com/open-eid/libdigidocpp/releases/tag/v3.12.2) release notes -------------------------------------- Changes compared to ver 3.12.1 - Fix issues found by coverity @@ -341,7 +343,7 @@ Changes compared to ver 3.12.1 -Libdigidocpp library 3.12.1 release notes +Libdigidocpp library [3.12.1](https://github.com/open-eid/libdigidocpp/releases/tag/v3.12.1) release notes -------------------------------------- Changes compared to ver 3.12.0 - Added Container::prepareWebSignature for C# bindings @@ -351,7 +353,7 @@ Changes compared to ver 3.12.0 -Libdigidocpp library 3.12.0 release notes +Libdigidocpp library [3.12.0](https://github.com/open-eid/libdigidocpp/releases/tag/v3.12.0) release notes -------------------------------------- Changes compared to ver 3.11.1 @@ -372,7 +374,7 @@ List of known issues: https://github.com/open-eid/libdigidocpp/wiki/Known-issues -Libdigidocpp library 3.11.1 release notes +Libdigidocpp library [3.11.1](https://github.com/open-eid/libdigidocpp/releases/tag/v3.11.1) release notes -------------------------------------- Changes compared to ver 3.11.0 @@ -383,7 +385,7 @@ List of known issues: https://github.com/open-eid/libdigidocpp/wiki/Known-issues -Libdigidocpp library 3.11.0 release notes +Libdigidocpp library [3.11.0](https://github.com/open-eid/libdigidocpp/releases/tag/v3.11.0) release notes -------------------------------------- Changes compared to ver 3.10.3 @@ -402,7 +404,7 @@ Changes compared to ver 3.10.3 -Libdigidocpp library 3.10.3 release notes +Libdigidocpp library [3.10.3](https://github.com/open-eid/libdigidocpp/releases/tag/v3.10.3-beta) release notes -------------------------------------- Changes compared to ver 3.10.0 @@ -414,13 +416,13 @@ Changes compared to ver 3.10.0 -Libdigidocpp library 3.10.0 release notes +Libdigidocpp library [3.10.0](https://github.com/open-eid/libdigidocpp/releases/tag/v3.10.0) release notes -------------------------------------- Changes compared to ver 3.9 - Changed the default BDOC signature profile to BDOC-TS (ASiC-E LT signature with time-stamp) for new signatures. To create a BDOC-TM (LT_TM, i.e. time-mark) signature, specify the "time-mark" profile value in Container::sign(Signer *signer, const string &profile) method call. - Fixed time zone usage when validating signer certificate validity period's starting time. Previously, "Not yet valid" error message was displayed even if the certificate was actually already valid. -- Improved BDOC signatures*.xml file's XML structure validation. Transforms XML element is now allowed to enhance interoperability. +- Improved BDOC signatures\*.xml file's XML structure validation. Transforms XML element is now allowed to enhance interoperability. - Improved TSL functionality - In case of BDOC format, checking the trustworthiness of trust services (CA, OCSP, time-stamping services) is now possible only by using TSL lists. Previously used certificate store functionality is no longer supported. - Removed country-specific filtering of the national TSLs that are referenced in the European Commission's central TSL list. @@ -432,7 +434,7 @@ Changes compared to ver 3.9 - Improved TSL loading when proxy is used, proxy settings are ignored in case of HTTPS connections. - Changed the XmlConf class to deprecated, use XmlConfV2 instead. - Changed the OCSP responder URL for EID-SK 2011 certificates, http://ocsp.sk.ee is now used. -- Fixed error message text that appears when data file's mime-type in BDOC manifest.xml does not conform with mime-type value in signatures*.xml file. Previously, the displayed mime-type values were interchanged between the signatures*.xml and manifest.xml files. +- Fixed error message text that appears when data file's mime-type in BDOC manifest.xml does not conform with mime-type value in signatures\*.xml file. Previously, the displayed mime-type values were interchanged between the signatures\*.xml and manifest.xml files. - The library's release notes is now also copied to the library's documentation: http://open-eid.github.io/libdigidocpp/manual.html#releasenotes - Development of the software can now be monitored in GitHub environment: https://github.com/open-eid/libdigidocpp @@ -457,10 +459,10 @@ Changes compared to ver 3.8 - Added class XmlConfV2 that should be used instead of XmlConf class if it is needed to configure time-stamp and TSL related configuration properties. - Added Xalan library for processing TSL files. - Added support for adding OCSP confirmation to signature if the signer's certificate is issued by "VRK CA for Qualified Certificates - G2" or "VRK Gov. CA for Citizen Qualified Certificates - G2". -- Improved BDOC document's validation, it is now checked that the data file mime-type value in manifest.xml file and the respective value in signatures*.xml file in element are the same. +- Improved BDOC document's validation, it is now checked that the data file mime-type value in manifest.xml file and the respective value in signatures\*.xml file in \\ element are the same. - Added "--mime=" parameter to digidoc-tool utility program's "create" command. The parameter can be used along with "--file=" parameter to set the mime-type value of a data file. If not set then the default value "application/octet-stream" is used. - Improved BDOC document's validation, added check for weak hash algorithm (SHA-1) usage in case of ECDSA signatures. -- Improved BDOC signatures*.xml file's XML structure validation. It is now additionally checked that unsupported elements CounterSignature, CompleteCertificateRefs, CompleteRevocationRefs, AttributeCertificateRefs, AttributeRevocationRefs, SigAndRefsTimeStamp, RefsOnlyTimeStamp, AttrAuthoritiesCertValues, AttributeRevocationValues, CommitmentTypeIndicationType, AllDataObjectsTimeStamp, IndividualDataObjectsTimeStampType would not exist in the file. +- Improved BDOC signatures\*.xml file's XML structure validation. It is now additionally checked that unsupported elements CounterSignature, CompleteCertificateRefs, CompleteRevocationRefs, AttributeCertificateRefs, AttributeRevocationRefs, SigAndRefsTimeStamp, RefsOnlyTimeStamp, AttrAuthoritiesCertValues, AttributeRevocationValues, CommitmentTypeIndicationType, AllDataObjectsTimeStamp, IndividualDataObjectsTimeStampType would not exist in the file. - Improved processing of special characters in URI attribute values according to RFC3986. Special characters in URI are percent-encoded, except of unreserved characters and delimiters. Both percent-encoded and non-percent-encoded characters are supported during signature's validation. Note that as a result, the files that contain special characters in URI values and have been created with v3.9 might not be compatible with v3.8 of the library. - Fixed problem that caused erroneous signatures if the data file's name contained colon character. - Fixed digidoc-tool utility program "extract" command's "--extractAll" parameter functionality. Now, if the parameter is present but there is no extraction directory specified then the files are extracted to the working directory. diff --git a/doc/digidoc-tool.md b/doc/digidoc-tool.md new file mode 100644 index 000000000..77e58bfa5 --- /dev/null +++ b/doc/digidoc-tool.md @@ -0,0 +1,446 @@ +# digidoc-tool {#digidoc-tool} + +The command line utility program digidoc-tool which is included in the Libdigidocpp distribution can be used to test the library or simply use it directly to handle digitally signed documents. + +\note The utility program is intended for testing and presentation of sample implementation of the library’s API. The interface of the utility program is not fixed and its long-term stability is not guaranteed. + +The general format for executing the program is: +``` +> digidoc-tool [command] [options] [input/output file] +``` + +Available optional options on all commands: + + + + +
\-\-nocolor +Disable terminal colors
\-\-loglevel=[0,1,2,3,4] +Log level: 0 - none, 1 - error, 2 - warning, 3 - info, 4 - debug
\-\-logfile= +File to log, empty to console
+ +## Creating and signing a document (local signing) {#Creating} + +Command "create" can be used to create a new DigiDoc container, add data files, optionally some meta-info about the signer and sign the document. The output extension selects ASiC-E (.asice or .sce) or ASiC-S (.asics or .scs). ASiC-S creation requires exactly one data file and the TimeStampToken signature profile. +General form of the command is: +``` +> digidoc-tool create --file= +``` + +Available options: + + + + +
\-\-file= Required +Data file(s) to be signed. The option can occur multiple times. + +\warning It is recommended not to use special characters in the data file’s name, i.e. it is suggested to only use the characters that are categorized as "unreserved" according to \ref RFC3986 "RFC 3986".
\-\-mime= Optional +Specifies the data file's mime-type value. When used then must be written right after the "--file" parameter. If left unspecified then the default mime-type value "application/octet-stream" is used. + +\warning Data file’s mime-type value must be formatted as specified in \ref RFC2045 "RFC 2045", section 5.1, i.e. the "type" and "subtype" values must be separated with a forward slash character.
\-\-dontsign Optional +Don't sign the newly created container.
+ +Additional options for the "create" command are the same as for "sign" command (see \ref Adding). + +Sample commands for creating and signing DigiDoc files: + +``` +Sample: creating an ASiC-S container with one data file and an RFC 3161 time-stamp token +> digidoc-tool create --file=file1.txt --mime=text/plain --profile=TimeStampToken timestamped-document.asics + +The profile alias time-stamp-token is also accepted. +``` + +``` +Sample: creating new ASiC-E file, adding multiple data files and signing via PKCS#11 driver +> digidoc-tool create --file=file1.txt --mime=text/plain --file=file2.pdf --mime=application/pdf --country=Estonia +--state=Harjumaa --city=Tallinn --postalCode=12345 --pkcs11 demo-container.asice + +Input: + --file=file1.txt - a data file to be added to container + --mime=text/plain - data file 'file1.txt' mime-type + --file=file2.pdf - a data file to be added to container + --mime=application/pdf - data file 'file2.pdf' mime-type + --country=Estonia - country where the signature is created + --state=Harjumaa - state where the signature is created + --city=Tallinn - city where the signature is created + --postalCode=12345 - postal code of the signature creation location + --pkcs11 - signing is done via PKCS#11 module + demo-container.asice - container to be created +``` + +``` +Sample: creating new ASiC-E file on Windows, adding data file and signing via CNG API +> digidoc-tool create --file=file1.txt --cng demo-container.asice + +Input: + --file=file1.txt - a data file to be added to container + --cng - CNG API is used for signing + demo-container.asice - container to be created +``` + +``` +Sample: creating new ASiC-E file on Windows, adding data file and signing via CNG API, dialog windows for certificate selection and PIN insertion are not displayed +> digidoc-tool create --file=file1.txt --cng --selectFirst --pin=01497 demo-container.asice + +Input: + --file=file1.txt - a data file to be added to container + --cng - CNG API is used for signing + --selectFirst - the first signing certificate in store is used for signing + --pin=01497 - PIN code (PIN2 in case of Estonian ID cards) + demo-container.asice - container to be created +``` + +## Creating and signing multiple documents {#createBatch} +Command "createBatch" Takes folder as argument folder/content/to/sign and sign them separate containers. +For additional options look sign command. + +## Add additional files to container {#add} +Command "add" for adding additional files to existing unsigned container. +Available options are --file and --mime look "create" command for info. + +## Creating and signing a document (external signing, e.g. in browser) {#websign} + +Command "websign" can be used to create a new DigiDoc container, add data files, optionally some meta-info about the signer and sign the document. Documents can be created only in ASiC-E format. +External signing use case may be used when signing is done in web applications, the communication with the signer's token and signing the hash is done via a web browser's signing module (plug-in or extension). See also https://web-eid.eu for implementing signing in browser environment. + +External signing process with websign command is as follows: +1. After executing the websign command, the utility program outputs the value of hash to be signed (in HEX) to console and waits until user enters the respective signature value +2. Send the hash to be signed to the signing token (e.g. by using the web signing demo page at https://open-eid.github.io/hwcrypto.js/sign.html) +3. Conduct signing, enter PIN2, retireve the signed hash (signature value) from the signing token +4. Enter the signature value (also in HEX) to the console +5. Utility program continues with signing process and outputs the signed container + +General form of the command is: +``` +> digidoc-tool websign --cert= --file= +``` + +Available options: + + + + +
\-\-cert= Required +Signer's certificate, in PEM format.
\-\-file= Required +Data file(s) to be signed. The option can occur multiple times.
\-\-mime= Optional +Specifies the data file's mime-type value. When used then must be written right after the "--file" parameter. If left unspecified then the default mime-type value "application/octet-stream" is used.
+ +Additional options for the "websign" command are the same as for "sign" command (see \ref Adding). + +Sample command for creating and external signing of ASiC-E files: + +``` +Sample: creating new ASiC-E file, specifying signers certificate, adding data files and other meta-data and calculating the RSA signature value in browser +> digidoc-tool websign --cert=signer.cer --file=file1.txt --file=file2.pdf --country=Estonia --state=Harjumaa --city=Tallinn --postalCode=12345 --profile=time-stamp demo-container.asice + +Input: + --cert=signer.cer - signers certificate + --file=file1.txt - a data file to be added to container + --file=file2.txt - a data file to be added to container + --profile=time-stamp - profile of the signature + --country=Estonia - country where the signature is created + --state=Harjumaa - state where the signature is created + --city=Tallinn - city where the signature is created + --postalCode=12345 - postal code of the signature creation location + demo-container.asice - container to be created +``` + + +## Opening document, validating signatures and extracting data files {#Opening} +Command "open" reads an existing document, prints its contents and validates its signatures. The --extractAll option extracts data files to disk. Supported ASiC-E, ASiC-S and legacy BDOC 2.1 variants are handled locally. PDF, legacy DDOC and ASiC containers with CAdES signatures are sent to the SiVa Online Service for validation; --offline disables that fallback, so those service-backed formats cannot be opened offline. BDOC 1.0 is not supported. +General form of the command is: +``` +> digidoc-tool open +``` + +Available options: + + + + + +
\-\-extractAll Optional +If set, then all of the input container’s data files are extracted and written to disk without validating signatures. If an output directory is not specified with the value of this parameter then the extracted files are written to the current working directory. + +On Windows, reserved device names are prefixed with an underscore (CON becomes _CON). Characters that are invalid in Windows filenames, control characters, and trailing spaces or dots are replaced with underscores. Extraction fails rather than overwriting an existing output file.
--validateOnExtract Optional +If set, then validates container before extracting files.
\-\-offline Optional +open container offline (eg. Don't send to SiVa)
\-\-warnings= + +(ignore, warning, error) Optional +Enables to choose the displaying of validation warnings (if present) of the file being opened. Can be used to test the warnings system of the utility program (see also "Validation status VALID WITH WARNINGS"). +The options include: +- warning – the default value used. The minor technical errors that are considered as warnings, are printed out as warnings. +- error – the errors that are otherwise considered as warnings (by the utility program), are printed out as errors. +- ignore – the errors that are otherwise considered as warnings (by the utility program), are not printed out. If there are any other errors present then these are treated as usual.
+ +Output of the default command contains the following data of the container: +``` + Container file: + Container type: + Documents (): + Document (): ( bytes) + Signatures (): + Signature (): + Validation: + EPES policy: urn:oid: + SPUri: + Signature method: + Signing time: + Signing cert: + Signed by: + Produced At: