DocsGuidesSDKsAPI
Dashboard

SDKs

Python SDK

You can use our Python SDK to:

  • Encrypt data server-side
  • Decrypt data server-side
  • Invoke Functions
  • Proxy requests through Relay

Encrypting/Decrypting data with our backend SDKs instead of Relay may expose you to greater compliance burden because your server handles plaintext data.

Instead you can:

  • Use a Relay to encrypt data before it reaches your server.
  • 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.

Parameters
app_idRequiredstr, Default: None

Your App's ID.

api_keyRequiredstr, Default: None

Your App's API Key.

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 Primitives. Evervault File Encryption is currently in Beta, and files can only be decrypted with Relay.

Parameters
dataRequiredstr | dict | bytes | bytearray

The data to encrypt.

evervault.decrypt(data)

evervault.decrypt() 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.

Parameters
dataRequiredstr | list | dict | bytes | bytearray

The data to decrypt.

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 Relay to decrypt data before sending it to third-parties.
  • Use Functions or Enclaves to process encrypted data.

evervault.run(function_name, data, run_async)

evervault.run() lets you invoke an Evervault Function with a given payload.

Parameters
function_nameRequiredstr

Name of the function the run token is for.

payloadRequireddict

Payload for the function.

run_asyncbool

Whether to run the Function asynchronously or not. Callback URL must be configured in the Evervault Dashboard to receive a webhook on Function completion. Asynchronous Function invocations must be enabled for your team by contacting support@evervault.com.

Response

Successful Function runs will return a dictionary containing a Function Run ID and the result from your Function in the following format:

In the case of an asynchronous Function invocation the result will be 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.

Parameters
function_nameRequiredstr

Name of the function the run token is for.

datadict

Payload that the token can be used with. If not provided, a run token will be created, and the payload will not be validated when the function is executed.

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.

Parameters
payloadRequiredstr | list | dict | bytes | bytearray

The payload containing encrypted data that the token will be used to decrypt.

expirydatetime

The time the token will expire. Defaults to 5 minutes in the future.

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 Relay based on the configuration created in the Evervault dashboard. See Relay to learn more.

Asynchronous HTTP requests are supported with aiohttp. Pass in a aiohttp.ClientSession to enable them for that session.

Parameters
decryption_domainsstr[]

Requests sent to any of the domains listed will be proxied through Relay. This will override the configuration created using the Evervault dashboard.

debug_requestsbool

Output request domains and whether they were sent through Relay.

client_sessionaiohttp.ClientSession

The aiohttp client session to enable relay on. Requires Python 3.11+.

evervault.attestable_enclave_session(enclave_attestation_data)

Returns a Requests session with will attest your Enclave during the TLS handshake.

By default the client will attest the Enclave 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 Enclave names to their corresponding PCRs.

Parameters
enclave_attestation_data

Optional constraints to assert that the PCRs present in the Enclave's attestation doc match the expected values. This can be either a single dict, or a list of dicts to allow roll-over between different sets of PCRs.

You can also provide a callback function which returns a set of PCRs for an Enclave. This can make it easier to migrate your clients across Enclave deployments as the PCRs inevitably change.

Using the Evervault API as a PCR Provider

The Evervault API exposes an endpoint to retrieve the PCRs for all active deployments of an Enclave. This can be used to keep your Client in sync with your Enclave across deployments.