Erebus (Erebus v0.2.0-rc.2) View Source

This is the entry point for the Erebus library. Here you will find operations for both encrypting and decrypting fields in the database.

Erebus is an implementation of the envelope encryption paradigm. For each encrypted struct, it uses a separate key called DEK (short for data encryption key). That key is encrypted using KEK (key encryption key).

The DEK is a symmetric key (Erebus uses AES-256 with Galois mode (AES-GCM) with AEAD), which guarantees both security and integrity of the data. The KEK is an asymmetric key - Erebus uses the public key for encryption (for performance reasons when using external key storage) and the private for decryption. The specific implementation depends on the backend.

Currently, there are three supported backend implementations:

  • Erebus.KMS.Google - Google KMS key storage. Your private key never leaves Google infrastructure, which is the most secure option
  • Erebus.KMS.Local - private/public key pair stored on your hard drive. Please note that it makes your keys prone to leakage
  • Erebus.KMS.Dummy - base64 as encryption for DEK. Never use it in production

Please note that you need to provide the config for the operations and call them, providing them for each call.

The preferred way of running it is with your wrapper, like:

defmodule MyApp.Erebus do
  def encrypt(struct, handle, version) do
    opts = Application.get_env(:my_app, :erebus)

    Erebus.encrypt(struct, handle, version, opts)
  end

  def decrypt() do
    opts = Application.get_env(:my_app, :erebus)
  end
end

while providing config in your app config file, e.g. for Google KMS:

config :my_app, :erebus,
  kms_backend: Erebus.KMS.Google,
  google_project: "someproject",
  google_region: "someregion",
  google_keyring: "some_keyring",
  google_goth: MyApp.Goth

or when using a local key file:

config :my_app, :erebus,
  kms_backend: Erebus.KMS.Local,
  keys_base_path: "/tmp/keys",
  private_key_password: "1234"

This also enables you to use a different Erebus config for less important data (e.g. local keys) and the higher security Google KMS where you need it.

Link to this section Summary

Functions

This function decrypts your encrypted struct. It takes

This function should be called when you want to encrypt your struct. It takes

reencrypt_dek, when called on an encrypted struct, forces re-encrypting the DEK using the provided KEK backend.

Link to this section Functions

Link to this function

decrypt(struct, fields_to_decrypt, opts \\ [])

View Source

This function decrypts your encrypted struct. It takes:

  • encrypted struct with dek field present
  • list of fields to be decrypted
  • options - providing backend and options for that backend
Link to this function

encrypt(struct, handle, version, opts)

View Source

This function should be called when you want to encrypt your struct. It takes:

  • struct which implements Erebus.Encryption protocol
  • handle for key
  • version of key
  • options - providing backend and options for that backend

One very meaningful option is :force_reencrypt flag, which can be used for re-encrypting all of the fields even when nothing was changed.

Link to this function

reencrypt_dek(struct, handle, version, opts)

View Source

reencrypt_dek, when called on an encrypted struct, forces re-encrypting the DEK using the provided KEK backend.