Cloak

Cloak makes it easy to encrypt fields in your Ecto schemas.

• Hex Documentation
• How to upgrade from Cloak 0.6.x to 0.7.x

Example

Fields are encrypted with custom Ecto.Type modules which Cloak helps you create.

defmodule MyApp.EctoSchema do
  use Ecto.Schema

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

    # ...
  end
end

When Ecto writes these fields to the database, it 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 field out of the database, it will automatically decrypt the value.

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

Notable Features

• Transparent, easy to use encryption for database fields
• Fully compatible with umbrella projects (as of 0.7.0)
• 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.

Migrating from 0.6.x

Updating to Cloak versions 0.7.0 and higher will require changes to your configuration and Ecto models. Please see the 0.6.x to 0.7.x Migration Guide for a full summary of changes and upgrade instructions.