Products

Functions

Evervault Functions lets you process data encrypted with Evervault Encryption using secure serverless functions, which are hosted on Evervault’s infrastructure and written in Node.js or Python.

Any encrypted data that is passed to a Function is decrypted by the Function’s runtime. This allows you to process and run logic on that data as you normally would — without handling it in plaintext on your infrastructure. Functions also support network requests to third-party APIs, for instance, where your data needs to be manipulated before or after being shared.

For more complex processes, processes requiring more compute resources or processes that have longer running times check out Evervault Cages — the easiest way to build, deploy and scale Secure Enclaves.


Getting Started

Get up and running with Evervault Functions in less than 5 minutes.

In this example, we will deploy an Evervault Function and call it using one of our server-side SDKs. Before starting this tutorial, you'll need to sign up for an Evervault account and create an App.

Deploy a Function

You can deploy a Function by connecting to a GitHub repository or using the Evervault CLI.

The quickest way to deploy your first Evervault Function is by signing into the Evervault Dashboard and creating a starter template Function by connecting your GitHub account.

  1. Sign in to the Evervault Dashboard
  2. Create or open an App and navigate to the Functions tab
  3. Click Create Function
  4. Select "Import repository" or "Choose template"
  5. Authenticate with GitHub
  6. Select a starter template and deploy your Function

Deployment failures often occur due to issues with the function.toml, package.json, or requirements.txt files. To prevent such failures, verify that these files are present or do not contain any invalid syntax.

Run your Function

Congratulations! You have successfully created and deployed your first Function.

Functions can be invoked using our server-side SDKs, our CLI or by sending an HTTPS request.

Try out any of the examples below to test your new Function!

1
const Evervault = require('@evervault/sdk');
2
const evervault = new Evervault('<APP_ID>', '<API_KEY>');
3
4
(async () => {
5
const encryptedName = await evervault.encrypt("Claude Shannon");
6
const result = await evervault.run("hello-function", {
7
name: encryptedName
8
});
9
10
console.log(result);
11
})();

Encryption within a Function

An encrypt function is available within your Function and can be accessed through the context parameter. This allows you to encrypt data in your response using your App’s keys.

The below examples demonstrate how to use the encrypt Function in Node and Python.

1
exports.handler = async (data, context) => {
2
return {
3
secret: await context.encrypt("Super Secret String"),
4
};
5
};

Functions Response

Any payload returned from a function will be contained within the result of the response object. Along with the result, the runId , a unique identifier for this functions invocation and the appUuid , the identifier of the App this function belongs to are also returned. The runId can be used to search for a functions

1
{
2
"result": {
3
"message":"Hello from a Function! It seems you have 4 letters in your name",
4
},
5
"runId":"ec9f1bd5-425d-47b2-a723-bd9e16a08f18",
6
"appUuid":"app_5ad66g419121"
7
}

Dependencies

When you deploy a Function to Evervault, we will locate your package.json or package-lock.json (for Node.js) and requirements.txt file (for Python) and install any non-development dependencies.

For Node.js Functions, if a node_modules folder is included then dependency installation will be skipped; this can be used to include private dependencies.

Resource Limits

What are the resource limits of Functions?

Evervault Functions currently have a maximum memory consumption of 1024MB, however this can be increased to 10,240MB on request. They currently have 2 available CPU cores, but this can also be increased to 6 cores.

Functions have 512MB of ephemeral filesystem storage available by default, which can be increased to 10,240MB on request. However, using ephemeral storage is not recommended for sensitive data, as it cannot be guaranteed that data won't be available to a future invocation — increasing the risk of an accidental data leak.

What is the maximum execution time of a Function?

Evervault Functions currently have a maximum of 30 seconds execution time due to their request-response serverless architecture.

By passing an X-Async header to the Function Run endpoint or by passing async: true as an option to the Function Run functions in our SDKs, you can run Functions for up to 15 minutes as a background job.

Functions running in async mode will not return a response, and all function output must be explicitly passed from the Function to another endpoint.

How scalable are Evervault Functions?

Evervault Functions will scale automatically to many thousands of requests per second without a noticeable drop in throughput or latency. We are actively improving Function latency and scalability for more intense workloads and see this as a core priority for our product roadmap.

Networking

Can I limit who can send requests to my Functions?

Evervault Functions has an Inbound Whitelist feature which lets you create a list of IP addresses that can invoke your Function.

By default, Functions will respond to requests invoked from any client with a valid Evervault API key or Run Token. By adding a domain name to the Inbound Whitelist in the Dashboard, your Function will only be invoked when a request is made from a whitelisted IP address.

Can I send requests to external APIs from a Function?

Evervault Functions has an Outbound Whitelist feature which lets you create a list of external hostnames that your Function can send requests to.

