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

Sample of using the digidoc4j utility

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

Creating an ASICE container

Using keystore

A valid container contains at least one document and is signed. To create such a container:

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

Using the ID-card (or any other hardware token)

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<output_file_name_and_path>" -add "<input_file_name_and_path>" "<mime_type>" -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 ASICE 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.

Usage of AIA OCSP

It is possible to use automatic AIA OCSP selection for signatures when specifying the -aiaocsp or --aiaocsp option. AIA OCSP usage is not possible for LT_TM profile. More information can be found in the QA section.

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

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 "<input_file_name_and_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 "<input_file_name_and_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 "<input_file_name_and_path>" -verify -verbose

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

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

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

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

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

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>

Using the time-mark signature profile for BDOC and detached signatures

To create and sign an BDOC container you need to specify the signature profile using the -profile option LT_TM and the output file extension has to be .bdoc:

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "<output_file_name_and_path>" -add "<input_file_name_and_path>" "<mime_type>" -profile LT_TM -pkcs11 "<pkcs11_driver_file>" "<PIN_code>" "<slot_number>"

To create a detached XadES signature:

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