|
libdigidocpp 4.6.0
|
|
libdigidocpp 4.6.0
|
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.
The general format for executing the program is:
Available optional options on all commands:
| Option | Description |
|---|---|
| --nocolor | Disable terminal colors |
| --loglevel=[0,1,2,3,4] | Log level: 0 - none, 1 - error, 2 - warning, 3 - info, 4 - debug |
| --logfile= | File to log, empty to console |
Command "create" can be used to create a new DigiDoc container, add data files, optionally some meta-info about the signer and sign the document. The output extension selects ASiC-E (.asice or .sce) or ASiC-S (.asics or .scs). ASiC-S creation requires exactly one data file and the TimeStampToken signature profile. General form of the command is:
Available options:
| Option | Usage | Description |
|---|---|---|
| --file= | Required | Data file to be signed, can occur multiple times |
| --mime= | Optional | Mime-type of the preceding --file |
| --dontsign | Optional | Don't sign the newly created container |
--mime= must be written right after the --file parameter it applies to. If left unspecified then the default mime-type value "application/octet-stream" is used.
Additional options for the "create" command are the same as for "sign" command (see Adding signatures).
Sample commands for creating and signing DigiDoc files:
Command "createBatch" Takes folder as argument folder/content/to/sign and sign them separate containers. For additional options look sign command.
Command "add" for adding additional files to existing unsigned container. Available options are --file and --mime look "create" command for info.
Command "websign" can be used to create a new DigiDoc container, add data files, optionally some meta-info about the signer and sign the document. Documents can be created only in ASiC-E format. External signing use case may be used when signing is done in web applications, the communication with the signer's token and signing the hash is done via a web browser's signing module (plug-in or extension). See also https://web-eid.eu for implementing signing in browser environment.
External signing process with websign command is as follows:
General form of the command is:
Available options:
| Option | Usage | Description |
|---|---|---|
| --cert= | Required | Signer's certificate, in PEM format |
| --file= | Required | Data file to be signed, can occur multiple times |
| --mime= | Optional | Mime-type of the preceding --file |
--mime= must be written right after the --file parameter it applies to. If left unspecified then the default mime-type value "application/octet-stream" is used.
Additional options for the "websign" command are the same as for "sign" command (see Adding signatures).
Sample command for creating and external signing of ASiC-E files:
Command "open" reads an existing document, prints its contents and validates its signatures. The --extractAll option extracts data files to disk. Supported ASiC-E, ASiC-S and legacy BDOC 2.1 variants are handled locally. PDF, legacy DDOC and ASiC containers with CAdES signatures are sent to the SiVa Online Service for validation; --offline disables that fallback, so those service-backed formats cannot be opened offline. An ASiC-S time-stamp container that encloses a DDoc file is opened together with the DDoc, whose data files and signatures are listed after validation by SiVa; with --offline it is opened as a plain time-stamped container and only its time-stamp is validated. BDOC 1.0 is not supported. General form of the command is:
Available options:
| Option | Usage | Description |
|---|---|---|
| --extractAll | Optional | Extract data files without validating signatures |
| --validateOnExtract | Optional | Validate the container before extracting files |
| --offline | Optional | Open container offline (e.g. don't send to SiVa) |
| --warnings=(ignore,warning,error) | Optional | How validation warnings are displayed |
--extractAll writes all of the input container’s data files 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.
--warnings enables to choose the displaying of validation warnings (if present) of the file being opened. Can be used to test the warnings system of the utility program (see also "Validation status VALID WITH WARNINGS"). The options include:
Output of the default command contains the following data of the container:
Sample commands for validating signatures and extracting data files:
Command "sign" enables adding XAdES signatures to existing ASiC-E and legacy BDOC 2.1 containers. The same signing options are used by "create" to add the initial RFC 3161 TimeStampToken to a new ASiC-S container; an existing ASiC-S container cannot receive another ordinary signature.
| Option | Usage | Description |
|---|---|---|
| --pin= | Optional | PIN code, asked on the command line when omitted |
| --profile= | Optional | Signature profile, see the values below |
| --XAdESEN | Optional | Use XAdES EN profile |
| --city= | Optional | City where the signature is created |
| --street= | Optional | streetAddress of production place in XAdES EN profile |
| --state= | Optional | State or province where the signature is created |
| --postalCode= | Optional | Postal code of the place where the signature is created |
| --country= | Optional | Country of origin, ISO 3166 2-character code (e.g. EE) |
| --role= | Optional | Signer’s role, can occur multiple times |
| --sha(224,256,384,512) | Optional | Hash function for digest values (testing) |
| --sigsha(224,256,384,512) | Optional | Hash function for the signed hash (testing) |
| --sigpsssha(224,256,384,512) | Optional | Same as --sigsha* with --rsapss (testing) |
| --rsapkcs15 | Optional | Change RSA signature padding to PKCS1.5 |
| --rsapss | Optional | Change RSA signature padding to PSS |
| --tsurl= | Optional | Change TS URL |
| --tscert= | Optional | Pin the TSA TLS certificate, PEM file |
| --tsurlarchive= | Optional | Change archive (LTA) TS URL |
| --tscertarchive= | Optional | Pin the archive (LTA) TSA TLS certificate, PEM file |
| --userAgent= | Optional | Application info sent to the TSA or OCSP service |
| --dontValidate | Optional | Don't validate container on signature creation |
If PIN is not provided with --pin= and (the default) PKCS#11 module is used for signing then the utility program asks for the user to insert PIN code to command line during the program’s execution time.
--profile= possible values are:
--tsurl= and --tscert= set the time-stamping service for signature time-stamps and the initial ASiC-S TimeStampToken. --tsurlarchive= and --tscertarchive= set the service for archive time-stamps: the ArchiveTimeStamp of the TSA profile and the ASiC-S archive-manifest time-stamps. The archive URL is taken from --tsurlarchive=, then the ts.url.archive configuration parameter, then --tsurl= and ts.url (see Time-stamping service settings); the archive certificate from --tscertarchive=, then --tscert=. The certificate options pin the TLS certificate of the service connection; they do not affect time-stamp token validation.
The hash options are used for testing purposes. --sha* specifies the hash function that is used when calculating digest values, --sigsha* the hash function that is used for calculating the hash that is being signed, and --sigpsssha* does the same and uses RSA-PSS padding with RSA keys.
By default, reference digests use signer.digestUri and RSA signatures use signer.signatureDigestUri, both configured as SHA-256 by default. For ECDSA signatures, the default signature hash is selected by the EC key size: SHA-224 for 224-bit keys, SHA-256 for 256-bit keys, SHA-384 for 384-bit keys, and SHA-512 for other key sizes (including 521-bit keys).
ECDSA with SHA3-256, SHA3-384 and SHA3-512 can be selected through digidoc::Signer::setMethod() using the algorithm URI. The command-line hash switches listed above select SHA-2 algorithms only.
Options for specifying module used for accessing the signing token - possible alternatives are PKCS#11, CryptoAPI/CNG and PKCS#12 (for testing purposes). When signing module is not specified then PKCS#11 module is used by default.
| Option | Usage | Description |
|---|---|---|
| --pkcs11[=] | Optional | Sign via PKCS#11 module (default on Linux and macOS) |
| --cng | Optional | Sign via Microsoft CNG API (Windows) |
| --selectFirst | Optional | With --cng: use the first certificate in the store |
| --thumbprint= | Optional | With --cng: hex thumbprint of the certificate to use |
| --pkcs12= | Optional | Sign with a PKCS#12 software token (testing) |
PKCS#11 is the default module for signing with smart card in Linux and macOS. The value of --pkcs11= can be used to specify the path and filename of PKCS#11 driver in your file system. For example, "opensc-pkcs11.dll" in Windows environment and "opensc-pkcs11.so" in Linux and OSX. If the parameter’s value is left unspecified then PKCS#11 driver’s location is looked up from configuration file (see also chap. Configuration parameters).
With --cng, if --pin parameter’s value is not set then PIN insertion dialog is displayed to the user. If neither --selectFirst nor --thumbprint is set then certificate selection dialog window is displayed to user.
--pkcs12= enables to use a PKCS#12 software token (containing the signing certificate and private key) for signature creation. Note that the created signature is not a valid signature and it is not equal to handwritten signature as the PKCS#12 software token is not considered a secure signature creation device.
Sample commands for adding signatures:
Command "extend" adds new validity evidence and saves the result. Without --signature, it calls the high-level digidoc::Container::extendContainerValidity workflow: eligible ASiC-E or ASiC-S signatures are extended in place, or the original container is wrapped in a new timestamped ASiC-S container when necessary.
When one or more --signature options are specified, only those zero-based signature indexes are extended directly with digidoc::Signature::extendSignatureProfile. In this mode --profile selects the target profile and --dontValidate skips validation after each extension.
| Option | Usage | Description |
|---|---|---|
| --signature= | Optional | Zero-based index of a signature to extend, can repeat |
| --profile= | Optional | Target profile for direct per-signature extension |
| --dontValidate | Optional | Don't validate a directly extended signature |
| --tsurl= | Optional | Change TS URL |
| --tscert= | Optional | Pin the TSA TLS certificate, PEM file |
| --tsurlarchive= | Optional | Change archive (LTA) TS URL |
| --tscertarchive= | Optional | Pin the archive (LTA) TSA TLS certificate, PEM file |
--profile= values are TS, TSA, time-stamp or time-stamp-archive. The high-level workflow chooses the required profile automatically when --signature is omitted.
The time-stamping service options are the same as for the "sign" command. Archive time-stamps, including the TimeStampToken of a container wrapped in a new ASiC-S container, use --tsurlarchive= and --tscertarchive=.
Signatures and data files can be removed from a DigiDoc container with the command "remove". Note that it is possible to remove data files only from an unsigned container (i.e all signatures must be removed before removing data files). The command is supported with DigiDoc formats BDOC 2.1 and ASiC-E. General format of the command is:
Available options:
| Option | Usage | Description |
|---|---|---|
| --document= | Optional | Index of the data file to remove, counted from zero |
| --signature= | Optional | Index of the signature to remove, counted from zero |
Sample commands for removing signatures and data files:
1.15.0