cloak v0.6.2 Cloak.AES.GCM View Source
A Cloak.Cipher
which encrypts values with the AES cipher in GCM (block) mode.
Internally relies on Erlang’s :crypto.block_encrypt/4
.
Configuration
In addition to the normal :default
and tag
configuration options, this
cipher take a :keys
option to support using multiple AES keys at the same time.
config :cloak, Cloak.AES.GCM,
default: true,
tag: "GCM",
keys: [
%{tag: <<1>>, key: Base.decode64!("..."), default: false},
%{tag: <<2>>, key: Base.decode64!("..."), default: true}
]
If you want to store your key in the environment variable, you can use
{:system, "VAR"}
syntax:
config :cloak, Cloak.AES.GCM,
default: true,
tag: "GCM",
keys: [
%{tag: <<1>>, key: {:system, "CLOAK_KEY_PRIMARY"}, default: true},
%{tag: <<2>>, key: {:system, "CLOAK_KEY_SECONDARY"}, default: false}
]
If you want to store your key in the OTP app environment, you can use
{:app_env, :otp_app, :env_key}
syntax:
config :cloak, Cloak.AES.GCM,
default: true,
tag: "GCM",
keys: [
%{tag: <<1>>, key: {:app_env, :my_app, :env_primary_key}, default: true},
%{tag: <<2>>, key: {:app_env, :my_app, :env_secondary_key}, default: false}
]
Key Configuration Options
A key may have the following attributes:
:tag
- The ID of the key. This is included in the ciphertext, and should be only a single byte. Seeencrypt/2
for more details.:key
- The AES key to use, in binary. If you store your keys in Base64 format you will need to decode them first. The key must be 128, 192, or 256 bits long (16, 24 or 32 bytes, respectively).:default
- Boolean. Whether to use this key by default or not.
Upgrading to a New Key
To upgrade to a new key, simply add the key to the :keys
array, and set it
as default: true
.
keys: [
%{tag: <<1>>, key: "old key", default: false},
%{tag: <<2>>, key: "new key", default: true}
]
After this, your new key will automatically be used for all new encyption, while the old key will be used to decrypt legacy values.
To migrate everything proactively to the new key, see the mix cloak.migrate
mix task defined in Mix.Tasks.Cloak.Migrate
.
Link to this section Summary
Functions
Callback implementation for Cloak.Cipher.decrypt/2
. Decrypts a value
encrypted with AES in GCM mode
Callback implementation for Cloak.Cipher.encrypt
. Encrypts a value using
AES in CTR mode
Callback implementation for Cloak.Cipher.version/0
. Returns the tag of the
current default key
Link to this section Functions
Callback implementation for Cloak.Cipher.decrypt/2
. Decrypts a value
encrypted with AES in GCM mode.
Uses the key tag to find the correct key for decryption, and the IV and Ciphertag included in the header to decrypt the body of the ciphertext.
Parameters
ciphertext
- Binary ciphertext generated byencrypt/2
.
Examples
iex> encrypt("Hello") |> decrypt
"Hello"
Callback implementation for Cloak.Cipher.encrypt
. Encrypts a value using
AES in CTR mode.
Generates a random IV for every encryption, and prepends the key tag, IV, and Ciphertag to the beginning of the ciphertext. The format can be diagrammed like this:
+----------------------------------------------------------+----------------------+
| HEADER | BODY |
+-------------------+---------------+----------------------+----------------------+
| Key Tag (n bytes) | IV (16 bytes) | Ciphertag (16 bytes) | Ciphertext (n bytes) |
+-------------------+---------------+----------------------+----------------------+
When this function is called through Cloak.encrypt/1
, the module’s :tag
will be added, and the resulting binary will be in this format:
+---------------------------------------------------------------------------------+----------------------+
| HEADER | BODY |
+----------------------+-------------------+---------------+----------------------+----------------------+
| Module Tag (n bytes) | Key Tag (n bytes) | IV (16 bytes) | Ciphertag (16 bytes) | Ciphertext (n bytes) |
+----------------------+-------------------+---------------+----------------------+----------------------+
The header information allows Cloak to know enough about each ciphertext to
ensure a successful decryption. See decrypt/1
for more details.
Important: Because a random IV is used for every encryption, encrypt/2
will not produce the same ciphertext twice for the same value.
Parameters
plaintext
- Any type of value to encrypt.key_tag
- Optional. The tag of the key to use for encryption.
Examples
iex> encrypt("The charge against me is a...") != "The charge against me is a..."
true
iex> encrypt("The charge against me is a...") != encrypt("The charge against me is a...")
true
Callback implementation for Cloak.Cipher.version/0
. Returns the tag of the
current default key.