Primitives
Functions
Evervault Functions are secure serverless functions which allow you to process data encrypted with Evervault Encryption.
When you pass encrypted data to a Function, it is automatically decrypted by the Function’s runtime. You can then process this data by running custom logic written in Node.js or Python as you normally would, but without ever handling it in plaintext on your infrastructure.
For more complex processes, processes requiring more compute resources, or processes that have longer running times, check out Evervault Enclaves — the easiest way to build, deploy and scale Secure Enclaves.
Deploying 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.
- Sign in to the Evervault Dashboard
- Create or open an App and navigate to the Functions tab
- Click Create Function
- Select "Choose template"
- Authenticate with GitHub
- Select a starter template and deploy your Function
Alternatively, if you have Function code ready in a GitHub repository which you would like to deploy, you can select "Import repository" at Step 4 above. Note that in this case the repo must contain a function.toml file.
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.
function.toml
Evervault Functions are configured using a function.toml configuration file which can be committed to source control. Simply provide a function.toml file in the root of your repository and Evervault will automatically include it at build time.
The format of a function.toml is as follows:
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.
If there are any issues with your dependencies, for example if you have missed one in your package.json, an InitializationError will be thrown.
Environment Variables
Environment Variables for a Function can be configured using either the Evervault Dashboard 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 variables in the Evervault Dashboard, navigate to Function -> Environment Variables. Alternatively use the ev function env command in the CLI.
Secrets are available in plaintext in the Function handler, but will be in their encrypted form when accessed from anywhere else within the Function.
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.
Running a Function
Functions can be invoked using our server-side SDKs, our CLI or using our REST API. The JSON payload included in the request will be decrypted before being passed to the Function handler.
Run Tokens
In each of the examples above, we have used an API Key for authentication. However, these API Keys are sensitive and should not be used client-side. When invoking Functions from frontend applications, we recommend using a Run Token.
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.
Run Tokens can be created using the Evervault server-side SDKs or the REST API.
Once created, Run Tokens can be used to invoke an Evervault Function client-side without providing a sensitive API Key.
Function Responses
The response from a Function run request will contain an id and a status field. The id is a unique identifier for this Function invocation which can be used to search for the invocation in the Function's Activity log. The status field will be either success or failure, depending on whether the function completed successfully or not.
Success
On a successful run, any payload returned from the Function will be contained within the result of the response object.
Failure
If there is a failure in the course of a Function run, the response will contain an error object with a message and stack field. The message field will contain a human readable error message, and the stack field will contain a stack trace of the error.
Functions that have been idle for extended periods of time may return FunctionNotReady HTTP 409 errors. This can be resolved by retrying the request. See the Functions API reference for the full specification.
Restricted Value Error
If you are a PCI customer, your Functions will be running in PCI mode. This is a restricted mode in which returning plaintext card numbers in the response will result in a error.
If it's required that you return card numbers to your users then Evervault Reveal may be a better choice. If you need the card number returned for some other reason, you can encrypt the card number inside the function before returning it.
Initialization Error
If there is an error during the initialization of your Function, for example if there's a syntax error or a dependency is not included in the package.json, the response will contain an error object with a message and stack field as follows:
Resource Limits
Evervault Functions have a maximum memory consumption of 1024MB, 2 available CPU cores and 512MB of ephemeral filesystem storage. 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.
If you require more memory or CPU cores, check out Evervault Enclaves — the easiest way to build, deploy and scale Secure Enclaves.
Execution Time
Evervault Functions have a default execution time of 30 seconds. This can be increased to a maximum of 55 seconds (for synchronous invocations) by setting the timeout in the function.toml.
Asynchronous Function runs up to 900 seconds (15 minutes) are also permitted. To execute a Function in async mode, you must set the async flag on your request payload to true.
Asynchronous Function results can be sent to a destination of your choice by creating a Webhook that is subscribed to the function.run.completed event. Webhooks can be configured via the Webhooks API or in the Evervault Dashboard in the Settings section.
Scalability
Evervault Functions scale automatically to many thousands of requests per second without a noticeable drop in throughput or latency.
Networking
Limiting access to your Function
By default, Functions will respond to requests invoked from any client with a valid Evervault API key or Run Token. By adding an IP address to the Inbound Whitelist in the Dashboard, your Function will only be invoked when a request is made from a whitelisted IP address.
Limiting egress from your Function
By default, Functions can send requests to any third-party endpoint.By adding a domain name to the Outbound Whitelist in the Dashboard, your Function will only have network access to the hostnames you specify.
Observability
Function Logs
Function execution logs are captured by Evervault. The logs can be viewed and queried within the Evervault dashboard, along with metrics derived from these logs.
Integration with Datadog
Support for Datadog in Functions is currently in preview. Contact us at support@evervault.com to get access.
You can enable support for Datadog for your Team's Functions in the Evervault dashboard, on the Team Settings page under the "Integrations" heading.
Clicking configure on the Datadog integration will present you with a modal to enter the Datadog site that you want your logs to be forwarded to, as well as an input for the Datadog token. We recommend you use a Client Token as Evervault will only send logs. Client Tokens can be generated in the Datadog dashboard on the "Organization Settings" page, under the "Access" heading.
Evervault will submit a log to verify the integration. This log can be ignored.
Once you have configured the Datadog integration in the dashboard, your Function logs should begin to be forwarded to your Datadog instance. The logs forwarded from Evervault are structured, and can be used to derive custom metrics.