Python

Encrypting/Decrypting data with our backend SDKs may expose you to greater compliance burden because your server needs to handle plaintext data. Instead, we recommend using Relay or our Client-Side SDKs to encrypt data.

Getting started

Install the SDK

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

1pip install evervault

Initialize the SDK

The SDK needs to be initialized with an App's ID and API key. If you don't have one yet, you can get one by creating an App in the Evervault Dashboard.

1import evervault
2evervault.init("<APP_ID>", "<API_KEY>")

Encrypt a string

Now that the SDK is initialized, we can encrypt a string.

1encrypted = evervault.encrypt("Hello, world!")

Reference

init

Initializes the SDK with your API Key and App ID.

1import evervault
2
3evervault.init(
4    # Your App's ID
5    app_id="<APP_ID>"
6    # Your App's API key
7    api_key="<API_KEY>",
8)

Parameters

app_idRequiredString
Your Evervault App's ID.
api_keyRequiredString
Your Evervault App's API Key.

encrypt

Encrypts data using Evervault Encryption. To encrypt a string using the Python SDK, simply pass a str or a dict, 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 Relay.

1import evervault
2evervault.init(app_id="<APP_ID>", api_key="<API_KEY>")
3
4## encrypt a string
5encrypted = evervault.encrypt("Hello, world!")
6
7## encrypt a file
8with open("<input-filename>", mode="rb") as plaintext_file:
9  contents = plaintext_file.read()
10  encrypted_contents = evervault.encrypt(contents)
11  with open("<output-filename>", "wb") as encrypted_file:
12    encrypted_file.write(encrypted_contents)

Parameters

dataRequiredstr | dict | bytes | bytearray
The data to encrypt.

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.

1import evervault
2evervault.init(app_id="<APP_ID>", api_key="<API_KEY>")
3encrypted = evervault.encrypt("Hello, world!")
4decrypted = evervault.decrypt(encrypted)

Parameters

dataRequiredstr | list | dict | bytes | bytearray
The data to decrypt.

PCI Compliance

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 it reaches third-party services.
Use Functions or Enclaves to process encrypted data.

run

Lets you invoke an Evervault Function with a given payload.

1import evervault
2evervault.init(app_id="<APP_ID>", api_key="<API_KEY>")
3
4result = evervault.run("hello-function", {
5  "name": "Claude Shannon",
6  "ssn": "ev:encrypted_string"
7})

Parameters

function_nameRequiredstr
The name of the function to invoke.
payloadRequireddict
The payload to pass to 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.

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

1{
2  "id": "func_run_09413338da56",
3  "status": "success",
4  "result": {
5    "message": "Hello from a Function! It seems you have 14 letters in your name",
6    "name": "ev:RFVC:TTLHY04oVJlBuvPx:A7MeNriTKFES0Djl9uKaPvHCAn9PjSfOHu7tswXFCHF9:jwYKE13o3iQlr6Dn/DRk80XpNOGb:$"
7  }
8}

In the case of an asynchronous Function invocation the result will be in the following format:

1{
2  "id": "func_run_09413338da56",
3  "status": "scheduled"
4}

create_run_token

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.

1import evervault
2evervault.init(app_id="<APP_ID>", api_key="<API_KEY>")
3
4result = evervault.create_run_token(
5    "hello-function",
6    {
7        "name": "Claude Shannon",
8        "ssn": "ev:encrypted_string"
9    }
10)

Parameters

function_nameRequiredstr
The name of the function to invoke.
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.

create_client_side_decrypt_token

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.

1from datetime import datetime, timedelta
2import evervault
3
4evervault.init(app_id="<APP_ID>", api_key="<API_KEY>")
5encrypted = evervault.encrypt("Hello, world!")
6now = datetime.now()
7time_in_five_minutes = now + timedelta(minutes=5)
8
9token = evervault.create_client_side_decrypt_token(encrypted_data, time_in_five_minutes)

Parameters

payloadRequiredstr | list | dict | bytes | bytearray
The data to decrypt.
expirydatetime
The time the token will expire. Defaults to 5 minutes in the future.

When you create a Run Token, the SDK will return a JSON object containing your token.

1{
2  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsInZlciI6IjAuMCJ9.eyJhcHBVdWlkIjoiYXBwX2RmZGE3MmUwMTZiMCIsImZ1bmN0aW9uTmFtZSI6ImhlbGxvLWNhZ2UtdGFsbC13YWxscy10cmF2ZWwiLCJydW5JZCI6IjRiMjhmMzNlLWU3NjYtNDI2OC1iNmY2LTUyYzZkM2VmMGQzYyIsImV4cCI6MTY2Nzg3Njc2Nn0.gCiFw7UJ8gjZfeXNEaqX4H1Y9HBX9avjioZ4yDU8PTtmGT4QTzVOhnDV46v_yyXLxpO1BgzoBRpYbLciiW1_QXSLmx6cCuJy4vHUZwssHT13vB7AXIl_88Ab5R7w9vpOQIDoCjhPVWJsolwUiiGh_5yE4wGv6WPTIfSv249_hpJLMz3AAffXUckiLPxFporY73KXtTANQH_zniivB91KdBnyGhle7gTs1EXWLqpdMIrqOz9cmoXU31DGd-AgeMzM082s_XtdCFq7FNLLtg6Nx8Mx8Bjl0cKV41R-jbTpHSXxutLX-PSDmWn5wSqDhlQoEWdTLsoS6xp7qhZ2urYyYg"
3}

Run Tokens can then be used to authenticate Function runs from the client-side.

1fetch("https://api.evervault.com/functions/[function-name]/runs", {
2  method: "POST",
3  headers: {
4    "Content-Type": "application/json",
5    Authorization: `RunToken [run-token]`,
6  },
7  body: JSON.stringify({
8    payload: {
9      ssn: "encrypted_string",
10    },
11  }),
12});

enable_outbound_relay

This should only be used when you need to configure third party SDKs with Relay. All other use cases should call Relay with a HTTP Client.

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.

1evervault.enable_outbound_relay()

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+.

attestable_encalve_session

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.

1# assert that the Enclave was signed with a known cert
2attested_session = evervault.attestable_enclave_session({
3  'my-enclave': { 'pcr_8': '606e2c1cae65ee569799803388d2ca285ad5c325f9d7c0d4a38b3aa30bd729ba96a9a13e64577a622a0a1f050f722123' }
4})
5
6attested_session.post(
7  'https://my-enclave.my-app.enclave.evervault.com',
8  data=sensitive_payload
9)

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.

1import evervault
2import requests
3import json
4
5evervault.init(app_id="app_1234", api_key="my_api_key")
6
7def resolve_pcrs_from_evervault():
8   resp = requests.get('https://api.evervault.com/enclaves/my-enclave/attestation', headers={'x-evervault-app-id': 'app-1234'})
9   payload = json.loads(resp)
10
11   #The API returns PCRs in camelCase, so we convert them to snake_case
12   snake_case_pcrs = {"data": [{k.replace('pcr', 'pcr_'): v for k, v in pcr.items()} for pcr in payload["data"]]}
13   return snake_case_pcrs["data"]
14
15attested_session = evervault.attestable_enclave_session({
16  'my-enclave': resolve_pcrs_from_evervault
17})
18
19attested_session.post('https://my-enclave.app-1234.enclave.evervault.com', headers = { 'api-key': 'my_api_key' })

Python

Parameters

Parameters

Parameters

PCI Compliance

Parameters

Parameters

Parameters

Parameters

Parameters

On this page