Actions Library: S3 Private Archive

Overview

This Action programmatically exports decrypted SendSafely package contents to a private S3 bucket for long-term storage. Many customers will use this Action to export package contents to a WORM bucket.

To request the template for this Action example, please reach out to your SendSafely account rep. 

Please note that this Action requires access to the contents of SendSafely packages, and thus must be configured with a Trusted Browser Key (for packages owned by a specific user) or Portal Master Key (for all packages in your portal).

Setup Instructions

This workflow requires either:

• a Trusted Device Key (TDK) belonging to the API user, OR
• a Master Key uploaded to your SendSafely portal, used by an API user who is a portal Admin

Step 1, Option A: The Trusted Device Key Approach

A Trusted Device Key will allow only those packages submitted to the Dropzone owned by the API user to be archived.

Trusted Device Keys for human users can be generated on login. You can learn how to generate a Trusted Device Key for a Service Account here.

The following instructions detail how to create a TDK. To repeat: this TDK must be associated with the SendSafely API user (the SendSafely account whose API key is being used as part of this Workflow).

Create SendSafely Trusted Device Key Pair

Unzip the `nodejs-tdkeys-create` file, navigate to the `nodejs-tdkeys-create` directory, and run `npm install`.

Then run the `generate-keys-and-upload-public-key.js` script, passing in the following arguments:

node generate-keys-and-upload-public-key.js ssHost=https://company.sendsafely.com/ ssApiKey=XXXXX ssApiSecret=XXXXX keyDescription=XXXXX

Note: You will generate the API key and secret via the SendSafely portal. A SendSafely Admin can impersonate a Service Account and generate its API key and secret.

The script creates a TDK pair and uploads its Public Key to SendSafely. SendSafely returns a Public TDK ID, which is used in naming the TDK pair files. The script writes two files to the `./keys` directory:

1. `<sendsafely-public-key-id>-privatekey.txt`
2. `<sendsafely-public-key-id>-publickey.txt`

You will need the Private TDK and the Public TDK ID for the Lambda.

Step 1, Option B: The Master Key Approach

A Master Key will allow ALL packages submitted to ANY Dropzone in a SendSafely portal to be archived.

You can learn how to set up a Master Key here.

The SendSafely Support team will provide you with a Public Key ID (via email) during the Master Key process – you will need this value later, when deploying the Workflow via the CloudFormation Template.

Note: This value is not sensitive, but it is essential to retain it or the Workflow will fail to run.

Step 2. Set up Workflow for Specific Event(s)

With the Public Key ID of your TDK or Master Key handy, you'll now set up the Workflow, which is done via various calls to the SendSafely REST API.

Must be set up for BOTH “FINALIZE_PACKAGE” and “WORKSPACE_UPLOAD”, separately.

Add Workflow or Enterprise Workflow

You'll now set up the Workflow. If you're using a TDK, this Action to apply to a single Dropzone's packages; if you're using a Master Key, you can create it as an Enterprise Workflow, which will apply to all Dropzone packages in your portal.

For a user-level Workflow: issue a POST query to `/workflow`:

• Body:

{
 "workflowEventType":"FINALIZE_PACKAGE"
}

For an Enterprise Workflow, issue a POST query to `/enterprise/workflow`:

• Body:

{
 "workflowEventType":"FINALIZE_PACKAGE"
}

• Response:

{ 
 workflowId: '<workflow ID>', 
 workflowName: 'S3 Export Workflow', 
 workflowIdentity: '<identity>', 
 workflowOrgId: '<org ID>', 
 workflowEventType: 'FINALIZE_PACKAGE', 
 workflowStatus: 'INACTIVE', 
 workflowPriority: 1, 
 workflowNotificationEmail: 'admin@<company>.com',
 eventFilters: []
}

Note: Workflows are created in an INACTIVE state initially, and will not run until activated.

Add Actions

Add Actions by issuing POST queries to `/workflow/{workflowID}/action`.

Note: whitespace in the request body can result in "Incorrect Signature" errors from the server.

