Kryptonite v0.1.9 Kryptonite.AES View Source
This module allows to easily perform AES related operations, such as generating keys, encrypting and decripting.
Examples
A successful flow of key / iv generation, encryption and decryption can be illustrated such as:
iex> {key, iv} = {generate_key!(), Random.bytes!(16)}
iex> {:ok, cypher} = encrypt_cbc(key, iv, "Message...")
iex> decrypt_cbc(key, iv, cypher)
"Message..."
In GCM mode, the same flow could be performed like so:
iex> {key, iv} = {generate_key!(), Random.bytes!(16)}
iex> ad = "Authentication data used to guard decryption."
iex> {:ok, cypher, tag} = encrypt_gcm(key, iv, ad, "Message...")
iex> decrypt_gcm(key, iv, ad, cypher, tag)
{:ok, "Message..."}
The advantage of GCM Mode is that it lets you know when the message cannot be decrypted properly. In other modes, you just end up with a decrypted garbaged message.
iex> {key, wrong_key, iv} = {generate_key!(), generate_key!(), Random.bytes!(16)}
iex> ad = "Authentication data used to guard decryption."
iex> {:ok, cypher, tag} = encrypt_gcm(key, iv, ad, "Message...")
iex> decrypt_gcm(wrong_key, iv, ad, cypher, tag)
{:error, :decryption_error}
Link to this section Summary
Types
A cypher is a binary of any shape
Initialization vectors must be at least 128 bits
A key is a 256 bit length bitstring
A padded binary can only be multiple of 128 bits long
A cypher tag is a binary of any shape
Functions
Decrypts a cypher
using AES in CBC mode
Decrypts a cypher
using AES in GCM mode
Derives an AES key deterministically based on a password
Encrypt a msg
with AES in CBC mode
Encrypt a msg
with AES in CBC mode
Generates an AES key
Generates an AES key
Link to this section Types
A cypher is a binary of any shape.
Initialization vectors must be at least 128 bits.
A key is a 256 bit length bitstring.
A padded binary can only be multiple of 128 bits long.
A cypher tag is a binary of any shape.
Link to this section Functions
Decrypts a cypher
using AES in CBC mode.
This function must be provided with the same initialization vector iv
that
was used to perform the encryption.
Examples
iex> {key, iv} = {generate_key!(), Random.bytes!(16)}
iex> msg = "Message..."
iex> {:ok, cypher} = encrypt_cbc(key, iv, msg)
iex> msg == decrypt_cbc(key, iv, cypher)
true
Decrypts a cypher
using AES in GCM mode.
Examples
iex> {key, iv} = {generate_key!(), Random.bytes!(16)}
iex> ad = "Auth data..."
iex> {:ok, cypher, tag} = encrypt_gcm(key, iv, ad, "Message...")
iex> decrypt_gcm(key, iv, ad, cypher, tag)
{:ok, "Message..."}
Derives an AES key deterministically based on a password.
Examples
iex> password = "Awesome Passw0rd!"
iex> opts = [salt: "S", rounds: 2]
iex> bit_size(derive_key(password, opts))
256
iex> derive_key(password, opts) == derive_key(password, opts)
true
Encrypt a msg
with AES in CBC mode.
Returns a tuple containing the initialization_vector
, and cypher
.
At a high level encryption using AES in CBC mode looks like this:
key + msg -> iv + cypher
Examples
iex> {:ok, cypher} = encrypt_cbc(generate_key!(), Random.bytes!(16), "Message...")
iex> is_bitstring(cypher)
true
Encrypt a msg
with AES in CBC mode.
Returns a tuple containing the initialization_vector
, and cypher
.
At a high level encryption using AES in CBC mode looks like this:
key + iv + ad + msg -> cypher + tag
Examples
iex> {key, iv} = {generate_key!(), Random.bytes!(16)}
iex> {:ok, cypher, tag} = encrypt_gcm(key, iv, "Auth", "Message...")
iex> is_binary(cypher) and is_binary(tag)
true
Generates an AES key.
Examples
iex> key = generate_key!()
iex> bit_size(key)
256
iex> generate_key!() == generate_key!()
false