-
Notifications
You must be signed in to change notification settings - Fork 39
Command line utility tool
It is possible to use the library directly from the command line. NB! this tool is provided for testing purposes only!
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.
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
In the following subsection, some examples are provided for using the utility.
A valid container contains at least one document (datafile) and is signed.
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>"
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"
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.
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.
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
.
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>"
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>"
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>"
java -Ddigidoc4j.mode=TEST -jar digidoc4j-util.jar -xades -digFile "<file_name>" "<base64_encoded_sha256_digest>" "<mime_type>" -sigInputPath "<signature_file_path>"
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>"
Official builds are provided through releases. If you want support, you need to be using official builds. For assistance, contact us by email [email protected]. Additional information can be found in wiki Q&A and on ID.ee portal.
For staying up to date with news impacting services and applications that use the DigiDoc4j library, join DigiDoc4j library newsletter.
Source code is provided on "as is" terms with no warranty (see license for more information). Do not file GitHub issues with generic support requests.