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.

DocSignTool Installation

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

• Windows
• Linux and macOS

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:

• -h, --help: Display help message and exit.
• -V, --version: Display version information and exit.

Commands:

• get_credential_ids: Output the list of eSigner credential IDs associated with a particular user.
• credential_info: Output key and certificate information related to a credential ID.
• sign: Sign and timestamp PDF filr.
• batch_sign: Sign and timestamp multiple PDF files with one OTP.
• hash: Pre-compute hash(es) for later use with batch_hash_sign command.
• batch_sign_hash: Sign hash(es) pre-computed with hash command.

Parameters:

• -access_token=<TOKEN>: OAuth access token.
• -contact_info=<CONTACT_INFO>: Contact information.
• -credential_id=<CREDENTIAL_ID>: Credential ID for signing certificate.
• -input_dir_path=<PATH>: Input directory for PDF files to be signed, have hashes computed, or pick unsigned files and corresponding hashes for signing.
• -input_file_path=<PATH>: Path of PDF file to be signed.
• -otp=<OTP>: OAuth OTP value from authentication app.
• -output_dir_path=<PATH>: Directory where signed PDF file(s) will be written.
• -page_no=<PAGE_NUMBER>: Page of PDF document where visible signature will appear.
• -password=<PASSWORD>: SSL.com account password.
• -sig_field_position=<X, Y, WIDTH, HEIGHT>: Position of visible signature on PDF.
• -signing_location=<SIGNING_LOCATION>: Location where document is signed.
• signing_reason=<SIGNING_REASON>: Reason for signing.
• -totp_secret=<TOTP_SECRET>: OAuth TOTP secret
• -username=<USERNAME>: SSL.com account username

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:

• If -credential_id is omitted and the user has only one eSigner document signing certificate, DocSignTool will default to that. If the user has more than one document signing certificate, this parameter is mandatory.
• If -output_dir_path is omitted, the file specified in -input_file_path will be overwritten with the signed file. DocSignTool will prompt the user before overwriting the file.
• If -signing_location is present, the location specified will be added to the digital signature.
• If -signing_reason is present, the reason for signing specified will be added to the digital signature.
• If -contact_info is present, the specified text will be added to the digital sigature. Although included with the signature, this information will not be included in the visible signature annotation (if present).
• If -sig_field_position is present, a visible signature annotation will be added to the document on the page specified by -page_no. The position and signature should be supplied in the format "x, y, width, height".
• -page_no is only required when creating a visible signature with -sig_field_position and specifies the page of the document that the visible signature annotation will appear on.
• If -totp_secret is present, DocSignTool will calculate a time-based OTP for signing, allowing automated use of the tool. If this parameter is not present, the user will be prompted for manual OTP entry.

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.

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:

• If -credential_id is omitted and the user has only one eSigner document signing certificate, DocSignTool will default to that. If the user has more than one document signing certificate, this parameter is mandatory.
• If -output_dir_path is omitted, the files specified in -input_dir_path will be overwritten with the signed files. DocSignTool will prompt the user before overwriting the files.
• If -signing_location is present, the location specified will be added to the digital signatures.
• If -signing_reason is present, the reason for signing specified will be added to the digital signatures.
• If -contact_info is present, the specified text will be added to the digital sigatures. Although included with the signature, this information will not be included in the visible signature annotations (if present).
• If -sig_field_position is present, a visible signature annotation will be added to the documents on the page specified by -page_no. The position and signature should be supplied in the format "x, y, width, height".
• -page_no is only required when creating a visible signature with -sig_field_position and specifies the page of the documents that the visible signature annotations will appear on.
• If -totp_secret is present, DocSignTool will calculate a time-based OTP for signing, allowing automated use of the tool. If this parameter is not present, the user will be prompted for manual OTP entry.

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

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:

• If -program_name is present when signing an MSI installer, the value will be displayed in the confirmation dialog as the program name.
• If -signing_location is present, the location specified will be added to the digital signatures when they are generated.
• If -signing_reason is present, the reason for signing specified will be added to the digital signatures when they are generated.
• If -contact_info is present, the specified text will be added to the digital sigatures when they are generated. Although included with the signature, this information will not be included in the visible signature annotations (if present).
• If -sig_field_position is present, a visible signature annotation will be added to the documents on the page specified by -page_no when the signatures are generated. The position and signature should be supplied in the format "x, y, width, height".
• -page_no is only required when creating a visible signature with -sig_field_position and specifies the page of the documents that the visible signature annotations will appear on when they are generated.

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:

• If -credential_id is omitted and the user has only one eSigner document signing certificate, DocSignTool will default to that. If the user has more than one document signing certificate, this parameter is mandatory.

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:
   • CLIENT_ID=qOUeZCCzSqgA93acB3LYq6lBNjgZdiOxQc-KayC3UMw
   • OAUTH2_ENDPOINT=https://oauth-sandbox.ssl.com/oauth2/token
   • CSC_API_ENDPOINT=https://cs-try.ssl.com
   • TSA_URL=http://ts.ssl.com
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.