Using the SendSafely REST API

Follow

This article outlines the steps required to access the SendSafely REST API and how to create a SendSafely package. The SendSafely REST API is available to users who are on an Enterprise Plan. 

Accessing the REST API

The SendSafely REST API Base URL is the following:

https://app.sendsafely.com/api/v2.0

The SendSafely REST API requires the following authentication-related HTTP headers on every request:

  • ss-api-key: SendSafely API Key obtained from the API Keys section of the Edit Profile page when logged into SendSafely
  • ss-request-timestamp: Generated in your client code using a standard date/time function to generate the current timestamp, and it should be in a format similar to the following:

2019-01-14T22:24:00+0000

  • ss-request-signature: HMAC calculated in your client represented by the following pseudo code:
HmacSHA256(API_SECRET, API_KEY + URL_PATH + TIMESTAMP + REQUEST_BODY)

API_SECRET is also obtained from the API Keys section of the Edit Profile page, and is only available when the API_KEY is first generated

API_KEY is the same value passed for the ss-api-key header

URL_PATH is the portion of the path after the Base URL

Example: https://demo.sendsafely.com/api/v2.0/package/

TIMESTAMP is the same value passed for the ss-request-timestamp header

REQUEST_BODY data passed in the body of an HTTP request (typically only relevant for POST, PUT, etc)

 

Create a new Package

The following steps can be used to create a new package using SendSafely:

Step 1 - Create a new (empty) Package

https://bump.sh/doc/sendsafely-rest-api#operation-put-package

Step 2 -  Add a file to the Package

Note: With SendSafely, files are encrypted using a PGP symmetric key (passphrase). The passphrase consists of the Server Secret (obtained from Step 1) combined with a Client Secret (also referred to as a “keycode” in Step 4). The Client Secret is generated client-side and should be a random 256-bit alphanumeric string. You will need this value after you perform Step 4 in order to construct the secure link that you will send to the recipients.

Before encrypting the file, you should also split the file into one or more “parts” to allow for faster processing when the user downloads and saves the file. We recommend using 2.5MB as the file part size. The total number of file parts should be calculated before you perform this step.

1. Generate a new File Id

https://bump.sh/doc/sendsafely-rest-api#operation-put-package-packageid-file

2. Obtain the S3 Upload URLs for each part

https://bump.sh/doc/sendsafely-rest-api#operation-put-package-packageid-file-fileid-upload-urls

3. Upload each file part

Uploads are done directly to S3 using PUT requests to the URLS obtained from Step b above. The body of each PUT request should only include the PGP encrypted file part in binary format.

When encrypting each file part, make sure you use the following PGP options:

  • Symmetric-Key Algorithm should be 9 (AES-256)
  • Compression Algorithm should be 0 (Uncompressed)
  • Hash Algorithm should be 8 (SHA-256)
  • Passphrase:  Server Secret concatenated with a random 256-bit Client Secret  
  • S2k-count: 65535
  • Filename: Any non-null value (typically the FileId + PartNumber)
  • Mode: b (62)

4. Mark the file upload as complete

https://bump.sh/doc/sendsafely-rest-api#operation-put-package-packageid-file-fileid-upload-urls

Step 3 - Add recipients

https://bump.sh/doc/sendsafely-rest-api#operation-put-package-packageid-recipient

Step 4 - Finalize the Package

For this step, you will need to calculate the “checksum” parameter using the keycode (Client Secret) and the Package Code (obtained from Step 1). The checksum is generated using PBKDF2-HMAC-SHA256 with the keycode as the password, and the Package Code as the salt.

Use the following inputs for your PBKDF2 function

  • Hashing Algorithm - SHA-256
  • Password  - Use the keycode for this value  
  • Salt - Use the Package Code for this value
  • Iteration Count - 1024
  • Key Length - 32 bytes  

https://bump.sh/doc/sendsafely-rest-api#operation-post-package-packageid-finalize

For additional information about the SendSafely API, including our Java, C#, and JavaScript SDKs, check out the SendSafely Developer Center on GitHub.

Have more questions? Submit a request