SSL.com

eSigner DocSignTool Command Guide

DocSignTool is a secure, privacy-oriented multi-platform Java command line utility for remotely signing PDF files using eSigner document signing certificates. Hashes of the documents are sent to SSL.com for signing so that the document itself is not sent. This is ideal where sensitive documents need to be signed, but should not be sent over the wire for signing. DocSignTool is also ideal for automated batch processes for high volume signings or integration into existing document workflows.

If you’d like to try DocSignTool with a demo account and certificate, please read eSigner Demo Credentials and Certificates for credentials and configuration information.

If you are looking to use esigner to sign code and excutables instead, please refer to this CodeSignTool guide.

OTP authorization is not required when signing using an esealing document signing certificate. Ignore all OTP parameters in the following guide if using an esealing document signing cerificate. (Customers with an existing Organization Validation document signing certificate can contact support@ssl.com to have it converted to an eSealing certificate.)

DocSignTool Installation

To install the current version of DocSignTool, simply download and unzip the correct file for your OS:

Note that the Windows download includes Java runtime, but the Linux/macOS version requires Java runtime to be installed on your computer. The Windows version of the command is a batch file (DocSignTool.bat) and the Linux/macOS version is a shell script (DocSignTool.sh).

DocSignTool Usage Overview

Usage: DocSignTool [-hV] [COMMAND] [PARAMETERS]

Options:

Commands:

Parameters:

If your password includes special characters, enclose it in quotes (e.g. -password="P!@^^ssword12").

DocSignTool Commands

get_credential_ids

Output the list of eSigner credential IDs associated with a particular user. Parameters -username and -password are required.

Usage: DocSignTool [-hV] get_credential_ids -username=<USERNAME> -password=<PASSWORD>

Example:

DocSignTool get_credential_ids -username=john.doe@example.com -password="P0z9@lxo41"
Credential ID(s):
- fe537ace-e132-52a9-c2e7-egcd2ac3f1e6

Entering DocSignTool get_credential_ids without the required parameters will display usage information for the command.

credential_info

Output key and certificate information related to a credential ID. Parameters -credential_id, -username, and -password are required.

Usage: DocSignTool [-hV] credential_info -credential_id=<CREDENTIAL_ID> -username=<USERNAME> -password=<PASSWORD>

Example:

DocSignTool credential_info -credential_id=fe537ace-e132-52a9-c2e7-egcd2ac3f1e6 -username=john.doe@example.com -password="P0z9@lxo41"
Signing Certificate Subject Information:
- Subject DN: CN=JOHN DOE, O=SSL Corp, L=Houston, ST=Texas, C=US
- Certificate Expiry: Sat Feb 11 14:52:59 EST 2023
- Issuer DN: CN=SSL.com Client Certificate Intermediate CA RSA R2, O=SSL Corp, L=Houston, ST=Texas, C=US

Entering DocSignTool credential_info without the required parameters will display usage information for the command.

sign

Sign and timestamp PDF file. Parameters -username, -password, and -input_file_path are required. -credential_id is required only for users with more than one eSigner document signing certificate. -output_dir_path, -signing_location, -signing-reason, -contact_info-sig_field_position, -page_no, and -totp_secret are optional.

Usage: DocSignTool sign [-hV] [-credential_id=<CREDENTIAL_ID>] -username=<USERNAME> -password=<PASSWORD> -input_file_path=<PATH> [-output_dir_path=<PATH>] [-signing_location=<SIGNING_LOCATION>] [-signing_reason=<SIGNING_REASON>] [-contact_info=<CONTACT_INFO>] [-sig_field_position=<X, Y, WIDTH, HEIGHT>][-page_no=<PAGE_NUMBER>] [-totp_secret=<TOTP_SECRET>]

Optional parameters:

For information on enrolling an EV document signing certificate in eSigner and setting up two-factor authentication, please read Remote EV Code Signing with eSigner. For information on the TOTP secret value, please refer to Automate eSigner EV Code Signing.

Examples:

Manual OTP Entry with Visible Signature:

DocSignTool sign -credential_id=fe537ace-e132-52a9-c2e7-egcd2ac3f1e6 -username=john.doe@example.com -password="P0z9@lxo41" -output_dir_path=signed -input_file_path=test.pdf -sig_field_position="100, 200, 150, 70" -page_no=1 -signing_location="Houston, Texas" -signing_reason="document approval" -contact_info="support@ssl.com"
Enter the OTP - Press enter to continue: 884646
PDF signed successfully: output\test.pdf

Automated OTP Generation, No Visible Signature:

