munch

# munch

[![Package Version](https://img.shields.io/hexpm/v/munch)](https://hex.pm/packages/munch)
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/munch/)

A fast, portable cryptographic hashing library for Gleam.

Like [`gleam_crypto`](https://hex.pm/packages/gleam_crypto), `munch` uses the
platform's native cryptography implementation where possible. Unlike
`gleam_crypto`, it also works in web browsers by falling back to pure Gleam implementations
when no native option is available.

`munch` supports MD5, SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512, along with
HMAC, constant-time comparison, signed messages, and secure random bytes.
While the API differs in some places to support tree-shaking unused algorithms,
it aims to be largely compatible with `gleam_crypto`.

## Installation

```
gleam add munch@1
```

## Example

```gleam
import munch

pub fn main() {
  // Hash a UTF-8 string and return its base16-encoded digest.
  let digest = munch.hash(munch.sha256, "hello")

  // Authenticate a UTF-8 string and return its base16-encoded HMAC.
  let authentication_code = munch.hmac("message", munch.sha256, "secret")
}
```

## Implementation and performance

Each hash algorithm first attempts to create a native hashing context. On
Erlang and supported server-side JavaScript runtimes, updates and finalization
are handled by the same optimized native cryptography machinery used by the
platform. This keeps the common server path fast while preserving the
incremental API for large inputs.

If native hashing is unavailable, `munch` transparently uses its pure Gleam
implementation. This implementation is not expected to match optimised native
code for large inputs, but matches or is slightly faster than common JavaScript
alternatives, like [crypto-js](https://www.npmjs.com/package/crypto-js).

## Support and development

Development happens on
[Tangled](https://tangled.org/becca.monster/munch). Visit the repository there
for bug reports and contributions.