Evervault Python SDK

The Evervault Python SDK is a toolkit for encrypting data as it enters your server, working with Functions, and proxying your outbound api requests to specific domains through Outbound Relay to allow them to be decrypted before reaching their target.

Getting Started

Before starting with the Evervault Python SDK, you will need to create an account and a team.

For full installation support, book time here.

Before contributing, make sure to use commitizen & to read Contributing.md.

Documentation

See the Evervault Python SDK documentation.

Installation

Our Python SDK is distributed via pypi, and can be installed using pip.

pip install evervault

Setup

To make Evervault available for use in your app:

import evervault

# Initialize the client with your App's ID and App’s API key
evervault.init("<APP_ID>", "<YOUR_API_KEY>")

# Encrypt your data
encrypted = evervault.encrypt({ "name": "Claude" })

# Process the encrypted data in a Function
result = evervault.run("<YOUR_FUNCTION_NAME>", encrypted)

# Decrypt data
result = evervault.decrypt(encrypted)

# Send the decrypted data to a third-party API
evervault.enable_outbound_relay()
requests.post("https://example.com", json = encrypted)

# Send attested requests to a Cage
attested_session = evervault.cage_requests_session({ 'my-cage': { 'pcr_8': '...' } })
# Attested TLS directly to the enclave
attested_session.get('https://my-cage.my-app.cages.evervault.com/hello')

Reference

The Evervault Python SDK exposes five functions.

evervault.init()

evervault.init() initializes the SDK with your API key. Configurations for the interception of outbound requests may also be passed in this function.

evervault.init(app_id = str, api_key = str[, decryption_domains=[], retry = bool, curve = str])

Parameter	Type	Description
app_id	str	The ID of your Evervault App
api_key	str	The API key of your Evervault App
curve	str	The elliptic curve used for cryptographic operations. See Elliptic Curve Support to learn more.

evervault.encrypt()

evervault.encrypt() encrypts data for use in your Functions. To encrypt data at the server, simply pass a python primitive type into the evervault.encrypt() function. Store the encrypted data in your database as normal.

evervault.encrypt(data = dict | list | set | str | int | bool)

Parameter	Type	Description
data	dict, list, set, str, int, bool	Data to be encrypted

evervault.decrypt()

evervault.decrypt() decrypts data previously encrypted with the encrypt() function or through Evervault's Relay (Evervault's encryption proxy). An API Key with the decrypt permission must be used to perform this operation.

evervault.decrypt(data =  str | dict | list | bytes | bytearray)

Parameter	Type	Description
data	str, dict, list, bytes, bytearray	Data to be decrypted

evervault.run()

evervault.run() invokes a Function with a given payload. An API Key with the run function permission must be used to perform this operation.

evervault.run(function_name = str, data = dict[, options = dict])

Parameter	Type	Description
function_name	str	Name of the Function to be run.
data	dict	Payload for the Function.
options	dict	Options for the Function run.

Function Run Options

Option	Type	Default	Description
async	Boolean	False	Run your Function in async mode. Async Function runs will be queued for processing.
version	Integer	None	Specify the version of your Function to run. By default, the latest version will be run.

evervault.create_run_token()

evervault.create_run_token() creates a single use, time bound token for invoking a function. An API Key with the create Run Token permission must be used to perform this operation.

evervault.create_run_token(function_name = str, data = dict)

Parameter	Type	Description
function_name	str	Name of the Function the run token should be created for.
data	dict	Payload that the token can be used with.

evervault.enable_outbound_relay()

evervault.enable_outbound_relay() configures your application to proxy HTTP requests using Outbound Relay based on the configuration created in the Evervault dashboard. See Outbound Relay to learn more. Asynchronous HTTP requests are supported with aiohttp. Pass in a aiohttp.ClientSession to enable them for that session. Note: Requires Python 3.11+

evervault.enable_outbound_relay([decryption_domains = Array, debug_requests = Boolean])

Parameter	Type	Default	Description
decryption_domains	Array	None	Requests sent to any of the domains listed will be proxied through Outbound Relay. This will override the configuration created using the Evervault dashboard.
debug_requests	Boolean	False	Output request domains and whether they were sent through Outbound Relay.
client_session	aiohttp.ClientSession	None	The aiohttp client session to enable outbound relay on. Requires Python >= 3.11.

evervault.cage_requests_session()

evervault.cage_requests_session() creates a requests Session which attests all traffic between your client and the Cage. You can provide the PCRs generated at build time to have even tighter control on the attestation.

evervault.cage_requests_session([cage_attestation_data = dict])

Parameter	Type	Default	Description
cage_attestation_data	dict, list	None	Provide attestation measures to make assertions about the code running within your enclave. The cage_attestation_data dict is a mapping of cage names to their corresponding attestation measures. A list of dicts can also be used passed, if you want to allow roll-over between different sets of PCRs

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/evervault/evervault-python.

Feedback

Questions or feedback? Let us know.