DocsGuidesReference
Dashboard

Guides

Ruby SDK

You can use our Ruby SDK to:

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

Encrypting data with our backend SDKs instead of Inbound Relay may expose you to greater compliance burden because your server handles plaintext data.

Instead you can:

  • Use an Inbound Relay to encrypt data before it reaches your server.
  • Use an Outbound Relay to decrypt data before it reaches a third-party service.
  • Use our client-side SDKs to encrypt data before sending it to your server.

Quickstart

Install SDK

Our Ruby SDK is distributed via RubyGems, and can be installed via the command line or a Gemfile.

1
$ gem install evervault

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

1
require "evervault"
2
3
Evervault.app_id = "<APP_ID>"
4
Evervault.api_key = "<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 and App ID), run it in your own environment and run the encryption and decryption for yourself.

1
require "evervault"
2
Evervault.app_id = "<APP_ID>"
3
Evervault.api_key = "<API_KEY>"
4
5
encrypted = Evervault.encrypt("Hello, world!")
6
7
puts encrypted
8
9
# Requires an API key with the `decrypt` permission
10
decrypted = Evervault.decrypt(encrypted)
11
12
puts decrypted
13
14
# Send the decrypted data to a third-party API
15
Evervault.enable_outbound_relay
16
uri = URI('https://example.com')
17
req = Net::HTTP::Post.new(uri.path, 'Content-Type' => 'application/json')
18
req.body = encrypted.to_json
19
http = Net::HTTP.new(uri.host, uri.port)
20
http.use_ssl = true
21
res = http.request(req)

Reference

Evervault.encrypt(data)

Encrypts data using Evervault Encryption. Evervault Strings can be used across all of our Primitives. To encrypt data using the Ruby SDK, simply pass a String, Hash or Array into the encrypt() method.

The encrypted data can be stored in your database as normal and can be used with any of Evervault’s other services.

1
require "evervault"
2
Evervault.app_id = "<APP_ID>"
3
Evervault.api_key = "<API_KEY>"
4
5
encrypted = Evervault.encrypt("Hello, world!")
Parameters
dataRequiredString | Hash

The data to encrypt.

Evervault.decrypt(data)

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.

1
require "evervault"
2
Evervault.app_id = "<APP_ID>"
3
Evervault.api_key = "<API_KEY>"
4
5
encrypted_data = Evervault.encrypt("Hello, world!")
6
decrypted = Evervault.decrypt(encrypted_data)
Parameters
dataRequiredString | Number | Boolean | Array | Hash

The data to decrypt.

Decrypting data with our backend SDKs is not available if you are part of the PCI or HIPAA compliance use cases

Instead you can:

Evervault.create_client_side_decrypt_token(payload, expiry)

Client Side Decrypt 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.

1
require "evervault"
2
Evervault.app_id = "<APP_ID>"
3
Evervault.api_key = "<API_KEY>"
4
5
encrypted_data = Evervault.encrypt("Hello, world!")
6
five_minutes = Time.now + 300 
7
8
token = Evervault.create_client_side_decrypt_token(encrypted_data, five_minutes)
Parameters
payloadRequiredString | Number | Boolean | Array | Hash

The payload containing encrypted data that the token will be used to decrypt.

expiryTime

The time the token will expire. Defaults to 5 minutes in the future.

Evervault.run(function_name, data)

Lets you invoke an Evervault Function with a given payload.

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

Name of the function the Run Token is for.

payloadRequiredHash

Payload for the Function.

Response

Successful Function runs will return a hash 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
}

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
require "evervault"
2
Evervault.app_id = "<APP_ID>"
3
Evervault.api_key = "<API_KEY>"
4
5
run_token = Evervault.create_run_token("hello-function", {
6
  "name": "Claude Shannon",
7
  "ssn": "ev:encrypted_string"
8
})
Parameters
function_nameRequiredString

Name of the Function the Run Token is for.

dataHash

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.

bernstein:~$
curl https://api.evervault.com/functions/hello-function/runs \
     -X POST \
     -H 'Authorization: RunToken eyJ..Tg' \
     -H 'Content-Type: application/json' \
	 --data '{"payload": {"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.

1
Evervault.enable_outbound_relay()
Parameters
decryption_domainsString[]

Requests sent to any of the domains listed will be proxied through Outbound Relay. This will override the configuration created using the Evervault dashboard.