• Stars
    star
    195
  • Rank 199,346 (Top 4 %)
  • Language
    Elixir
  • License
    MIT License
  • Created almost 6 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Encrypted fields for Ecto

Cloak.Ecto

Coverage Status Build Status

Easily encrypt fields in your Ecto schemas. Relies on Cloak for encryption.

Usage

Cloak.Ecto helps you create Ecto.Type modules which automatically encrypt and decrypt your data. You simply define a type and set the type of your fields, and Cloak.Ecto handles the rest.

defmodule MyApp.Encrypted.Binary do
  use Cloak.Ecto.Binary, vault: MyApp.Vault
end
defmodule MyApp.EctoSchema do
  use Ecto.Schema

  schema "table_name" do
    field :encrypted_field, MyApp.Encrypted.Binary

    # ...
  end
end

When Ecto writes the fields to the database, Cloak encrypts the values into a binary blob, using a configured encryption algorithm chosen by you.

iex> Repo.insert!(%MyApp.EctoSchema{encrypted_field: "plaintext"})
08:46:08.862 [debug] QUERY OK db=3.4ms
INSERT INTO "table_name" ("encrypted_field") 
VALUES ($1) RETURNING "id", "encrypted_field" [
  <<1,10, 65, 69, 83, 46, 67, 84, 82, 46, 86, 49, 
    69, 92, 173, 219, 203, 238, 26, 58, 236, 5, 
    104, 23, 12, 10, 182, 31, 221, 89, 22, 58, 
    34, 79, 109, 30, 70, 254, 56, 93, 102, 84>>
]

Likewise, when Ecto reads the encrypted blob out of the database, Cloak will automatically decrypt the value into the intended data type at runtime.

iex> Repo.get(MyApp.EctoSchema, 1)
%MyApp.EctoSchema{encrypted_field: "plaintext"}

For complete usage instructions, see the Hex documentation.

Troubleshooting

See our troubleshooting guide for solutions to common issues.

Notable Features

  • Transparent, easy to use encryption for database fields
  • Fully compatible with umbrella projects
  • Bring your own encryption algorithm, if you want
  • Mix task for key rotation: mix cloak.migrate

Security Notes

  • Supported Algorithms: Cloak's built-in encryption modules rely on Erlang's :crypto module. Cloak supports the following algorithms out of the box:

    • AES.GCM
    • AES.CTR
  • Encrypted Data Not Searchable: Cloak uses random IVs for each ciphertext. This means that the same value will not encrypt to the same value twice. As a result, encrypted columns are not queryable. However, Cloak does provide easy ways to create hashed, searchable columns.

  • Runtime Data is not Encrypted: Cloak encrypts data at rest in the database. The data in your Ecto structs at runtime is not encrypted.

  • No Support for User-specific Encryption Keys: Cloak's Ecto.Type modules do not support user-specific encryption keys, due to limitations on the Ecto.Type behaviour. However, you can still use Cloak's ciphers to implement these in your application logic.

Use Without Ecto

If you want to use Cloak without Ecto, see cloak instead.

Local Development

To develop this library locally, you will need to install the correct version of Elixir and Postgres. The easiest way to set everything up is with Docker and docker-compose:

$ cd cloak_ecto
# Runs the bin/test script in the context of Docker
$ docker-compose run code bin/test
# To access a terminal with mix, use this command:
$ docker-compose run code bash
# Run any command of your choosing:
root@234098234oij:/app# mix docs

More Repositories

1

cloak

Elixir encryption library designed for Ecto
Elixir
564
star
2

elasticsearch-elixir

No-nonsense Elasticsearch library for Elixir
Elixir
421
star
3

ex_twilio

Twilio API client for Elixir
Elixir
334
star
4

number

ActionView::Helpers::NumberHelper for Elixir
Elixir
223
star
5

immortal

Helper modules for OTP applications
Elixir
176
star
6

destructure

Javascript-style destructuring for Elixir
Elixir
110
star
7

mithril

An Elixir architecture-in-a-box for a backend server. Supports GraphQL, Authority authentication, and more.
Elixir
80
star
8

telephonist

Elixir state machines for Twilio calls
Elixir
41
star
9

ex_twiml

Generate TwiML with Elixir
Elixir
37
star
10

travis_elixir_plts

Pre-built Dialyzer Persistent Lookup Tables for Travis and Elixir
16
star
11

ecto_validation_case

Simplify your Ecto validation tests
Elixir
11
star
12

giphy

Elixir wrapper for Giphy API
Elixir
6
star
13

async

Async/Await pattern for Elixir
Elixir
5
star
14

rspec_best_practices

A collection of Markdown docs describing how best to test your code using RSpec
5
star
15

phoenix_ecto_encryption_sample

A sample Phoenix app demonstrating how to encrypt data using Ecto
CSS
5
star
16

twiliomenu

A gem for moving twilio code into the model
Ruby
4
star
17

delegate_with_docs

Delegate functions while preserving their docs
Elixir
3
star
18

travis_elixir_plt_generator

Generate PLTs on Travis infrastructure, then upload to S3
Elixir
3
star
19

stripity_stripe

Elixir
2
star
20

try_git

1
star
21

danielberkompas

1
star
22

spacemacs-dberkom

Emacs Lisp
1
star
23

mithril_blog

An example blog using the proposed Mithril architecture
Elixir
1
star