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:
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:
- 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
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
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
2. Obtain the S3 Upload URLs for each part
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
Step 3 - Add recipients
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