# Quickstart: KMS in a Phoenix app This guide assumes you are an Elixir/Phoenix developer who wants field-level encryption in a normal Phoenix application. It starts with a vanilla Phoenix app in `example/phoenix_example`, adds `:kms` as a dependency, configures KMS to start with the app, and encrypts one Ecto schema field through owner-scoped KMS aliases and AAD. KMS uses SQLite by default. The Phoenix app can keep its normal PostgreSQL app database while KMS stores its own key tables in `tmp/kms/kms_dev.sqlite3`. Working example in this repo: ```sh example/phoenix_example ``` Evidence this example works: ```sh cd example/phoenix_example mix ecto.reset mix test # 7 tests, 0 failures ``` ## 1. Start with Phoenix Generate a normal Phoenix application: ```sh mkdir -p example cd example mix phx.new phoenix_example --no-install cd phoenix_example ``` The committed example was generated this way, then patched to act like a standalone app inside this repository. ## 2. Add KMS as a dependency Add KMS to your application's `mix.exs`: ```elixir defp deps do [ {:kms, "~> 0.1.0"}, {:phoenix, "~> 1.8.1"}, # ... normal Phoenix deps ] end ``` The committed `example/phoenix_example` application uses `{:kms, path: "../.."}` so it exercises the repository checkout directly. Start the KMS OTP application with the Phoenix app: ```elixir def application do [ mod: {PhoenixExample.Application, []}, extra_applications: [:logger, :runtime_tools, :kms] ] end ``` The KMS OTP application starts: - the configured KMS repo, delegating to SQLite by default - `KMS.Cache` - session cleanup - optional fallback bootstrap ## 3. Configure Phoenix and KMS repos The example uses two persistence stores: - `PhoenixExample.Repo` for application tables. - KMS SQLite repo for KMS key tables. In `config/config.exs`: ```elixir config :phoenix_example, ecto_repos: [PhoenixExample.Repo, KMS.Repo.SQLite] config :kms, ecto_repos: [KMS.Repo.SQLite] config :kms, KMS.Repo, repo: KMS.Repo.SQLite config :kms, :client, KMS.Client.Local config :kms, :rmk_provider, KMS.RMK.Local config :kms, KMS.RMK.Local, key_path: Path.expand("../priv/kms_rmk_#{config_env()}.key", __DIR__) ``` In `config/dev.exs`, keep Phoenix on PostgreSQL and KMS on SQLite: ```elixir config :phoenix_example, PhoenixExample.Repo, username: "postgres", password: "postgres", hostname: "localhost", database: "phoenix_example_dev" config :kms, KMS.Repo.SQLite, database: Path.expand("../tmp/kms/kms_dev.sqlite3", __DIR__), journal_mode: :wal, foreign_keys: :on, busy_timeout: 5_000, pool_size: 10, priv: "priv/repo", migration_primary_key: false, migration_foreign_key: [type: :text], migration_timestamps: [type: :utc_datetime_usec] ``` KMS can use PostgreSQL too, but SQLite is the simplest embedded/default path. See [Database configuration](database.md). For production, configure a high-entropy `KMS_SESSION_HASH_KEY`, explicit RMK key path or external RMK provider, SQLite database backups, TLS, and crash dump policy. See [Security](security.md) and [Root master keys](rmk.md). ## 4. Create an encrypted Ecto field The example stores documents with encrypted body text: ```elixir defmodule PhoenixExample.Documents.Document do use Ecto.Schema import Ecto.Changeset @primary_key {:id, :binary_id, autogenerate: false} @foreign_key_type :binary_id schema "documents" do field :owner_id, :string field :title, :string field :encrypted_body, :string, redact: true field :body, :string, virtual: true, redact: true timestamps(type: :utc_datetime) end def changeset(document, attrs) do document |> cast(attrs, [:id, :owner_id, :title, :body]) |> maybe_put_id() |> validate_required([:id, :owner_id, :title, :body]) |> validate_length(:owner_id, min: 1, max: 255) |> validate_length(:title, min: 1, max: 255) |> encrypt_body() |> validate_required([:encrypted_body]) end defp maybe_put_id(changeset) do case get_field(changeset, :id) do nil -> put_change(changeset, :id, Ecto.UUID.generate()) _id -> changeset end end defp encrypt_body(%Ecto.Changeset{valid?: true} = changeset) do owner_id = get_field(changeset, :owner_id) document_id = get_field(changeset, :id) body = get_field(changeset, :body) with _kek <- ensure_alias!(owner_id), {:ok, encrypted_body} <- encrypt_body(body, owner_id, document_id) do put_change(changeset, :encrypted_body, encrypted_body) else {:error, reason} -> add_error(changeset, :body, "encryption failed: #{inspect(reason)}") end end defp encrypt_body(changeset), do: changeset def decrypt_body(%__MODULE__{encrypted_body: encrypted_body, owner_id: owner_id, id: document_id}) do KMS.decrypt_alias(encrypted_body, alias_name(owner_id), aad: aad(document_id)) end def alias_name(owner_id), do: "owner:#{owner_id}" def aad(document_id), do: "document:#{document_id}/body" defp ensure_alias!(owner_id) do case KMS.create_alias(alias_name(owner_id)) do {:ok, kek} -> kek {:error, reason} -> raise "failed to ensure KMS alias: #{inspect(reason)}" end end defp encrypt_body(body, owner_id, document_id) do KMS.encrypt_alias(body, alias_name(owner_id), aad: aad(document_id)) end end ``` Migration: ```elixir def change do create table(:documents, primary_key: false) do add :id, :binary_id, primary_key: true add :owner_id, :string, null: false add :title, :string, null: false add :encrypted_body, :text, null: false timestamps(type: :utc_datetime) end end ``` The plaintext `body` field is virtual. The changeset encrypts it into `encrypted_body`; `body` is never persisted in the Phoenix application table. ## 5. Understand alias and AAD policy For this small example, KMS policy lives directly in the `Document` module. Each owner gets one KEK alias, e.g. `owner:alice`. Many documents for the same owner share that KEK. AAD stays field-specific: `document:#{document_id}/body`. It binds encryption/decryption to the `body` field of that document row. Copying `encrypted_body` to another document id does not decrypt. See [Additional authenticated data](aad.md). ## 6. Encrypt transparently in the changeset The changeset owns encryption. The Phoenix context stays boring: ```elixir def create_document(attrs) do Repo.transaction(fn -> case %Document{} |> Document.changeset(attrs) |> Repo.insert() do {:ok, document} -> document {:error, changeset} -> Repo.rollback(changeset) end end) end ``` Reads decrypt before returning to caller: ```elixir def get_document!(id) do Document |> Repo.get!(id) |> with_body!() end ``` Application code passes `body` to the changeset and gets `body` back from the context. The database stores only `encrypted_body`. ## 7. Prove plaintext stays out of the app table The example test proves encryption, owner-scoped aliasing, and AAD binding: ```elixir test "encrypts document body through KMS and decrypts transparently" do assert {:ok, document} = Documents.create_document(%{ owner_id: "alice", title: "Launch notes", body: "Keep this plaintext out of the application table" }) stored = Repo.get!(Document, document.id) assert stored.body == nil refute stored.encrypted_body =~ "Keep this plaintext" assert Documents.get_document!(document.id).body == document.body assert %KMS.Kek{} = KMS.Keks.get_by_alias(Document.alias_name("alice")) end ``` Run it: ```sh cd example/phoenix_example mix deps.get mix ecto.reset mix test ``` Current evidence from this worktree: ```text 7 tests, 0 failures ``` ## 8. Use KMS directly from IEx After setup: ```sh iex -S mix ``` Create and read an encrypted document: ```elixir {:ok, document} = PhoenixExample.Documents.create_document(%{ owner_id: "alice", title: "Private note", body: "only plaintext in app memory" }) PhoenixExample.Documents.get_document!(document.id).body ``` Inspect stored ciphertext: ```elixir stored = PhoenixExample.Repo.get!(PhoenixExample.Documents.Document, document.id) stored.encrypted_body stored.body ``` `stored.body` is `nil`; `stored.encrypted_body` is ciphertext. ## Next steps - Use [AAD](aad.md) consistently for encrypted fields. - Choose and back up an [RMK provider](rmk.md). - Read [Database configuration](database.md) for SQLite/PostgreSQL options. - Read [Security](security.md) before production. - Explore [use cases](use_cases.md), including [standalone KMS](use_cases/standalone.md).