eSigner Document Signing Gateway Guide

The eSigner document signing gateway API distributes as a docker image and installs on the customer’s premise. It performs the following actions:

• The third party application sends the unsigned PDF document to the document signing gateway API
• The document signing gateway application computes the PDF hash and sends to the eSigner CSC API for hash signing
• The signed hash is then embedded inside the PDF document as part of the PDF document signing operation
• The signed PDF document is timestamped using SSL.com TSA
• The CRL based revocation of signer certificate chain is fetched and embedded inside the PDF document to make it LTV enabled

Requirements

Request:-

URL:- /v1/pdf/eseal

A valid access token is required to access the API. A guide on how to retrieve the Access Token can be found on this article: Remote Document Signing with eSigner CSC API

{
    "credential_id": "db1653b7-6135-4a10-809b-e29a25d3bb7b",
    "page_number": 0,
    "signing_reason": "",
    "signing_location": "",
    "contact_Info": "",
    "sig_field_position":{
      "x": 160,
      "y":245,
      "width":250,
      "height": 150  
    },
    "hand_signature": "<HAND_SIGNATURE_IMAGE>",
    "pdf": ""
}

Legend:

• credential_id – Mandatory credential ID of the eSeal certificate. To know how to identify the credential ID of your certificate, please refer to this guide: https://www.ssl.com/guide/esigner-signing-credential-guide/#ftoc-heading-2
• page_number – Only required for visible signatures. It starts with 0
• signing_reason – Optional signing reason
• signing_location – Optional signing location
• contact_info – Optional contact information
• sig_field_position – x, y, width and height of the signature field position. It is only required for visible signatures
• hand_signature – Base64 encoded PNG hand signature image. It is only required for visible signatures and to add hand signature as part of signature appearance
• pdf – Base64 encoded PDF document to sign

Response:-

{
     "signed_pdf": ""
}

• signed_pdf – Base64 encoded signed LTV enabled PDF document

Installation Instructions

1. Unzip the document signing gateway release
2. Open the application.properties files and change accordingly
   

   # For sandbox testing, set the CSR URL to https://cs-try.ssl.com and for production set it to https://cs.ssl.com
   
   csc.url=https://cs-try.ssl.com
   
   # URL of the SSL.com TSA
   
   tsa.url=http://ts.ssl.com
   
   # Port in docker container
   
   server.port=8081
   
   # TLS server certificate settings. One can use self signed certificate or private PKI or public PKI certificate
   
   server.ssl.enabled=true
   
   server.ssl.key-store: ./server.jks
   
   server.ssl.key-password: secret
   
   server.ssl.key-store-password: secret

3. Open the Dockerfile

   FROM eclipse-temurin:17.0.9_9-jdk-jammy
   
   # Port on which document signing gateway will be running. This must be same as in application.properties file
   
   EXPOSE 8081
   
   WORKDIR /app
   
   COPY document_signing_gateway-1.0.0.jar /app/
   
   COPY application.properties /app/
   
   COPY server.jks /app/
   
   COPY GoNotoKurrent.ttf /app/
   
   ENTRYPOINT ["java", "-Dspring.config.location=file:/app/application.properties", "-jar", "document_signing_gateway-1.0.0.jar"]

4. Install Docker Engine on your machine. Afterward, build the docker image using the following command
5. Run the container using the following command. It also creates volume for docker signing gateway API log file and port mapping as well
   docker run -it -p 8081:8081 -v document_signing_gateway_logs:/logs document_signing_gateway:1.0.0
6. Access the document signing gateway API using an application or POSTMAN tool.

Optional Mode: Esealing

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 can self-convert their Organization Validation (OV) document signing certificate to an esealing certificate on their SSL.com accounts. Take note that an Individual Validation (IV) document signing certificate cannot be converted for esealing. Instructions for esealing conversion are detailed below.

Convert your OV document signing certificate  to an esealing certificate

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.
   

Use eSealing endpoint

Note: SSL.com customers with an eSealing certificate can use a specific endpoint to efficiently seal PDF documents using just one API call since it does not require two-factor authentication. 

Sandbox eSealing endpoint: https://cs-try.ssl.com/csc/v1/credentials/list
Production eSealing endpoint: https://cs.ssl.com/csc/v1/credentials/list

The JSON request is: “DS_ESEAL”

It should look like the following image: