gleam/crypto

Set of cryptographic functions.

Types

HashAlgorithm

pub type HashAlgorithm {
  Sha224
  Sha256
  Sha384
  Sha512
  Md5
  Sha1
}

Constructors

```
Sha224
```
```
Sha256
```
```
Sha384
```
```
Sha512
```
```
Md5
```
The MD5 hash algorithm 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.
```
Sha1
```
The SHA1 hash algorithm 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.

Hasher

</>

pub type Hasher

Functions

digest

</>

pub fn digest(hasher: Hasher) -> BitArray

Finalizes a streaming hash calculation.

See new_hasher for more information and examples.

hash

</>

pub fn hash(algorithm: HashAlgorithm, data: BitArray) -> BitArray

Computes a digest of the input bit string.

Examples

let digest = hash(Sha256, <<"a":utf8>>)

If you wish to to hash content in multiple chunks rather than all at once see the new_hasher function.

hash_chunk

</>

pub fn hash_chunk(hasher: Hasher, chunk: BitArray) -> Hasher

Adds data to a streaming digest calculation.

See new_hasher for more information and examples.

hmac

</>

pub fn hmac(
  data: BitArray,
  algorithm: HashAlgorithm,
  key: BitArray,
) -> BitArray

Calculates the HMAC (hash-based message authentication code) for a bit string.

Based on the Erlang crypto:mac function, or the node:crypto.createHmac function on JavaScript.

new_hasher

</>

pub fn new_hasher(algorithm: HashAlgorithm) -> Hasher

Initializes the state for a streaming hash digest calculation. Then you can add data into the digest algorithm using hash_update function. Finally you use hash_final to retrieve the digest.

It is useful for hashing streams of data or large amount of it without the need to load it all to the memory.

Examples

let hash =
  new_hasher(Sha512)
  |> hash_chunk(<<"data to hash":utf8>>)
  |> digest

secure_compare

</>

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

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

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

sign_message

</>

pub fn sign_message(
  message: BitArray,
  secret: BitArray,
  digest_type: HashAlgorithm,
) -> String

Sign 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(a: 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.

verify_signed_message

</>

pub fn verify_signed_message(
  message: String,
  secret: BitArray,
) -> Result(BitArray, Nil)

Verify a message created by the sign_message function.