DocSignTool sign -credential_id=fe537ace-e132-52a9-c2e7-egcd2ac3f1e6 -username=john.doe@example.com -password="P0z9@lxo41" -output_dir_path=signed -input_file_path=test.pdf -totp_secret=ii5gVvZ9G+WkxB3FauAnoL/z14AXSMistcE0jZMWWNSjQDlql2kt2D6Z+l8=
PDF signed successfully: output\test.pdf

Entering DocSignTool sign without the required parameters will display usage information for the command.

If you get the error message, Error: invalid otp when attempting to sign a file, it could be caused by one or more of these issues:
  • The QR code you scanned into your authentication app doesn’t match the username, password, and/or credential ID from your command. This could happen if:
    • You have multiple accounts configured for 2FA on your device and chose the wrong one.
    • You are attempting to use your login credentials for a shared certificate, but scanned a QR code shared by a teammate from their account.
  • The OTP you entered has already expired.
  • Your command includes an invalid TOTP secret.

batch_sign

Sign and timestamp up to 100 PDF files with one OTP. Parameters -username, -password, and -input_dir_path are required. -credential_id is required only for users with more than one eSigner document signing certificate. -output_dir_path, -signing_location, -signing-reason, -contact_info-sig_field_position, -page_no, and -totp_secret are optional.

Usage: DocSignTool [-hV] batch_sign [-hV] [-credential_id=<CREDENTIAL_ID>] -username=<USERNAME> -password=<PASSWORD> -input_dir_path=<PATH> [-output_dir_path=<PATH>] [-signing_location=<SIGNING_LOCATION>] [-signing_reason=<SIGNING_REASON>] [-contact_info=<CONTACT_INFO>] [-sig_field_position=<X, Y, WIDTH, HEIGHT>][-page_no=<PAGE_NUMBER>] [-totp_secret=<TOTP_SECRET>]

Optional parameters:

Example:

DocSignTool batch_sign -username=john.doe@example.com -password="P0z9@lxo41" -credential_id=fe537ace-e132-52a9-c2e7-egcd2ac3f1e6 -input_dir_path=input -output_dir_path=output -sig_field_position="100, 200, 150, 70" -page_no=1 -signing_location="Houston, Texas" -signing_reason="document approval" -contact_info="support@ssl.com"
Enter the OTP - Press enter to continue: 455145
Batch sign command executed successfully. Output directory for signed files: output

Entering DocSignTool batch_sign without the required parameters will display usage information for the command.

hash

SHA 256 algorithm should be used to compute the hash of the PDF document. 
  1. A PDF library is needed to manipulate the PDF for hash input and later embed the PKCS#7 in the PDF document. (ex. ApachePDFBox in Java). 
  2. A Crypto library for creating PKCS#7 out of raw signatures received from eSigner API (ex. BouncyCastle in Java).

Pre-compute hash(es) for later use with batch_hash_sign command. Parameters -access_token and -input_dir_path are required. -credential_id is required only for users with more than one eSigner document signing certificate. -signing_location, -signing-reason, -contact_info-sig_field_position, and -page_no, are optional.

Usage: DocSignTool [-hV] hash -access_token=<ACCESS_TOKEN> -input_dir_path=<PATH> [-signing_location=<SIGNING_LOCATION>] [-signing_reason=<SIGNING_REASON>] [-contact_info=<CONTACT_INFO>] [-sig_field_position=<X, Y, WIDTH, HEIGHT>][-page_no=<PAGE_NUMBER>]

Optional parameters:

Example:

DocSignTool hash -access_token=eyJraWQiOiJmUE1yYUdlbXVMWGUtcG9JWUtLem1CMEYwYXlFczktUEpiN29lTWFlY2I0IiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJTU 0wuY29tIEF1dGhlbnRpY2F0aW9uIFNlcnZpY2UiLCJleHAiOjE2MTQ4OTcxNDIsImlhdCI6MTYxNDg5MzU0MiwianRpIjoiZmI2OTZlNDUtMTIzOS00ZGE4LW I1MmYtODNkZDE2MTY3ZTM3IiwidXNlciI6eyJ1c2VyX2lkIjoxMzIyODU4LCJ1c2VyX2VtYWlsIjoiYWFyb24uZS5ydXNzZWxsQGdtYWlsLmNvbSIsInNzbF9 hY2NvdW50X2lkIjo0NzQzMDJ9LCJjbGllbnQiOnsiaWQiOiJmUE1yYUdlbXVMWGUtcG9JWUtLem1CMEYwYXlFczktUEpiN29lTWFlY2I0In19.fCKDs1igjsI UDG2sUN_2OTb90Jw1nKNPHcD1MyEUR6sHCv_aJmcvcaFRne_eKLHzeQ9WtT5y3Fb2ppc50kMnjPG6JgX5gnFMptMn-ySsI277CtKbkSn3u-WSDSovn51jPm82 4wTeJmuXEzdv9clRjTwp6VoM9eqHCIaDAd3MP2xpMaa35cZbDaaAFKQ7jxWo9dUuTZY7DsKK0p1LloUEnmNxtNimQ3GDwkj_M600WB1zYrhDL9_3oZKaXcUx9 qzHcBCLzGgeaZ0xdpZtADxmXDUCcmkZi20yQ53bxqVL2w00sJ73efKB7JGeGWVehO-ZlGs3PUQwooox1JgEgcsA -credential_id=fe537ace-e132-52a9 -c2e7-egcd2ac3f1e6 -input_dir_path=input
Hash command executed successfully. Hash files created at: input

