If you have been granted access to an Amazon S3 bucket for storing data, here's how to interact with the contents:

Authentication

Your server is associated with a custom profile that grants it full permission to your Amazon S3 bucket. Thus, any command issued through the AWS command line interface or through one of their SDK's will work automatically without the need to add a key pair to your environment.

If you require access to your bucket outside of the Healthcare Blocks environment, please create a support ticket, and we'll allocate a key pair you can use externally.

Application-Level Authentication

Files containing PHI should have their S3 object permissions set to "private" via the AWS SDK. If you need end users to be able to retrieve content directly from S3 (even if your application obfuscates the S3 object URL and does an internal redirect), your application should create a pre-signed token that automatically expires within 5 minutes. This prevents users from distributing a valid object URL externally. The AWS SDK (for each programming language) contains pre-signed S3 URL functionality - please refer to the respective documentation.

Encryption at Rest

If you are storing any PHI in S3, you will need to set the server-side encryption option when using the AWS SDK in your application. Please refer to the documentation for the relevant AWS SDK.

New! On November 6, 2017, AWS rolled out a feature that enables the setting of a default encryption policy for a bucket. Healthcare Blocks has turned on this option for all buckets. If your bucket was created prior to mid-November 2017, any objects that require encryption should have used the AWS SDK to set an encryption flag. If you need to encrypt existing objects on a global scale, please create a help desk ticket.

Don't Embed PHI in Object Names

S3 does not obfuscate object names, therefore it is important that you do not embed patient names, SSN, and other PHI identifiers in the file names of the objects saved to S3.

Listing Bucket Contents

Assuming your bucket is called healthcareblocks-123:

aws s3 ls s3://healthcareblocks-123

Uploading a local file

aws s3 cp myfile.txt s3://healthcareblocks-123 --sse

The "--sse" flag is important because it enables server-side encryption.

Also, note that you don't need to be in the same directory as the file, since the aws command works from any directory, e.g.

aws s3 cp /data/postgresql/dropbox/somefile.tar.bz2 s3://healthcareblocks-123 --sse

Downloading a file

aws s3 cp s3://healthcareblocks-123/stuff.txt myfile.txt

Additional Reference

Check out the Amazon CLI S3 reference page: http://docs.aws.amazon.com/cli/latest/reference/s3/

Desktop Clients

Mac

Windows