Module Bytesrw_crypto.Hash

Generic and dedicated message digests (hashes).

Warning. Before using a hash algorithm, check it is Bytesrw_crypto.Hash.Algorithm.is_supported otherwise panics are raised on usage.

Dedicated modules. If you need to manipulate hash values of a specific algorithm beyond a simple check it's better to use a dedicated module. By giving a proper type for its hash values it makes it for clearer code and avoid possible mixups. For example here is a dedicated module for algorithm Sha_384:

module Sha_384 = Bytesrw_crypto.Hash.Make
   (struct let algorithm = Bytesrw_crypto.Hash.Algorithm.Sha_384 end)

A few predefined hash modules are provided for hashes in widespread use in 2025.

Hash algorithms

module Algorithm : sig ... end

Hash algorithm identifiers.

Hashes

type t

The type for generic hashes. These hashes are not tied to an algorithm. Values of this type just represent the result of any hash algorithm as a sequence of bytes. Use a dedicated module to work with a particular type hash.

val length : t -> int

length h is the length of hash h. See also Algorithm.length.

module State : sig ... end

Hash state.

val value : State.t -> t

value state is the hash of state.

Warning. This must be called only once. It has an effect on state. Trying to do the following operations afterwards raises Bytesrw_crypto.Panic exceptions:

val verify_value : State.t -> t -> bool

verify_value state h checks in constant time that value state is equal to h.

Warning. This has all the caveats of value.

Hashing

val string : Algorithm.t -> string -> t

string alg s is the alg hash of s.

val bytes : Algorithm.t -> bytes -> t

bytes alg b is the alg hash of b.

slice alg s is the alg hash of the bytes in the range of s.

reader alg r is the alg hash of stream r. This consumes the reader. See also reads.

Hashing streams

See also this cookbook entry.

reads state r is hr with:

  • hr a reader that taps the reads of r to update state.
  • state, the hash state to udpate.

To get the final hash result use value on state once.

writes state w is hw with:

  • hw a writer that taps the writes to update state before giving them to w.
  • state, the hash state to udpate.

To get the final hash result use value on state once.

Predicates and comparisons

val verify_equal : t -> t -> bool

verify_equal h0 h1 uses Verify.equal_strings to assert the equality of h0 and h1. Raises Invalid_argument if the hashes length is not positive and equal.

val equal : t -> t -> bool

equal h0 h1 is true iff h0 and h1 are equal.

Warning. This uses String.equal which does not order the strings in constant time. If you know the hashes are of the same length use verify_equal. Note that dedicated hash modules use Verify.equal_string for their T.equal function.

val compare : t -> t -> int

equal is a total order on hashes compatible with equal.

Warning. This uses String.compare which does not order the strings in constant time.

Converting

val to_binary_string : t -> string

to_binary_string h is a big-endian binary representation of h of length length.

val of_binary_string : ?check_length:int -> string -> (t, string) Stdlib.result

of_binary_string s is a hash from the big-endian binary representation stored in s. If check_length is specified, errors if the hash is not length bytes.

val to_hex : t -> string

to_hex h is the binary representation of h using lowercase US-ASCII hex digits.

val of_hex : ?check_length:int -> string -> (t, string) Stdlib.result

of_hex s parses a sequence of hex digits into a hash. If check_length is specified, errors if the resulting hash has not check_length bytes.

val pp : Stdlib.Format.formatter -> t -> unit

pp formats hashes for inspection.

Dedicated modules

module type T = sig ... end

The type for dedicated hash modules.

module type ALGORITHM = sig ... end

The type for hash algorithm specification.

module Make (Algorithm : ALGORITHM) : T

Make (A) is a hash module for the hashes of the algorithm specifed by A.