DocsGuides
Dashboard

Reference

Python SDK

You can use our Python SDK to:

  • Encrypt data server-side
  • Invoke Functions
  • Decrypt data through Outbound Relay

Encrypting data with our backend SDKs instead of Inbound Relay may expose you to greater compliance burden because plaintext data touches your server before it is encrypted.

Instead you can:

Quickstart

Install SDK

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

lovelace:~$
pip install evervault

Initialize SDK

Now, let's initialize the SDK using our App's API key. If you don't have one yet, you can get one by creating an App in the Evervault Dashboard.

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

Encrypt a string

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

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

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), run it in your own environment and run the encryption and decryption for yourself.

1
import evervault
2
evervault.init("<API_KEY>")
3
4
encrypted = evervault.encrypt("Hello, world!")
5
6
print(encrypted)

Reference

evervault.init(api_key)

Initializes the SDK with your API Key.

1
import evervault
2
3
evervault.init(
4
    # Your App's API key 
5
    api_key="<API_KEY>", 
6
)
Parameters
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 products. Evervault File Encryption is currently in Beta, and files can only be decrypted with Outbound Relay.

1
import evervault
2
evervault.init(api_key="<API_KEY>")
3
4
# encrypt a string
5
encrypted = evervault.encrypt("Hello, world!")
6
7
# encrypt a file
8
with 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.

evervault.run(function_name, data, options)

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

1
import evervault
2
evervault.init(api_key="<API_KEY>")
3
4
result = evervault.run(
5
    "hello-function",
6
    {
7
        "name": "Claude Shannon",
8
        "ssn": "ev:encrypted_string"
9
    },
10
    {
11
        "async": False,
12
        "version": None
13
    }
14
)
Parameters
function_nameRequiredstr

Name of the function the run token is for.

payloadRequireddict

Payload for the function.

optionsdict

Additional options for running the function.

options.asyncbool, Default: false

Run your Function in async mode. Asynchronous Function runs will be queued for processing and return a 200 OK response saying your run has been queued.

options.versionint, Default: None

Specify the version of your Function to run. By default, the latest version will be run.

Response

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

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

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.

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

Response

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.

lovelace:~$
curl -X POST https://run.evervault.com/hello-function \
     -H 'Authorization: Bearer eyJ..Tg' \
     -H 'Content-Type: application/json' \
     --data '{"name": "Claude Shannon", "ssn": "ev:encrypted_string"}'

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.

1
evervault.enable_outbound_relay()
Parameters
decryption_domainsstr[]

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_requestsbool

Output request domains and whether they were sent through Outbound Relay.

client_sessionaiohttp.ClientSession

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.

For example:

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

Optional constraints to assert that the PCRs present in the Cage'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.

cage_attestation_data.[cageName].pcr0String. Default: None

The PCR0 to use when attesting the given Cage.

cage_attestation_data.[cageName].pcr1String. Default: None

The PCR1 to use when attesting the given Cage.

cage_attestation_data.[cageName].pcr2String. Default: None

The PCR2 to use when attesting the given Cage.

cage_attestation_data.[cageName].pcr8String. Default: None

The PCR8 to use when attesting the given Cage.