kangarootwelve_xkcp.rs

A Rust wrapper around the eXtended Keccak Code Package implementation of the KangarooTwelve cryptographic hash function. That implementation includes SSSE3, AVX2, and AVX-512 optimizations, and it detects processor support at runtime. The k12sum sub-crate provides a command line interface.

This package wraps C code via FFI, so you have to have a C compiler installed to build it.

Usage

The k12sum command line utility

k12sum hashes files or data from standard input using KangarooTwelve. To install it:

1. Make sure you have a working C compiler. On Linux and macOS, you can run gcc --version to check that GCC is installed. On Windows, if you don't already have Visual Studio installed, you can install the C++ Build Tools for Visual Studio 2019.
2. Install Rust and Cargo.
3. Run cargo install k12sum.

If rustup didn't configure your PATH for you, you might need to go looking for the installed binary in e.g. ~/.cargo/bin. You can test out how fast KangarooTwelve is on your machine (however see the Performance section below) by creating a big file and hashing it, for example as follows:

```bash

Create a 1 GB file.

head -c 1000000000 /dev/zero > /tmp/bigfile

Hash it with SHA-256.

time openssl sha256 /tmp/bigfile

Hash it with KangarooTwelve.

time k12sum /tmp/bigfile ```

The kangarootwelve_xkcp Rust crate

To use KangarooTwelve from Rust code, add a dependency on the kangarootwelve_xkcp crate to your Cargo.toml. Here's an example of hashing some bytes:

```rust // Hash an input all at once. let hash1 = kangarootwelve_xkcp::hash(b"foobarbaz");

// Hash an input incrementally. let mut hasher = kangarootwelvexkcp::Hasher::new(); hasher.update(b"foo"); hasher.update(b"bar"); hasher.update(b"baz"); let hash2 = hasher.finalize(); asserteq!(hash1, hash2);

// Extended output. OutputReader also implements Read. let mut hasher = kangarootwelvexkcp::Hasher::new(); hasher.update(b"foobarbaz"); let mut outputreader = hasher.finalizexof(); let mut output = [0; 1000]; outputreader.squeeze(&mut output); asserteq!(&output[..32], hash1.asbytes()); ```

Performance

This crate currently builds SIMD optimizations only on x86_64 Linux. Windows and macOS are supported, but they build the slower "generic32" implementation. If you're using this crate to compare benchmarks of different hash functions, you'll need to do it on x86_64 Linux. This might change in a future version.

License

The Rust wrapping code in this project is released into the public domain via CC0. Vendored XKCP code is covered by a mixture of licenses.