Erebus (Erebus v0.2.0-rc.3) 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 optionErebus.KMS.Local
- private/public key pair stored on your hard drive. Please note that it makes your keys prone to leakageErebus.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
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
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.
reencrypt_dek, when called on an encrypted struct, forces re-encrypting the DEK using the provided KEK backend.