Command line utility tool

Command line utility tool overview

It is possible to use the library directly from the command line. NB! this tool is provided for testing purposes only!

Setting up the utility

The utility is distributed as a zip file with the name digidoc4j-util-*.zip (where * is the actual version number). Unzip the file to a directory of your choice. From that directory you can now run it:

java -jar digidoc4j-util.jar

After running the previous command, it shows the list of all available commands with a short description.

Test mode

It is possible to invoke the library in test mode by adding -Ddigidoc4j.mode=TEST. In this mode, demo timestamping and demo OCSP services are used together with demo TSL, allowing to use TEST certificates.

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar

Using custom configuration

A custom configuration file can be set up - just create your version of the file digidoc4j.yaml (modified according to your needs) and place it into utility's root folder (the one where the utility's .jar is in). When running the utility, your version of digidoc4j.yaml will be used, in case of its absence - utility will fall back to its default behavior.

If you are using Test mode, then customized version of digidoc4j-test.yaml can also be placed into utility's root folder. That way, when running in Test mode, your version of digidoc4j-test.yaml will be used, when running in Prod mode - your version of digidoc4j.yaml will be used. If digidoc4j-test.yaml is absent - your version of digidoc4j.yaml will be used for both Prod and Test modes, if absent - utility will fall back to default configuration (according to the mode chosen).

Examples of using the digidoc4j utility

In the following subsection, some examples are provided for using the utility.

Creating an ASiC-E container

A valid container contains at least one document (datafile) and is signed.

Signing with PKCS#12 (keystore)

Add a datafile to a container and sign it (a new container will be created if it does not exist yet):

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<container_file_path>" -add "<path_of_datafile_to_add>" "<mime_type>" -pkcs12 "<pkcs12_token_file>" "<pkcs12_token_password>"

It is also possible to add signatures to existing containers without adding new datafiles:

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<container_file_path>" -pkcs12 "<pkcs12_token_file>" "<pkcs12_token_password>"

Signing with PKCS#11 (ID-card or any other hardware token)

Add a datafile to a container and sign it (a new container will be created if it does not exist yet):

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<container_file_path>" -add "<path_of_datafile_to_add>" "<mime_type>" -pkcs11 "<pkcs11_driver_file>" "<PIN_code>" "<slot_number>"

It is also possible to add signatures to existing containers without adding new datafiles:

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<container_file_path>" -pkcs11 "<pkcs11_driver_file>" "<PIN_code>" "<slot_number>"

When the client computer has only one smartcard reader then for Estonian ID-cards typically first two slots are used:

• slot 0 - for authentication (PIN1)
• slot 1 - for signing (PIN2)

In case where computer has multiple smartcard readers (and depending on driver) the slot numbers can be different:

• slot 0 - reader 0, PIN1
• slot 1 - reader 0, PIN2
• slot 2 - reader 1, PIN1
• slot 3 - reader 1, PIN2
• etc

In order to investigate possibilities one can use OpenSC tools, for example:

pkcs11-tool -L --module /usr/local/lib/opensc-pkcs11.so

Example how to create and sign ASiC-E container in testing environment:

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "test.asice" -add "test.pdf" "application/pdf" -pkcs11 "/usr/local/lib/opensc-pkcs11.so" "12345" "1"

Creating multiple signed containers

To create signatures of all the files within a directory, you need to specify the input directory containing data files, and output directory where the signed containers will be saved.

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -inputDir "<input_directory_path>" -mimeType "<mime_type (optional)>" -outputDir "<output_directory_path>" -pkcs11 "<pkcs11_module_path>" "<pkcs11_token_pin_password>" "<pkcs11_slot_index>"

e-tokens which are bought from SK are initialized in FIPS 140-2 or EAL4+ CC v3.1 rez mode. Thanks to that PIN-code cannot be cached without adding PIN-caching to script. This means that you cannot use -inputDir, but can use only -in parameter with those tokens.

More information about creating and signing multiple containers can be found from this article.

Extending profile of signature(s)

In order to extend the profile of a signature in an existing container, use option -p (or -profile) and specify target profile:

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<file_name_and_path>" -p LTA

Container should contain at least one signature, and it can contain multiple signatures. Utility currently supports extension of signatures only for ASiC-E containers.

Additionally, you can override timestamp digest algorithm (-datst), TSP source url (-tspsource) and TSP source url for archive timestamps (-tspsourcearchive):

• in case of extending to LT profile, overridden value of TSP source url for signature timestamps (-tspsource) will take effect.
• in case of extending to LTA profile, overridden values of timestamp digest algorithm (-datst) and TSP source url for archive timestamps (-tspsourcearchive) will take effect.