Entering DocSignTool hash without the required parameters will display usage information for the command.

batch_sign_hash

Sign hash(es) pre-computed with hash command. Parameters -access_token, input_dir_path, -otp, and output_dir_path are required. -credential_id is required only for users with more than one eSigner document signing certificate.

Usage: DocSignTool [-hV] batch_sign_hash -access_token=<ACCESS_TOKEN> [-credential_id=<CREDENTIAL_ID>] -input_dir_path=<PATH> -output_dir_path=<PATH> -otp=<OTP>

Optional parameters:

Example:

DocSignTool batch_sign_hash -access_token=eyJraWQiOiJmUE1yYUdlbXVMWGUtcG9JWUtLem1CMEYwYXlFczktUEpiN29lTWFlY2I0IiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJTU
0wuY29tIEF1dGhlbnRpY2F0aW9uIFNlcnZpY2UiLCJleHAiOjE2MTQ4OTcxNDIsImlhdCI6MTYxNDg5MzU0MiwianRpIjoiZmI2OTZlNDUtMTIzOS00ZGE4LW
I1MmYtODNkZDE2MTY3ZTM3IiwidXNlciI6eyJ1c2VyX2lkIjoxMzIyODU4LCJ1c2VyX2VtYWlsIjoiYWFyb24uZS5ydXNzZWxsQGdtYWlsLmNvbSIsInNzbF9
hY2NvdW50X2lkIjo0NzQzMDJ9LCJjbGllbnQiOnsiaWQiOiJmUE1yYUdlbXVMWGUtcG9JWUtLem1CMEYwYXlFczktUEpiN29lTWFlY2I0In19.fCKDs1igjsI
UDG2sUN_2OTb90Jw1nKNPHcD1MyEUR6sHCv_aJmcvcaFRne_eKLHzeQ9WtT5y3Fb2ppc50kMnjPG6JgX5gnFMptMn-ySsI277CtKbkSn3u-WSDSovn51jPm82
4wTeJmuXEzdv9clRjTwp6VoM9eqHCIaDAd3MP2xpMaa35cZbDaaAFKQ7jxWo9dUuTZY7DsKK0p1LloUEnmNxtNimQ3GDwkj_M600WB1zYrhDL9_3oZKaXcUx9
qzHcBCLzGgeaZ0xdpZtADxmXDUCcmkZi20yQ53bxqVL2w00sJ73efKB7JGeGWVehO-ZlGs3PUQwooox1JgEgcsA -credential_id=fe537ace-e132-52a9
-c2e7-egcd2ac3f1e6 -input_dir_path=input -output_dir_path=output -otp=142392
Batch sign hash command executed successfully. Output directory for signed files: output

Entering DocSignTool batch_sign_hash without the required parameters will display usage information for the command.

How to test  DocSignTool in sandbox mode

  1. In the DocSignTool release, go to conf folder and open doc_sign_tool.properties file
  2. Comment out the existing properties by adding # symbol before every property
  3. Add the following properties in the file:
  4. Save the file. After saving, DocSignTool can now be used in sandbox mode.
  5. To switch back to production mode, uncomment the existing properties and delete the sandbox properties.

Optional: Convert your OV document signing certificate  to an esealing certificate

Note: This section is only for users who want to do esealing. To automate document signing and not be prompted by One Time Passwords (OTP), users self-convert their Organization Validation (OV) document signing certificate to an esealing certificate on their SSL.com accounts. Instructions are below:

  1. Click Orders on the top menu of your SSL.com account. 
  2. Locate your certificate and click the download/details link.
  3. Click the REMOVE 2FA button.
Thank you for choosing SSL.com! If you have any questions, please contact us by email at Support@SSL.com, call 1-877-SSL-SECURE, or just click the chat link at the bottom right of this page. You can also find answers to many common support questions in our knowledgebase.
Exit mobile version