# Ruby

_Use the Evervault Ruby SDK to encrypt/decrypt data, run Functions, create client tokens, and enable Relay._

> Encrypting/Decrypting data with our backend SDKs may expose you to greater
>   compliance burden because your server needs to handle plaintext data. Instead,
>   we recommend using [Relay](/relay) or our [Client-Side SDKs](/sdks) to encrypt
>   data.

## Getting started

### Install the SDK

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

### Initialize the 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](https://app.evervault.com).

### Encrypt a string

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

```ruby
encrypted = Evervault.encrypt("Hello, world!")
```

## Reference

### encrypt

Encrypts data using [Evervault Encryption](/developers/evervault-encryption). Evervault Strings can be used across all of our products. 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.

```ruby
require "evervault"
Evervault.app_id = "<APP_ID>"
Evervault.api_key = "<API_KEY>"

encrypted = Evervault.encrypt("Hello, world!")
```

**Parameters**

- `data` `String | Boolean | Number | Array | Hash` _(required)_ — The data to encrypt.

### decrypt

Decrypts the data previously encrypted with the `encrypt()` function or through [Relay](/relay). An API key with the `decrypt` permission must be used to perform this operation.

```ruby
require "evervault"
Evervault.app_id = "<APP_ID>"
Evervault.api_key = "<API_KEY>"

encrypted_data = Evervault.encrypt("Hello, world!")
decrypted = Evervault.decrypt(encrypted_data)
```

**Parameters**

- `data` `String | Boolean | Number | Array | Hash` _(required)_ — The data to decrypt.

> **PCI Compliance**
>
> Decrypting data with our backend SDKs is not available if you are part of the PCI or HIPAA compliance use cases. Instead you can:
>
> - Use [Relay](/relay) to decrypt data before it reaches third-party services.
> - Use [Functions](/functions) or [Enclaves](/enclaves) to process encrypted data.

### create_client_side_decrypt_token

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.

```ruby
require "evervault"
Evervault.app_id = "<APP_ID>"
Evervault.api_key = "<API_KEY>"

encrypted_data = Evervault.encrypt("Hello, world!")
five_minutes = Time.now + 300

token = Evervault.create_client_side_decrypt_token(encrypted_data, five_minutes)
```

**Parameters**

- `payload` `String | Boolean | Number | Array | Hash` _(required)_ — The data to decrypt.
- `expiry` `Time` — The time the token will expire. Defaults to 5 minutes in the future.
### run

Lets you invoke an [Evervault Function](/functions) with a given payload.

```ruby
require "evervault"
Evervault.app_id = "<APP_ID>"
Evervault.api_key = "<API_KEY>"

result = Evervault.run("hello-function", {
  "name": "Claude Shannon",
  "ssn": "ev:encrypted_string"
})
```

**Parameters**

- `functionName` `String` _(required)_ — The name of the function to invoke.
- `payload` `Hash` _(required)_ — The payload to pass to the function.

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

```json
{
  "id": "func_run_09413338da56",
  "status": "success",
  "result": {
    "message": "Hello from a Function! It seems you have 14 letters in your name",
    "name": "ev:RFVC:TTLHY04oVJlBuvPx:A7MeNriTKFES0Djl9uKaPvHCAn9PjSfOHu7tswXFCHF9:jwYKE13o3iQlr6Dn/DRk80XpNOGb:$"
  }
}
```

### create_run_token

Creates a single use, time bound token (5 minutes) for invoking an [Evervault Function](/functions) with a given payload. Run Tokens can be used to invoke an Evervault Function client-side without providing a sensitive API Key.

```ruby
require "evervault"
Evervault.app_id = "<APP_ID>"
Evervault.api_key = "<API_KEY>"

run_token = Evervault.create_run_token("hello-function", {
  "name": "Claude Shannon",
  "ssn": "ev:encrypted_string"
})
```

**Parameters**

- `functionName` `String` _(required)_ — Name of the Function the Run Token is for.
- `payload` `Hash` — 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.

When you create a Run Token, the SDK will return a JSON object containing your token.

```json
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsInZlciI6IjAuMCJ9.eyJhcHBVdWlkIjoiYXBwX2RmZGE3MmUwMTZiMCIsImZ1bmN0aW9uTmFtZSI6ImhlbGxvLWNhZ2UtdGFsbC13YWxscy10cmF2ZWwiLCJydW5JZCI6IjRiMjhmMzNlLWU3NjYtNDI2OC1iNmY2LTUyYzZkM2VmMGQzYyIsImV4cCI6MTY2Nzg3Njc2Nn0.gCiFw7UJ8gjZfeXNEaqX4H1Y9HBX9avjioZ4yDU8PTtmGT4QTzVOhnDV46v_yyXLxpO1BgzoBRpYbLciiW1_QXSLmx6cCuJy4vHUZwssHT13vB7AXIl_88Ab5R7w9vpOQIDoCjhPVWJsolwUiiGh_5yE4wGv6WPTIfSv249_hpJLMz3AAffXUckiLPxFporY73KXtTANQH_zniivB91KdBnyGhle7gTs1EXWLqpdMIrqOz9cmoXU31DGd-AgeMzM082s_XtdCFq7FNLLtg6Nx8Mx8Bjl0cKV41R-jbTpHSXxutLX-PSDmWn5wSqDhlQoEWdTLsoS6xp7qhZ2urYyYg"
}
```

Run Tokens can then be used to authenticate Function runs from the client-side.

```javascript
fetch("https://api.evervault.com/functions/[function-name]/runs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `RunToken [run-token]`,
  },
  body: JSON.stringify({
    payload: {
      ssn: "encrypted_string",
    },
  }),
});
```

### enable_outbound_relay

> This should only be used when you need to configure third party SDKs with
>   Relay. All other use cases should call Relay with a HTTP Client.

Configures your application to proxy HTTP requests using [Relay](/relay) based on the configuration created in the Evervault dashboard.

```ruby
Evervault.enable_outbound_relay()
```

**Parameters**

- `decryption_domains` `String[]` — Requests sent to any of the domains listed will be proxied through Relay. This will override the configuration created using the Evervault dashboard.