When unset, utility will fall back to using parameters defined in the configuration.

Creating a timestamped ASiC-S container

A valid ASiC-S container contains only one document and is signed or timestamped.

• To create timestamped ASiC-S container the -tst option must be used, and the output file extension must be .asics or .scs:

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<output_file_name_and_path>" -add "<input_file_name_and_path>" "<mime_type>" -tst

• To timestamp an existing ASiC-S container (whether new or already timestamped), use the following command:

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<output_file_name_and_path>" -tst

It is possible to timestamp ASiC-S container more than once to maintain its long term availability and integrity.

Additionally, you can specify timestamp digest algorithm (-datst), reference digest algorithm (-refdatst) and TSP source url (-tspsourcearchive) to use. When unset, utility will fall back to using parameters defined in the configuration.

Timestamping option - respective configuration parameter that is overridden by that option:

• -datst - ARCHIVE_TIMESTAMP_DIGEST_ALGORITHM
• -refdatst - ARCHIVE_TIMESTAMP_REFERENCE_DIGEST_ALGORITHM
• -tspsourcearchive - TSP_SOURCE_FOR_ARCHIVE_TIMESTAMPS

Usage example with all options specified:

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<output_file_name_and_path>" -add "<input_file_name_and_path>" "<mime_type>" -tst -datst SHA384 -refdatst SHA512 -tspsourcearchive http://tsa.demo.sk.ee/tsarsa

How to run utility using custom configuration is described in the section Setting up the utility.

Usage of AIA OCSP

It is possible to use automatic AIA OCSP selection for signature creation. More information can be found in the QA section.

Since DigiDoc4j version 5.3.0, preference to use AIA OCSP is enabled by default. AIA OCSP preference can be disabled by specifying the -noaiaocsp or --noaiaocsp option.

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<container_file_path>" -add "<path_of_datafile_to_add>" "<mime_type>" -noaiaocsp -pkcs11 "<pkcs11_driver_file>" "<PIN_code>" "<slot_number>"

Prior to DigiDoc4j version 5.3.0, preference to use AIA OCSP had to be enabled explicitly by specifying the -aiaocsp or --aiaocsp option.

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<container_file_path>" -add "<path_of_datafile_to_add>" "<mime_type>" -aiaocsp -pkcs11 "<pkcs11_driver_file>" "<PIN_code>" "<slot_number>"

NB: the aiaocsp option was deprecated in DigiDoc4j version 5.3.0 and will be removed in the future.

Container Validation

The utility performs validation when specifying the -verify or -v option. The output shows all signatures and their statuses as well as all errors:

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<container_file_path>" -verify

In order to see validation warnings in addition to the errors you must specify the -warnings or -w option:

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<container_file_path>" -verify -warnings

In order to see even more information about the validation you must specify the -verbose or --verbose option:

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<container_file_path>" -verify -verbose

In order to see more detailed report of validation process you can specify -r "<report_directory_path>" option:

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<container_file_path>" -verify -r "<report_directory_path>"

Then you can find in given report directory following xml-files: validationReport.xml, validationDiagnosticData*.xml, validationDetailReport*.xml and validationSimpleReport*.xml.

Working with detached XAdES signatures

Signing with PKCS#12

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -xades -digFile "<file_name>" "<base64_encoded_sha256_digest>" "<mime_type>" -pkcs12 "<pkcs12_token_file>" "<pkcs12_token_password>" -sigOutputPath "<signature_file_path>"

Signing with PKCS#11

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -xades -digFile "<file_name>" "<base64_encoded_sha256_digest>" "<mime_type>" -pkcs11 "<pkcs11_driver_file>" "<PIN_code>" "<slot_number>" -sigOutputPath "<signature_file_path>"

Signing with multiple digest files (either with PKCS#11 or PKCS#12)

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -xades -digFile "<file_name>" "<base64_encoded_sha256_digest>" "<mime_type>" -digFile "<file_name>" "<base64_encoded_sha256_digest>" "<mime_type>" -pkcs11 "<pkcs11_driver_file>" "<PIN_code>" "<slot_number>" -sigOutputPath "<signature_file_path>"

Validation

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -xades -digFile "<file_name>" "<base64_encoded_sha256_digest>" "<mime_type>" -sigInputPath "<signature_file_path>"

Validation with multiple digest files

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -xades -digFile "<file_name>" "<base64_encoded_sha256_digest>" "<mime_type>" -digFile "<file_name>" "<base64_encoded_sha256_digest>" "<mime_type>" -sigInputPath "<signature_file_path>"