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

Sample of using the digidoc4j utility

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

Creating a BDOC container

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

java -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 time-mark signature profile

To sign a container using the time-mark protocol you need to specify the signature profile using the -profile option LT_TM:

java -jar digidoc4j-util.jar -in "<output_file_name_and_path>" -add "<input_file_name_and_path>" "<mime_type>" -profile LT_TM -pkcs12 "<pkcs12_token_file>" "<pkcs12_token_password>"

Using the ID-card

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

When the client computer has only one smartcard reader then for Estonian ID-cards there are usually two slots available:

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

In case where computer has multiple smartcard readers the slot numbers are usable in pairs:

• 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 BDOC container in testing environment:

java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -in "test.bdoc" -add "dds_acrobat.pdf" "application/pdf" -pkcs11 "/usr/local/lib/opensc-pkcs11.so" "22975" "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 -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.

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 -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 -jar digidoc4j-util.jar -in "<input_file_name_and_path>" -verify -warnings

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

java -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 -jar digidoc4j-util.jar -xades -digFile "<file_name>" "<base64_encoded_sha256_digest>" -pkcs12 "<pkcs12_token_file>" "<pkcs12_token_password>" -sigOutputPath <path_of_to_be_created_signature_file>

Signing with PKCS#11

java -jar digidoc4j-util.jar -xades -digFile "<file_name>" "<base64_encoded_sha256_digest>" -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 -jar digidoc4j-util.jar -xades -digFile "<file_name>" "<base64_encoded_sha256_digest>" -digFile "<file_name>" "<base64_encoded_sha256_digest>" -pkcs11 "<pkcs11_driver_file>" "<PIN_code>" "<slot_number>" -sigOutputPath <path_of_to_be_created_signature_file>

Using the time-mark signature profile

To create a detached XadES signature using the time-mark protocol you need to specify the signature profile using the -profile option LT_TM:

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

Validation

java -jar digidoc4j-util.jar -xades -digFile "<file_name>" "<base64_encoded_sha256_digest>" -sigInputPath <signature_file_path>

Validation with multiple digest files

java -jar digidoc4j-util.jar -xades -digFile "<file_name>" "<base64_encoded_sha256_digest>" -digFile "<file_name>" "<base64_encoded_sha256_digest>" -sigInputPath <signature_file_path>

Test mode

It is possible to invoke the library in test mode by adding -Ddigidoc4j.mode=TEST. This will use the test TSL and accepts test ID cards.

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