A light-weight, ephemeral secret sharing service. pysecrets uses a secure PBKDF (scrypt), and the latest AES encryption standards to ensure the confidentiality, integrity, and authenticity of data sent through the service. Pysecrets is intended to run in AWS as a containerized application, with a static UI.
Pysecrets requires python3.12, the cryptography module to support the mode of encryption used by the service, and boto3 (included in the python lambda runtime by AWS).
Pysecrets uses AWS services including: ECS, DynamoDB, and S3. These are used for the application runtime and UI, as well as storage of encrypted secrets.
docker build -t pysecrets .
To ensure the best security practices, the methods used for KDF and encryption/decryption have been baked into the code itself. There are a few options that can be configured. All of these should be passed in to the function via environment variables.
| VARIABLE | DEFAULT | DESCRIPTION |
|---|---|---|
| TTL_DAYS | 5 | Configures the TTL that the secret records will have in Dynamo. |
| S3_BUCKET | nil | Tells the server in which S3 bucket to store encrypted files. |
If using the provided terraform, TTL_DAYS is an option that can be passed in,
and S3_BUCKET is predefined with the proper value.
Because pysecrets uses static pages for the UI, the APIs can be accessed directly. To interact with the APIs, here are some examples via CURL. To send and receive a string based secret:
~ ❯ curl -X POST -H "Content-Type: application/json" https://URL/encrypt -d '{"secret": "super secret text", "view_count": 1}'
{"secret_id": "HrVfOn1aoqKHeRKi", "passphrase": "iT95_B9p9PSMcP-hH9OGS81w9FZVTEpf"}
~ ❯ curl -X POST -H "Content-Type: application/json" https://URL/decrypt -d '{"secret_id": "HrVfOn1aoqKHeRKi", "passphrase": "iT95_B9p9PSMcP-hH9OGS81w9FZVTEpf"}'
{"data": "super secret text"}
The string based secret sharing works by passing the encrypt route secret text
and a view count via a JSON payload. To retrieve the secret, send the decrypt
route the generated secret id and passphrase.
The file based API works similarly:
~ ❯ cat test.txt
hello
~ ❯ curl -X POST -F "file=@test.txt" https://URL/encrypt
{"secret_id": "97tfNQQBAl0w2zNE", "passphrase": "CPIX4PeLALaLaNLVFM~oNjM!N&bjZ377"}
~ ❯ curl -OJ -H "Content-Type: application/json" -X POST https://URL/decrypt -d '{"secret_id": "97tfNQQBAl0w2zNE", "passphrase": "CPIX4PeLALaLaNLVFM~oNjM!N&bjZ377"}'
~ ❯ cat test.txt
hello
The same encrypt route is used but this time, the data payload is the file to
encrypt. This is done using the multipart form mechanism so that it behaves the
same in browser and against the API. To retrieve this file, hit the same
decrypt route with the same payload as the string secret. This will return the
file and the proper Content-Disposition header needed to understand it is an
attachment that should be downloaded, and will include the file name.
Ephemeral Secret service utilizes the best in business algorithms and functions for proper encryption at rest that guarantees information security. There is another domain of security however not covered by the service itself. That is encryption in transit. As previously mentioned, an nginx configuration file is provided that can serve as the web server proxy. It is highly reccomended to follow or use this configuration as it contains all the options required for modern best practices on encryption in transit. When configuring these best practice options, there is a somewhat significant reduction in comptibility for older devices but considering the security gains this is a worthwhile sacrifice.
Pysecrets uses three main security standards to ensure full information security.
The first of which is the encryption/decryption mode. Pysecrets uses
AES-256-GCM. This uses the AES standard with a key size of 256 bits and the
GCM mode. GCM is a combination of Galois field authentication and a counter mode
algorithm and can be further documented
here. GCM was designed to
be performant (via parallelized operations) and to guarantee authenticity and
confidentiality. By using an AEAD (authenticated encryption with associated
data) cipher mode, one can guarantee that the ciphertext maintains integrity
upon decryption and will fail to decrypt if someone attempts to modify the
ciphertext while it remains encrypted.
Scrpyt is a password-based key derivation function and us used to generate the AES key used for encryption and decryption. Scrypt was designed to take input paramaters that relate largely to the hardware resources available. Because it uses the most resources available to it, brute force or custom hardware attacks become infeasible. More on the function can be read here.
Pythons os package comes with functions that allow for access to random number
generation from the /dev/urandom entropy pool device.
This project is licensed under the terms of the MIT License.