toc

Ruby SDK

A full reference of our Ruby SDK.

You can use our Ruby SDK to:

  1. Encrypt data at your server
  2. Run your Cages

You can use our Ruby SDK to encrypt data — rather than with Relay — and still send it to a third-party via Relay. Encrypting with our backend SDKs is best for developers who want to avoid the network latency of Relay and/or want to avoid sending plaintext data to Relay to be encrypted.

Encrypting data with our backend SDKs instead of Relay may expose you to greater compliance burden because plaintext data touches your server before it is encrypted. If you want to avoid sending plaintext data to Relay and want to reduce your compliance burden — by never having plaintext data touch your infrastructure — using our frontend SDKs to encrypt in the browser or on the client is best.

You don’t need to change your database configuration. You can store Evervault-encrypted data in your database as you would the plaintext version.

Installation

Install the Ruby SDK.

  • Gemfile
  • Install it yourself

Add this line to your app's Gemfile:

ruby
gem "evervault"

And then execute:

bash
bundle install

Initialization

Evervault can be initialized in two ways:

  1. As a singleton
  2. Manually

The singleton pattern is recommended because reusing your Evervault client prevents additional overhead of loading keys at Cage runtime.

ruby
require "evervault"
# Initialize the client with your team’s API key
Evervault.api_key = "<YOUR_API_KEY>"
# Encrypt your data
encrypted = Evervault.encrypt({ name: "Alice" })
# Process the encrypted data in a Cage
result = Evervault.run("demo-cage", encrypted)

You can manually initialize different clients at different times. For example, if you have multiple Evervault teams and need to switch context.

ruby
require "evervault"
# Initialize the client with your team's API key
evervault = Evervault::Client.new(api_key: "<YOUR_API_KEY>")

Reference

The Evervault Ruby SDK exposes two methods:

  • Evervault.encrypt
  • Evervault.run

Evervault.encrypt

Evervault.encrypt encrypts data for use in your Cages. To encrypt data on your server, simply pass a Hash or String into the Evervault.encrypt method. Store the encrypted data in your database as normal.

ruby
Evervault.encrypt(data = Hash | String)
ParameterTypeDescription
dataHash or StringData to be encrypted

Evervault.run

Evervault.run lets you invoke a Cage with a given payload.

ruby
Evervault.run(cage_name = String, data = Hash[, options = Hash])
ParameterTypeDescription
cage_nameStringName of the Cage to be run
dataHashPayload for the Cage
optionsHashOptions for the cage run.
OptionTypeDefaultDescription
asyncBooleanfalseRun your Cage in async mode. Async Cage runs will be queued for processing.
versionIntegernilSpecify the version of your Cage to run. By default, the latest version will be run.