Crypto v0.1.0

Cryptographic hashes, message authentication codes and key derivation

Installation

Add Crypto to the [Dependencies] table of your package's Rux.toml:

[Dependencies]
Crypto = { Namespace = "Rux", Version = "0.1.0" }

Standard packages are declared by hand: the registry does not serve them, so rux add Rux/Crypto cannot add them.

Guide

Cryptographic hashes, message authentication codes and key derivation.

Not published, and not to be published until reviewed. Every algorithm here matches its published test vectors, but passing vectors is not the same as being safe to rely on: the things that go wrong in cryptographic code — a comparison that leaks timing, a secret that outlives its use, a construction used outside the assumptions it was proved under — pass vectors happily. This package is awaiting an independent review by someone who did not write it. Until that review is recorded, treat it as unaudited. The review checklist says what is already established and what to look at first.

What it provides

SHA-2 — SHA-224, SHA-256, SHA-384, SHA-512, and the two SHA-512 truncations.
SHA-3 and SHAKE — the Keccak permutation, the four fixed-size hashes, and the two extendable-output functions.
BLAKE3 — unkeyed, keyed, and derive-key modes, with extendable output.
HMAC and HKDF — generic over any digest, and the two-stage key derivation built on them.
Legacy hashes — LegacyMd5 and LegacySha1, for reading what already exists. Both are broken; neither implements the digest interface, so nothing takes one by accident.
Digests — an incremental contract every algorithm implements, with one-shot forms beside it.
Constant-time comparison — Equal, which takes the same time whichever bytes differ, because the ordinary comparison leaks where the first difference is and that is enough to forge a tag one byte at a time.
Zeroization — Wipe, written so it cannot be optimized away.

Digest, XOF, and HMAC states are structural Copy values: copying a state takes an independent snapshot and owns no external resource. Safe mutation uses &var receivers, and read-only queries use &; calls borrow automatically. Construct default states with type calls such as Sha256(), Sha512(), and Blake3(). Descriptive variants such as Sha256::New224(), Shake::New128(), and Blake3::NewKeyed() retain their names. Raw pointers remain only inside compression helpers and the optimizer barrier, where contiguous word access or an opaque address is intentional.

Index

Interfaces

Name	Summary
`Digest`	An incremental digest.

Types

Name	Summary
`Blake3Chunk`	The state of one chunk being filled.
`Blake3`	An incremental BLAKE3 hash.
`Hmac<D>`	An incremental HMAC over any digest.
`Sha3`	An incremental SHA-3 hash at any of its four sizes.
`LegacyMd5`	An incremental MD5.
`LegacySha1`	An incremental SHA-1.
`Sha256`	An incremental SHA-256 or SHA-224.
`Sha512`	An incremental SHA-512, SHA-384, SHA-512/224 or SHA-512/256.
`Shake`	An extendable-output function: absorb a message, then read as many bytes as wanted.

Functions

Name	Summary
`Blake3Compress`	The compression function: sixteen words of state over seven rounds, producing sixteen words of output.
`Blake3Of`	The BLAKE3 hash of `bytes`, at whatever length `into` asks for.
`Blake3KeyedOf`	The keyed BLAKE3 hash of `bytes` under `key`, in one call.
`Blake3DeriveKey`	A key derived from `material` under `context`, at whatever length `into` asks for.
`Equal`	Whether two byte sequences are equal, in time that does not depend on where they differ.
`Wipe`	Overwrites `bytes` with zeros in a way the compiler may not remove.
`HkdfExtract<D>`	Extracts a pseudorandom key from `material`, salted with `salt`.
`HkdfExpand<D>`	Expands `key` into `into`, separated by `info`.
`Hkdf<D>`	Extract and expand in one call: the whole of HKDF.
`HmacOf<D>`	The HMAC of `message` under `key`, in one call.
`KeccakPermute`	The Keccak-f1600 permutation, applied in place to twenty-five lanes.
`Sha3Of224`	The SHA3-224 digest of `bytes`, in one call.
`Sha3Of256`	The SHA3-256 digest of `bytes`, in one call.
`Sha3Of384`	The SHA3-384 digest of `bytes`, in one call.
`Sha3Of512`	The SHA3-512 digest of `bytes`, in one call.
`LegacyMd5Of`	The MD5 digest of `bytes`.
`LegacySha1Of`	The SHA-1 digest of `bytes`.
`Sha256Of`	The SHA-256 digest of `bytes`, in one call.
`Sha224Of`	The SHA-224 digest of `bytes`, in one call.
`Sha512Of`	The SHA-512 digest of `bytes`, in one call.
`Sha384Of`	The SHA-384 digest of `bytes`, in one call.
`Sha512Trunc224Of`	The SHA-512/224 digest of `bytes`, in one call.
`Sha512Trunc256Of`	The SHA-512/256 digest of `bytes`, in one call.
`Shake128Of`	`into.length` bytes of SHAKE128 over `bytes`, in one call.
`Shake256Of`	`into.length` bytes of SHAKE256 over `bytes`, in one call.

Constants

Name	Summary
`HkdfMaximumBlocks`	The most blocks `Expand` can produce, since its counter is one byte.
`HmacMaximumBlock`	The longest block any supported digest uses, which is what the padded key buffers are sized to.

TimeOrdered

A version 7 UUID: the current time in its leading bits, entropy in the rest.

Digest

An incremental digest.

Edit this page on GitHub