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

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.

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>"