This guide will show you how to enroll a document signing certificate order with SSL.com’s eSigner service and use the Cloud Signature Consortium (CSC) API to digitally sign a document hash and a PDF file. You can use this guide with either cURL or Postman. We recommend that Postman users install the desktop app for working through the examples. The examples in this guide are both applicable to SSL.com’s production and test eSigner and eSealing environments. Differences in commands between production and test modes are explained in the following sections.
To follow these instructions you will need:
- A validated document signing certificate order. Please read this how-to for full instructions on ordering and validation.
- A Client ID (also known as an Application ID. Please refer to this how-to for instructions on generating this credential).
Order your SSL.com Document Signing Certificate
How to Order a Certificate in the Production Environment
Please refer to this guide article for instructions on how to order a production document signing certificate: Ordering Process for Code and Document Signing Certificates
How to Order a Test Certificate on SSL.com’s Sandbox
SSL.com offers a dedicated Sandbox environment, mirroring our live SSL.com portal and SWS API, for a risk-free experimentation space. This “laboratory” setting allows users to explore and test SSL.com’s services without the worry of causing disruptions or incurring actual costs.
The article, Using the SSL.com Sandbox for Testing and Integration, will help you navigate the process of establishing a Sandbox account, initiating a test order, and integrating the Sandbox with the SWS API.
Once you have created your test certificate, please contact the SSL.com support team to have it validated. You can do this by clicking the online chat button at the lower-right corner of the SSL.com website or sending an email to support@ssl.com.
Enroll in eSigner and Set Up Two-Factor Authentication
Before you can start using the CSC API, you’ll need to enroll in SSL.com’s eSigner cloud signing service. Validated orders can be enrolled in eSigner following the instructions below:
- . Navigate to the Orders tab in in your SSL.com account and locate your order.
- Click the order’s details link.
- Create a and confirm a 4-digit PIN, then click the create PIN button.
If you need to reset your eSigner PIN, please read this how-to.
- A QR code will appear.
The next time you reload the page the QR code will not be visible. If you need to to view or reset your eSigner QR code, please read this how-to.
- Scan the code into a 2-factor authentication app on your mobile device, such as Google Authenticator or Authy. The app will provide you with one-time passwords (OTPs) for use when signing. Each OTP is valid for 30 seconds.
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
- Click Orders on the top menu of your SSL.com account.
- Locate your certificate and click the download/details link.
- Click the REMOVE 2FA button.
Install Postman and Import API Collections
The instructions in this section are for Postman users only. If you’re using cURL with the CSC API, you can move onto the next section.
- Download and unzip the CSC API Postman collection and Document Signing API Postman collection (see https://www.postman.com/sslcom for online SSL.com API collections).
- Download and install the Postman REST Client.
- Launch Postman, then create a new Postman account or sign into an existing one.
- Click the Import button.
- Click the Upload Files button, navigate to the unzipped API collection files (
csc-api-prod.postman_collection.jsonanddocument-signing-api-prod.postman_collection.json), and open them.
- Click the Import button.
- The API requests you will be working with are now available in the Collections tab on the left side of the Postman window.
Retrieve Access Token
The next step is to retrieve an access token from SSL.com. You’ll need your Client ID available, as well as the username and password for your SSL.com account. Access tokens are valid for one hour after they are issued.
Use the clickable tabs below to choose instructions for Postman or cURL:
- Select an API request from the CSC API collection.
- Select the Authorization tab and select OAuth 2.0 from the Type menu.
- Enter the following information into the form:
- Header Prefix:
Bearer - Token Name:
SSLCOM CSC(or any other easy-to-remember name that you prefer) - Grant Type:
Authorization Code - Callback URL:
https://upload.esigner.com - Authorize using browser: unchecked
- Auth URL:
https://login.ssl.com/oauth2/authorizefor Production environment;https://oauth-sandbox.ssl.com/oauth2/authorizefor Sandbox environment. - Access Token URL:
https://login.ssl.com/oauth2/tokenfor Production environment;https://oauth-sandbox.ssl.com/oauth2/tokenfor Sandbox environment. - Client ID: [Your Client ID]
- Client Secret: [Your Client Secret]
- Scope:
service - State: [leave blank]
- Client Authentication:
Send as Basic Auth header
When you are finished, click the Get New Access Token button.
- Header Prefix:
- A login form will appear. Enter your SSL.com username and password, then click the Member Login button.
- Your new access token should appear in Postman. Select the access token text and copy it to the clipboard, then close the Manage Access Tokens dialog box. Paste your access token into a text editor where you can access it easily. Each access token will expire after one hour.
You can also save your token for re-use in Postman requests, but we have found that it is most reliable to copy and paste the token directly into each request.
- Use the following command to request an access token. Replace the values shown in ALL-CAPS with your actual values:
curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{ "client_id" : "YOUR-CLIENT-ID", "client_secret" : "YOUR-CLIENT-SECRET", "grant_type" : "password", "username" : "YOUR-USERNAME", "password" : "YOUR-PASSSWORD" }' - You should receive a JSON object containing an access token and a refresh token. Copy the access token value to paste into your API requests. You won’t need the refresh token for these examples.
Sign a Hash
Now that you have an access token, you can begin making API requests and creating signatures. This section will lead you through the five available requests in the Postman CSC collection, resulting in the creation of a digital signature from a document hash.
- 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).
- A Crypto library for creating PKCS#7 out of raw signatures received from eSigner API (ex. BouncyCastle in Java).
Get CSC Info (Optional)
- You can use the CSC Info request to get information about SSL.com’s cloud signature service. Note that, unlike the others in the collection, this request does not require your access token. To send the request, select CSC Info from the CSC API collection, then click the Send button.
- Information about the cloud signature service will appear in a JSON object in Postman’s Response field.
- Use the following command to get info about SSL.com’s CSC API service. If you in sandbox environment, use
https://cs-try.ssl.com/csc/v0/infoinstead.
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Content-Type: application/json" \ --data-raw "{}" - You will recieve a JSON object with details about the service:
CSC Credentials List
The CSC Credentials List request will retrieve a credential you will use in later API requests.
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. If you do not have an eSealing certificate, please proceed to the regular instructions below.
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:
- Select CSC Credentials List and click the Authorization tab.
- Choose Bearer Token from the Type menu, paste your access token into the Token field, then click the Send button.
- A JSON object with a list of credential IDs associated with the user will appear in the Response field. Your list will probably contain one value. Copy and paste your credential ID into a text editor for use in later requests.
- Enter the following command. (Replace MY-ACCESS-TOKEN with your actual access token). If you are in sandbox environment, use
https://cs-try.ssl.com/csc/v0/credentials/listinstead:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY-ACCESS-TOKEN" \ --data-raw "{}"If using an eseal certificate (document signing certificate with only organization information; included with your free esigner.com account), then include “clientData”: “DS_ESEAL” (note: eseals do not require OTP authentication). Other options for “clientData” are “EVCS” for EV Code Signing and “DS” (default) for IV or IV+OV Document Signing :
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY-ACCESS-TOKEN" \ --data-raw '{"clientData": "DS_ESEAL"}' - You should receive a JSON object with a list of credential IDs associated with the user. Your list will probably contain one value. Copy and paste your credential ID into a text editor for use in later requests.
CSC Credentials Info (Optional)
The CSC Credentials Info request will return certificates and other information associated with a credential ID, and is not required for signing.
- To use this request, select CSC Credentials Info from the collection and click the Authorization tab.
- Choose Bearer Token from the Type menu, then paste your access token into the Token field.
- Select the Body tab, then paste your credential ID as the value for
credentialID.
- Click the Send button.
- A JSON object with your signing certificate chain and other information will appear in the Response field.
- Enter the following command. If you are in the sandbox environment, use
https://cs-try.ssl.com/csc/v0/credentials/infoReplaceMY-ACCESS-TOKENandMY-CREDENTIAL-IDwith your actual information:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY-ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "certificates": "chain", "certInfo": true, "authInfo": true }' - You should receive a JSON object with your signing certificate chain and other information:
Credentials Authorize
The Credentials Authorize request will retrieve authorization for signing a hash.
- Begin by selecting Credentials Authorize from the collection and clicking the Authorization tab.
- Choose Bearer Token from the Type menu, then paste your access token into the Token field.
- Select the Body tab. Paste your credential ID as the
credentialIDvalue and a hash of the document you wish to sign as thehashvalue. Retrieve and enter an OTP from your authentication app and enter it as the value forOTP, then click the Send button. Note: OTP is not required for esealing certificates.
- A JSON object with your Signature Activation Data (SAD) will appear in the Response field. Copy and paste this value into a text editor for use in the hash signing request.
- Use the following command. Replace
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID, andMY-HASHwith your actual information. Get a one-time password from your 2FA application and use is as the value forMY-OTP. Note: OTP is not required for esealing certificates.
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY-ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP" }' - You should receive a JSON object with your Signature Activation Data (SAD). Copy and paste this value into a text editor for use in the hash signing request.
Sign Hash
Now you’re ready to sign the document hash.
- Select Sign Hash from the collection, then select the Authorization tab.
- Choose Bearer Token from the Type menu, then paste your access token into the Token field.
- Select the Body tab. Paste your credential ID as the
credentialIDvalue, your Signature Activation Data as theSADvalue, and a hash of the document you wish to sign as thehashvalue, then click the Send button.
- A JSON object with your signature will appear in the Response field.
- Enter the following command. Replace
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-SAD, andMY-HASHwith your actual information:
curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY-ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "hash": [ "MY-HASH" ], "signAlgo": "1.2.840.113549.1.1.11" }' - You should receive a JSON object containing your signature.
Sign a PDF
In addition to signing document hashes, you can also upload and sign a PDF file.
When signing a PDF you will be working with two POST requests:
- Upload PDF Document
- Sign PDF Document
You can re-use the credential you retrieved above with the CSC Credentials List request. You will probably also need to retrieve a new access token.
Upload PDF Document
- Select the Upload PDF Document request and click the Authorization tab.
- Choose Bearer Token from the Type menu, then paste your access token into the Token field.
- Select the Headers tab and paste your credential ID in the Value column.
- Select the Body tab and click the × next to
hello.pdfto remove this placeholder filename.
- Click the Select File button, then navigate to the file you want to upload.
- Click the Send button.
- Select and copy the
idvalue in the response to use in the next request.
- Use the following command. Replace
MY-CREDENTIAL-ID,MY-ACCESS-TOKEN, and/PATH/TO/FILE.pdfwith your actual information:
curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Authorization: Bearer MY-ACCESS-TOKEN" \ --header "Content-Type: application/pdf" \ --data-binary "@/PATH/TO/FILE.pdf"
- You will receive a JSON object with a value for
id. Copy this value to use in the next request.
Note: For visible signatures, please refer to the following HTTP Request Headers (/v1/pdf/upload):
|
Credential-Id |
Unique Credential ID assigned to the key – Mandatory |
|
Signing-Reason |
Add signing reason to add in signature appearance and also in signature dictionary – Optional e.g. I approve this document |
|
Signing-Location |
Add signing location in signature dictionary – Optional e.g. Houston, Texas |
|
Contact-Info |
Add contact information in signature dictionary – Optional e.g. Phone number |
|
Signature-Field-Position |
Signature field position where visual signature displays. The format is “x,y,width,height“ – Optional |
|
Page-Number |
Page number where to draw signature – Optional |
|
Hand-Signature |
Base64 encoded PNG image of hand signature – Optional |
Sign PDF Document
Now you can sign the PDF.
- Select the Upload PDF Document request and click the Authorization tab.
- Choose Bearer Token from the Type menu, then paste your access token into the Token field.
- Select the Body tab, paste in the
idvalue from the previous step and an OTP from your authentication app, then click the Send button.
- The PDF data will appear below in the Response field. Choose Save to a File from the Save Response menu, then give the file a name.
- Open the file in Acrobat to confirm that the file has been signed.
- Enter the following command. Replace
MY-CREDENTIAL-ID,MY-FILE-ID, andOUTPUT-FILENAMEwith your actual information. Get a one-time password (OTP) from your 2FA app and enter it asMY-OTP. Note: OTP is not required for esealing certificates:
curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Content-Transfer-Encoding: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer MY-ACCESS-TOKEN' \ --data-raw '{ "id": "MY-FILE-ID", "otp":"MY-OTP" }' \ --output OUTPUT-FILENAME - cURL will download the signed file and save it to the filename you specified:
- Open the PDF in Acrobat or Acrobat Reader to check that the signature is valid.