1st Action. Put a hold on the package on the SendSafely backend:

• Body:

{
 "actionType": "BLOCK_PACKAGE",
 "actionNotify": "DEFAULT"
}

2nd Action. Invoke the Lambda function:

• Body:

{
 "actionType": "INVOKE_WEBHOOK",
 "actionInput":"<LAMBDA URL>",
 "actionNotify": "ON_FALSE"
}

3rd Action. Release the hold on the package:

• Body:

{
 "actionType": "UNBLOCK_PACKAGE",
 "actionNotify": "DEFAULT"
}

• Response:

{ 
 actionId: '<action ID>', 
 actionOrder: 3, 
 actionType: 'UNBLOCK_PACKAGE', 
 actionNotify: 'DEFAULT', 
 response: 'SUCCESS' 
}

Add Action Filter

You will need to add an Action Filter to this third step, to only run if the 2nd Action succeeds (`ACTION_RESULT_TRUE`). To create this Action Filter, issue a POST query to `/workflow/:workflowId/action/:actionId/filter`.

• Body:

{
 "filterType": "ACTION_RESULT_TRUE",
 "filterValue": "<Action ID of 2nd Action>",
 "filterOperator":"EQUALS"
}

You will also need the Action Secret of the Webhook Action (i.e., `INVOKE_WEBHOOK` of the `FINALIZE_PACKAGE` Workflow), for use in the callback to SendSafely from the Lambda function. Retrieve this by issuing a GET query to `/workflow/:workflowId/action/:actionId/secret`.

Update Workflow

We'll now activate the Workflow so that it runs. To set the Workflow to "active," issue a PUT request to `/workflow/{workflowID}`:

• Body:

{ 
 "workflowStatus": "ACTIVE" 
}

• Response:

{
 "workflowStatus": "ACTIVE"
}

Update Action

To change Lambda URL, etc., as needed, issue a PUT request to `/workflow/{workflowID}/action/{actionID}`:

• Body:

{
 "actionInput": "<Lambda URL>"
}

Step 3. Deploy Lambda Function

Deploy the Lambda function using the CloudFormation Template (in YAML format) provided.

Note that you will need permissions in AWS to deploy the required resources: Lambda, S3 Bucket.

Step 4. Update Secrets Manager

There are two sets of secrets to update post-deployment:

1. Automatic_Export_Config
2. Automatic_Export_Private_Key

Navigate to the Secrets Manager link of the Stacks Resources tab in AWS to update the values of the following Automatic_Export_Config secrets:

• ss-host
• ss-api-key
• ss-api-secret
• ss-public-key-id

The `ss-public-key-id` is given to you by the SendSafely Support team (via email) and is NOT the same as any file IDs generated by any setup scripts.

For the following secret, you will need to update both the key and value:

• action-secret-id-\<actionId-finalize-package\>

For the key, you need to replace \<actionId-finalize-package\> with the actionId of the relevant Workflow Action.

You can retrieve the actionId by calling the `/workflows/` REST endpoint, and viewing the “actions” of the relevant Workflow – the relevant Action is the one with the actionType `INVOKE_WEBHOOK`.

Then, update the Automatic_Export_Private_Key Entry by pasting in the full text of the Trusted Device–or Master–Private Key, including the opening and closing tags:
- -----BEGIN PGP PRIVATE KEY BLOCK-----
- -----END PGP PRIVATE KEY BLOCK-----.

Step 5. Test Workflow

Now that you've set up the Workflow, trigger a test run based on the Event you enabled it for:

• FINALIZE_PACKAGE: Make a Dropzone submission, or create a Transfer Package (Send/Receive)
• WORKSPACE_UPLOAD: Upload a file to a Workspace

The script performs various checks on the required SendSafely configuration variables:

• publicKeyId (of either the TDK or the Master Key – if the latter, this ID is provided by SendSafely Support when you first submit your Master Key)
• ssHost
• ssApiKey
• ssApiSecret

The script will also check that the private SendSafely Master Key has been retrieved successfully from Secrets Manager.