munch - v1.0.0

munch

Cryptographic hash functions and related utilities.

Hash Algorithms

md5, sha1, sha224, sha256, sha384, sha512

Block API

hash, hash_bits, hmac, hmac_bits

Stream API

new_hash, new_hmac, update, update_bits, digest, digest_bits

Utils

secure_compare, sign_message, verify_signed_message, strong_random_bytes

Types

Hash

</>

The state of a streaming hash or HMAC calculation.

pub type Hash =
  @internal Hash

HashAlgorithm

opaque </>

A hash algorithm.

Pass one of the algorithm values defined in this module, such as sha256, to functions which accept a HashAlgorithm.

pub opaque type HashAlgorithm

Values

digest

</> 
pub fn digest(hash: Hash) -> String

Finalizes a streaming hash or HMAC calculation and returns its base16 encoded digest.

See new_hash and new_hmac for more information and examples.

digest_bits

</> 
pub fn digest_bits(hash: Hash) -> BitArray

Finalizes a streaming hash or HMAC calculation and returns its binary digest.

See new_hash and new_hmac for more information and examples.

hash

</> 
pub fn hash(algorithm: HashAlgorithm, string: String) -> String

Computes the base16 encoded digest of a UTF-8 encoded string.

Examples

import munch

assert munch.hash(munch.sha256, "a")
  == "CA978112CA1BBDCAFAC231B39A23DC4DA786EFF8147C4E72B9807785AFEE48BB"

To hash content in multiple chunks, see the new_hash function.

hash_bits

</> 
pub fn hash_bits(
  algorithm: HashAlgorithm,
  bits: BitArray,
) -> BitArray

Computes the binary digest of a bit string.

Returns

The digest as a BitArray.

Examples

import gleam/bit_array
import munch

assert munch.hash_bits(munch.sha256, <<"a":utf8>>)
  |> bit_array.base16_encode
  == "CA978112CA1BBDCAFAC231B39A23DC4DA786EFF8147C4E72B9807785AFEE48BB"

To hash content in multiple chunks, see the new_hash function.

hmac

</> 
pub fn hmac(
  data: String,
  algorithm: HashAlgorithm,
  key: String,
) -> String

Computes the base16 encoded HMAC of UTF-8 encoded data using a UTF-8 encoded key.

Examples

import munch

assert munch.hmac("message", munch.sha256, "key")
  == "6E9EF29B75FFFC5B7ABAE527D58FDADB2FE42E7219011976917343065F58ED4A"

To authenticate content in multiple chunks, see the new_hmac function.

hmac_bits

</> 
pub fn hmac_bits(
  data: BitArray,
  algorithm: HashAlgorithm,
  key: BitArray,
) -> BitArray

Computes the binary HMAC of a bit string.

If the key does not contain a whole number of bytes, its final byte is padded with trailing zero bits before use.

Examples

import gleam/bit_array
import munch

assert munch.hmac_bits(<<"message":utf8>>, munch.sha256, <<"key":utf8>>)
  |> bit_array.base16_encode
  == "6E9EF29B75FFFC5B7ABAE527D58FDADB2FE42E7219011976917343065F58ED4A"

To authenticate content in multiple chunks, see the new_hmac function.

md5

</> 
pub const md5: HashAlgorithm

The MD5 hash algorithm.

MD5 is considered weak and should not be used for security purposes. It may still be useful for non-security purposes or for compatibility with existing systems.

new_hash

</> 
pub fn new_hash(algorithm: HashAlgorithm) -> Hash

Initializes the state for a streaming hash digest calculation.

Add data using update_bits or update, then retrieve the digest using digest_bits or digest.

This is useful for hashing streams or large amounts of data without loading all of it into memory at once.

Examples

import munch

let digest =
  munch.new_hash(munch.sha512)
  |> munch.update("data to hash")
  |> munch.update("more data")
  |> munch.digest

new_hmac

</> 
pub fn new_hmac(algorithm: HashAlgorithm, key: BitArray) -> Hash

Initializes a streaming HMAC (hash-based message authentication code).

Add data using update_bits or update, then retrieve the authentication code using digest_bits or digest.

If the key does not contain a whole number of bytes, its final byte is padded with trailing zero bits before use.

secure_compare

</> 
pub fn secure_compare(left: BitArray, right: BitArray) -> Bool

Compares two binaries in constant-time to avoid timing attacks.

For more details see: http://codahale.com/a-lesson-in-timing-attacks/

sha1

</> 
pub const sha1: HashAlgorithm

The SHA-1 hash algorithm.

SHA-1 is considered weak and should not be used for security purposes. It may still be useful for non-security purposes or for compatibility with existing systems.

sha224

</> 
pub const sha224: HashAlgorithm

The SHA-224 hash algorithm.

sha256

</> 
pub const sha256: HashAlgorithm

The SHA-256 hash algorithm.

sha384

</> 
pub const sha384: HashAlgorithm

The SHA-384 hash algorithm.

sha512

</> 
pub const sha512: HashAlgorithm

The SHA-512 hash algorithm.

sign_message

</> 
pub fn sign_message(
  message: BitArray,
  secret: BitArray,
  algorithm: HashAlgorithm,
) -> String

Signs a message which can later be verified using the verify_signed_message function to detect if the message has been tampered with.

A web application could use this verifier to sign HTTP cookies. The data can be read by the user, but cannot be tampered with.

strong_random_bytes

</> 
pub fn strong_random_bytes(length: Int) -> BitArray

Generates a specified number of bytes randomly uniform 0..255, and returns the result in a binary.

On Erlang this uses a cryptographically secure PRNG seeded and periodically mixed with operating system provided entropy. By default this is the RAND_bytes method from OpenSSL. https://erlang.org/doc/man/crypto.html#strong_rand_bytes-1

On JavaScript the WebCrypto API is used.

update

</> 
pub fn update(hash: Hash, str: String) -> Hash

Adds a UTF-8 encoded string to a streaming hash or HMAC calculation.

See new_hash and new_hmac for more information and examples.

update_bits

</> 
pub fn update_bits(hash: Hash, bits: BitArray) -> Hash

Adds binary data to a streaming hash or HMAC calculation.

See new_hash and new_hmac for more information and examples.

verify_signed_message

</> 
pub fn verify_signed_message(
  message: String,
  secret: BitArray,
  algorithm: HashAlgorithm,
) -> Result(BitArray, Nil)

Verifies a message created by the sign_message function.

The hash algorithm must be the same one that was used to sign the message.

✨ Search Document