Skip to content

Command line utility tool

naare edited this page Aug 8, 2019 · 11 revisions

Command line utility tool overview

It is possible to use the library directly from the command line.

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

You can’t perform that action at this time.