Cloak.Ecto

When using Cloak.Ecto, keep the following security constraints in mind:

• Encrypted Data is Not Searchable: Because Cloak uses random Initialization Vectors (IVs) for each ciphertext, the same plaintext will result in different ciphertexts every time. Consequently, you cannot perform direct equality queries (e.g., WHERE encrypted_field = 'value') on these columns. To search encrypted data, you must implement hashed, searchable columns.
• Runtime Data is Plaintext: Encryption only happens at rest in the database. Once the data is loaded into your Elixir application via Ecto, the values in your structs are in plaintext.
• No User-Specific Keys via Ecto.Type: Due to the limitations of the Ecto.Type behaviour, you cannot use user-specific encryption keys directly within the schema field definition. If you need user-specific keys, you must use Cloak's ciphers manually within your application logic.
• Supported Algorithms: Cloak relies on Erlang's :crypto module. Out-of-the-box supported algorithms include AES.GCM and AES.CTR.

To encrypt data, follow these steps:

1. Migration: Add the field as a :binary type in your migration.
2. Schema: Use your custom encrypted type (e.g., MyApp.Encrypted.Binary) for the field.
3. Searching (Optional): To make a field queryable, create a mirrored _hash field using Cloak.Ecto.HMAC and update the changeset to populate it.

# Migration
create table(:users) do
  add :email, :binary
  add :email_hash, :binary
  timestamps()
end

# Schema
defmodule MyApp.Accounts.User do
  use Ecto.Schema
  import Ecto.Changeset

  schema "users" do
    field :email, MyApp.Encrypted.Binary
    field :email_hash, MyApp.Hashed.HMAC
    timestamps()
  end

  def changeset(struct, attrs \ %{}) do
    struct
    |> cast(attrs, [:email])
    |> put_hashed_fields()
  end

  defp put_hashed_fields(changeset) do
    changeset
    |> put_change(:email_hash, get_field(changeset, :email))
  end
end

When introducing Cloak to an existing project, you must migrate unencrypted fields to new encrypted fields. This process involves creating a vault, defining local Ecto types, adding duplicate encrypted fields to your schema, migrating the data, and finally replacing the original fields with the encrypted ones.

Step 1: Setup Vault and Types

1. Ensure a Cloak.Vault is configured as per the installation guide.
2. Create local Ecto types for each field type you wish to encrypt (e.g., MyApp.Encrypted.Binary for strings or MyApp.Encrypted.Map for maps).

Step 2: Add encrypted_* Fields

Add new binary columns to your database table to hold the encrypted data. For example, to encrypt :name and :metadata:

alter table(:users) do
  add :encrypted_name, :binary
  add :encrypted_metadata, :binary
end

Update your Ecto schema to include these new fields using your custom encrypted types. During the migration phase, use a temporary helper function in your changeset to keep the new fields in sync with the old ones:

defmodule MyApp.Accounts.User do
  use Ecto.Schema
  import Ecto.Changeset

  schema "users" do
    field :name, :string
    field :encrypted_name, MyApp.Encrypted.Binary
    field :metadata, :map
    field :encrypted_metadata, MyApp.Encrypted.Map
  end

  def changeset(struct, attrs \ %{}) do
    struct
    |> cast(attrs, [:name, :metadata])
    |> put_encrypted_fields()
  end

  # Temporary function to ensure changes are copied to new fields
  defp put_encrypted_fields(changeset) do
    changeset
    |> put_change(:encrypted_name, get_field(changeset, :name))
    |> put_change(:encrypted_metadata, get_field(changeset, :metadata))
  end
end

Step 3: Copy Data

Run a script in a Mix task or IEx to migrate existing records to the new fields:

MypApp.Accounts.User
|> MyApp.Repo.all()
|> Enum.map(fn user ->
  user
  |> Ecto.Changeset.change(%{
       encrypted_name: user.name,
       encrypted_metadata: user.metadata
     })
  |> MyApp.Repo.update!()
end)

Step 4: Remove Original Fields

Once data is verified, create a migration to remove the unencrypted columns and rename the encrypted columns back to the original names:

alter table(:users) do
  remove :name
  remove :metadata
end

rename table(:users), :encrypted_name, to: :name
rename table(:users), :encrypted_metadata, to: :metadata

Finally, clean up your schema by removing the temporary put_encrypted_fields/1 function and updating the field types to the encrypted versions:

defmodule MyApp.Accounts.User do
  use Ecto.Schema
  import Ecto.Changeset

  schema "users" do
    field :name, MyApp.Encrypted.Binary
    field :metadata, MyApp.Encrypted.Map
  end

  def changeset(struct, attrs \ %{}) do
    struct
    |> cast(attrs, [:name, :metadata])
  end
end

# Full migration workflow is provided in the content summary above.

Cloak.Ecto allows you to create custom Ecto.Type modules that automatically encrypt data before it is written to the database and decrypt it when it is read.

To use it, follow these steps:

1. Define an encrypted type module by using Cloak.Ecto.Binary (or other available types) and specifying your vault.
2. Use that type in your Ecto schema definition.

When you insert a record, the value is stored in the database as an encrypted binary blob. When you fetch the record, Ecto automatically decrypts the blob back into the original plaintext value.

# 1. Define the encrypted type
defmodule MyApp.Encrypted.Binary do
  use Cloak.Ecto.Binary, vault: MyApp.Vault
end

# 2. Use it in your schema
defmodule MyApp.EctoSchema do
  use Ecto.Schema

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

# Usage example:
# Inserting plaintext results in an encrypted blob in the DB
Repo.insert!(%MyApp.EctoSchema{encrypted_field: "plaintext"})

# Fetching results in the original plaintext
Repo.get(MyApp.EctoSchema, 1)
# => %MyApp.EctoSchema{encrypted_field: "plaintext"}