By default, Functions can send requests to any third-party endpoint. When sending data to a third-party endpoint via your Function, Evervault ensures that the destination hostname is included in your API Whitelist (if provided).

By adding a domain name to the Outbound Whitelist in the Dashboard, your Function will only have network access to the hostnames you specify.


Run Tokens

Run Tokens are single use, time bound tokens for invoking an Evervault Function with a given payload. Run Tokens will only last for 5 minutes and must be used with the same payload that was used to create the Run Token.

Once created, Run Tokens can be used to invoke an Evervault Function client-side without providing a sensitive API Key.

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

Reference

function.toml

Evervault Functions can be configured using a function.toml configuration file which can be committed to source control. Simply include a function.toml file in the root of your repository and Evervault will automatically include it at build time.

The format of your function.toml is as follows:

1
[function]
2
# Customize your Function's timeout by providing a positive integer value.
3
# The timeout is defined in seconds.
4
# Default: 30
5
# Maximum: 900
6
timeout = 120
7
8
# Customize your Function's entry point by specifying the handler in the form `<FILE>.
9
handler = "main.myFunc"
10
11
# The name of your Function
12
name = "your-function-name"
13
14
# The language of your Function
15
# Node: node@18, node@16
16
# Python: python@3.7, python@3.8, python@3.9
17
language = "node@18"

Default Function Configuration

OptionValue
Node.js VersionVersion 16
function.timeout30 seconds
Memory1024MB
Ephemeral Storage512MB

Environment Variables

Environment Variables for a Function can be configured using either the UI or CLI. Secrets can be encrypted on creation and will be made available to your Function handler in plaintext on startup.

To manage your environment in the UI, navigate to Function -> Environment Variables. Alternatively use the ev function env command in the CLI.

Secrets are only available in plaintext in the Function handler.


Alerts

Alerts allow you to see errors in Slack, Discord or sent to any webhook url of your choice. You can create an alert for your Function inside of the Evervault dashboard by navigating to Function -> Alerts -> Add Alert

Webhooks

When you configure a custom webhook to receive alerts, the following fields will be in the response.

Fields
teamUuid

Unique identifier for your team.

errorMessage

Message explaining what went wrong.

evMessage

Message about where the error has occurred.

timestamp

The time the error occurred.

errorType

The function error code

statusCode

The HTTP response code.

statusGroup

4XX, 5XX or ERR

functionUuid

Unique identifier for your Function.

functionName

The name of your Function.


Error Codes

If you received a failed response from the Function Run API that included an X-Evervault-Error-Code header or if you received a JSON response with an evervaultErrorCode field in the case of programmatic access, you can use this error code reference to help resolve the issue.

Error Codes
initialization-error

The function failed to initialize. This error is commonly encountered when there are problems with your code or when a required import is missing.

Here are some steps you can take to troubleshoot and resolve the issue:

  • Check for Syntax Errors: Make sure that there are no syntax errors in your code. Check for missing parentheses, commas, semicolons, or any other syntax-related issues.
  • Verify Import Statements: Ensure that you have included all the necessary import statements in your code. If you are using a specific package or library, make sure it is present in the appropriate configuration files such as package.json (for Node.js projects) or requirements.txt (for Python projects).
  • Check Package/Dependency Installation: If you are using external packages or libraries, verify that they are installed correctly in your project. You can usually install dependencies by running the appropriate package manager command (e.g., npm install for Node.js or pip install -r requirements.txt for Python).
request-timeout

The function run timed out as it took too long to complete. Ensure all paths in your function complete within the timeout specified in the Functions reference.

decryption-error

There was an issue decrypting the data passed to the function. Ensure that the data being passed to the function was encrypted by the same app that owns the function.

unauthorized

This error indicates that you are not authorized to access the resource you are requesting. Ensure that you have included the correct api key in your request.

bad-request

The server is unable (or refuses) to process the request sent by the client, due to an issue that is perceived by the server to be a client problem.

resource-not-found

The API is unable to find the resource you have requested.

internal-error

There was an issue with the Functions service itself.

forbidden-ip-error

That the IP address of the client which invoked the Function is not present in the IP whitelist. Ensure that your Function’s IP whitelist is correctly defined and includes any tenants that you expect to invoke the Function.

run-token-validation-error

The run token used in the run request is failing to verify. Ensure that the run token being returned from the SDK has not been altered in any way.

run-token-expired

The run token used in the run request has expired. Run Tokens have a time to live of five minutes.

payload-verification-error

The payload in the run request does not match that used to create the run token. Ensure that the same payload is used when creating the run token and running the function.

run-token-used-error

The run token has already been used. Run Tokens are single use only. Generate a new run token to be able to run the function again.

function-not-ready-error

This function hasn't been invoked in a long time and entered an inactive state. This will resolve itself after a few moments; just wait and try your request again.