View Source Charon.Utils.Crypto (Charon v2.7.1)

Encrypt/decrypt, sign/verify, secure compare binaries etc.

Link to this section Summary

Functions

Constant time memory comparison for fixed length binaries, such as results of HMAC computations.

Decrypt a binary using the provided key and return the plaintext or an error.

Encrypt the plaintext into a binary using the provided key.

Calculate a HMAC of data using key. The algorithm is sha256.

Compare exp_hmac with the HMAC of data given key.

Generate a random URL-encoded string of byte_size bytes.

Sign a binary into a new binary prefixed with a header containing the original binary's url-encoded HMAC. If the input data is a human-readable (UTF-8) string, the result of this function will be too.

Sign a binary into a new binary prefixed with a header containing the original binary's HMAC.

Verify that a binary is signed with a valid signature (by sign_hmac/2 or sign_encoded_hmac/2).

Link to this section Functions

Link to this function

constant_time_compare(bin_a, bin_b)

View Source
@spec constant_time_compare(binary(), binary()) :: boolean()

Constant time memory comparison for fixed length binaries, such as results of HMAC computations.

Returns true if the binaries are identical, false if they are of the same length but not identical. The function raises an ArgumentError if the binaries are of different size.

doctests

Doctests

iex> constant_time_compare(<<0>>, <<0>>)
true
iex> constant_time_compare(<<0>>, <<1>>)
false
@spec decrypt(binary(), binary()) :: {:ok, binary()} | {:error, :decryption_failed}

Decrypt a binary using the provided key and return the plaintext or an error.

@spec encrypt(binary(), binary()) :: binary()

Encrypt the plaintext into a binary using the provided key.

@spec hmac(iodata(), binary()) :: binary()

Calculate a HMAC of data using key. The algorithm is sha256.

doctests

Doctests

iex> <<174, 127, 185, 114, 225, 247, 199, 79, _::binary>> = hmac(["iodata"], "secret")
Link to this function

hmac_matches?(data, key, exp_hmac)

View Source
@spec hmac_matches?(iodata(), binary(), binary()) :: boolean()

Compare exp_hmac with the HMAC of data given key.

doctests

Doctests

iex> data = ["iodata"]
iex> hmac = hmac(data, "secret")
iex> hmac_matches?(data, "secret", hmac)
true
iex> hmac_matches?(data, "other secret", hmac)
false
Link to this function

random_url_encoded(byte_size)

View Source
@spec random_url_encoded(pos_integer()) :: binary()

Generate a random URL-encoded string of byte_size bytes.

doctests

Doctests

iex> random = random_url_encoded(16)
iex> {:ok, <<_::binary>>} = Base.url_decode64(random, padding: false)
Link to this function

sign_encoded_hmac(binary, key)

View Source
@spec sign_encoded_hmac(binary(), binary()) :: binary()

Sign a binary into a new binary prefixed with a header containing the original binary's url-encoded HMAC. If the input data is a human-readable (UTF-8) string, the result of this function will be too.

The output format may change, but will still be verifiable by verify_hmac/2.

doctests

Doctests

iex> sign_encoded_hmac("charon!", "secret")
"signed_u64.MwvpgZ_Tb5P19rltHpsHE_ONQs3dR6Et39Adu34WvsU.charon!"
@spec sign_hmac(binary(), binary()) :: binary()

Sign a binary into a new binary prefixed with a header containing the original binary's HMAC.

The output format may change, but will still be verifiable by verify_hmac/2.

doctests

Doctests

iex> <<"signed.", _hmac::256, ".charon!">> = sign_hmac("charon!", "secret")
Link to this function

verify_hmac(binary, key)

View Source
@spec verify_hmac(binary(), binary()) ::
  {:ok, binary()} | {:error, :invalid_signature | :malformed_input}

Verify that a binary is signed with a valid signature (by sign_hmac/2 or sign_encoded_hmac/2).

doctests

Doctests

# verifies both `sign_hmac/2` and `sign_encoded_hmac/2`
iex> "charon!" |> sign_encoded_hmac("secret") |> verify_hmac("secret")
{:ok, "charon!"}
iex> "charon!" |> sign_hmac("secret") |> verify_hmac("secret")
{:ok, "charon!"}

# returns :invalid_signature error on HMAC mismatch
iex> "charon!" |> sign_encoded_hmac("secret") |> verify_hmac("wrong")
{:error, :invalid_signature}
iex> "charon!" |> sign_hmac("secret") |> verify_hmac("wrong")
{:error, :invalid_signature}

# returns :malformed_input when input binary is of unknown format
iex> verify_hmac("charon!", "secret")
{:error, :malformed_input}