Cloak.AES.CTR

A Cloak.Cipher which encrypts values with the AES cipher in CTR (stream) mode.

Configuration

In addition to the normal :default and :tag configuration options, this cipher takes a :keys option to support using multiple AES keys at the same time.

config :cloak, Cloak.AES.CTR,
  default: true,
  tag: "AES",
  keys: [
    %{tag: <<1>>, key: :base64.decode("..."), default: true},
    %{tag: <<2>>, key: :base64.decode("..."), 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. See encrypt/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.

  • :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}
]

You'll then likely need to recompile the Cloak dependency. 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.

Summary

Callback implementation for Cloak.Cipher.decrypt. Decrypts a value encrypted with AES in CTR mode

Callback implementation for Cloak.Cipher.encrypt. Encrypts a value using AES in CTR mode

Callback implementation for Cloak.Cipher.version. Returns the tag of the current default key

Functions

decrypt(ciphertext)

Callback implementation for Cloak.Cipher.decrypt. Decrypts a value encrypted with AES in CTR mode.

Uses the key tag to find the correct key for decryption, and the IV included in the header to decrypt the body of the ciphertext.

Parameters

  • ciphertext - Binary ciphertext generated by encrypt/2.

Examples

iex> encrypt("Hello") |> decrypt
"Hello"
encrypt(plaintext, key_tag \\ <<1>>)

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 and IV to the beginning of the ciphertext. The format can be diagrammed like this:

+----------------------------------+----------------------+
|              HEADER              |         BODY         |
+------------------+---------------+----------------------+
| Key Tag (1 byte) | IV (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 (1 byte) | IV (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.

Example

iex> encrypt("Hello") != "Hello"
true

iex> encrypt("Hello") != encrypt("Hello")
true
version()

Callback implementation for Cloak.Cipher.version. Returns the tag of the current default key.