Guides
Python SDK
You can use our Python SDK to:
- Encrypt data server-side
- Decrypt data server-side
- Invoke Functions
- Proxy requests through Outbound Relay
Encrypting/Decrypting data with our backend SDKs instead of Inbound Relay may expose you to greater compliance burden because your server handles plaintext data.
Instead you can:
- Use an Inbound Relay to encrypt data before it reaches your server.
- Use an Outbound Relay to decrypt data before it reaches a third-party service.
- Use our client-side SDKs to encrypt data before sending it to your server.
Quickstart
Install SDK
Our Python SDK is distributed via pypi, and can be installed using pip
.
Initialize SDK
Now, let's initialize the SDK using our App's ID and our App's API key. If you don't have an API key yet, you can get one by creating an App in the Evervault Dashboard.
Encrypt a string
Now that the SDK is initialized, we can encrypt a string.
Full example
Pulling all of this together leaves us with the following working example. You can copy and paste the code below (using a sandbox API key, and App ID), run it in your own environment and run the encryption and decryption for yourself.
Reference
evervault.init(app_id, api_key)
Initializes the SDK with your API Key and App ID.
evervault.encrypt(data)
Encrypts data using Evervault Encryption.
To encrypt a string using the Python SDK, simply pass a str
or a dict
into the evervault.encrypt()
function. To encrypt a file, pass a bytes
or bytearray
.
The encrypted data can be stored in your database or file storage as normal. Evervault Strings can be used across all of our products. Evervault File Encryption is currently in Beta, and files can only be decrypted with Outbound Relay.
evervault.decrypt(data)
evervault.decerypt()
decrypts the data previously encrypted with the encrypt()
function or through Relay.
An API key with the decrypt
permission must be used to perform this operation.
Decrypting data with our backend SDKs is not available if you are part of the PCI or HIPAA compliance use cases
Instead you can:
- Use Outbound Relay to decrypt data before sending it to third-parties.
- Use Functions or Cages to process encrypted data.
evervault.run(function_name, data, options)
evervault.run()
lets you invoke an Evervault Function with a given payload.
Response
Function runs will return a JSON object containing a Function Run ID and the result from your Function in the following format:
evervault.create_run_token(function_name, data)
Creates a single use, time bound token (5 minutes) for invoking an Evervault Function with a given payload. Run Tokens can be used to invoke an Evervault Function client-side without providing a sensitive API Key.
evervault.create_client_side_decrypt_token(payload, expiry)
Client Side Decyrpt Tokens are versatile and short-lived tokens that frontend applications can utilise to decrypt data previously encrypted through Evervault. Client Side Decrypt Tokens are restricted to specific payloads.
By default, a Client Side Decrypt Token will live for 5 minutes into the future. The maximum time to live of the token is 10 minutes into the future.
The payload containing encrypted data that the token will be used to decrypt.
Response
When you create a Run Token, the SDK will return a JSON object containing your token.
Run Tokens can then be used to authenticate Function runs from the client-side.
evervault.enable_outbound_relay(options)
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.
Requests sent to any of the domains listed will be proxied through Outbound Relay. This will override the configuration created using the Evervault dashboard.
The aiohttp client session to enable outbound relay on. Requires Python 3.11+.
evervault.cage_requests_session(cage_attestation_data)
Returns a Requests
session with will attest your Cage during the TLS handshake.
By default the client will attest the Cage using the attestation document but will not make any assertions about the values of the PCRs. The attestation can be further scoped to the software running in your enclave by passing a dict
mapping Cage names to their corresponding PCRs.