▼Crypto:   Cryptographic Operations
►3 Message Digests
On this page:
digest-spec?
digest-impl?
get-digest
digest-size
digest-block-size
generate-hmac-key
3.1 High-level Digest Functions
digest
hmac
3.2 Low-level Digest Functions
make-digest-ctx
digest-ctx?
digest-update
digest-final
digest-copy
digest-peek-final
make-hmac-ctx
Bibliography
  top  ← prev  up  next → 

3 Message Digests

A message digest function (sometimes called a cryptographic hash function) maps variable-length, potentially long messages to fixed-length, relatively short digests. Different digest functions, or algorithms, compute digests of different sizes and have different characteristics that may affect their security.

The HMAC construction combines a digest function together with a secret key to form an authenticity and integrity mechanism [HMAC].

This library provides both high-level, all-at-once digest operations and low-level, incremental operations.

procedure

(digest-spec? v) → boolean?

  v : any/c
Returns #t if v represents a digest specifier, #f otherwise.

A digest specifier is a symbol, which is interpreted as the name of a digest. The following symbols are valid: 'blake2b-160, 'blake2b-256, 'blake2b-384, 'blake2b-512, 'blake2s-128, 'blake2s-160, 'blake2s-224, 'blake2s-256, 'md2, 'md4, 'md5, 'ripemd160, 'sha0, 'sha1, 'sha224, 'sha256, 'sha3-224, 'sha3-256, 'sha3-384, 'sha3-512, 'sha384, 'sha512, 'shake128, 'shake256, 'tiger1, 'tiger2, 'whirlpool. Not every digest name in the list above necessarily has an available implementation, depending on the cryptography providers installed.

Future versions of this library may add other forms of digest specifiers.

procedure

(digest-impl? v) → boolean?

  v : any/c
Returns #t if v represents a digest implementation, #f otherwise.

procedure

(get-digest di [factories]) → (or/c digest-impl? #f)

  di : digest-spec?
  factories : (or/c crypto-factory? (listof crypto-factory?))
   = (crypto-factories)
Returns an implementation of digest di from the given factories. If no factory in factories implements di, returns #f.

procedure

(digest-size di) → exact-positive-integer?

  di : (or/c digest-spec? digest-impl? digest-ctx?)
Returns the size in bytes of the digest computed by the algorithm represented by di.

Examples:
> (digest-size 'sha1)

20

> (digest-size 'sha256)

32

procedure

(digest-block-size di) → exact-positive-integer?

  di : (or/c digest-spec? digest-impl? digest-ctx?)
Returns the size in bytes of the digest’s internal block size. This information is usually not needed by applications, but some constructions (such as HMAC) are defined in terms of a digest function’s block size.

Example:
> (digest-block-size 'sha1)

64

procedure

(generate-hmac-key di) → bytes?

  di : (or/c digest-spec? digest-impl?)
Generate a random secret key appropriate for HMAC using digest di. The length of the key is (digest-size di).

The random bytes are generated with crypto-random-bytes.

3.1 High-level Digest Functions

procedure

(digest di input [#:key key]) → bytes?

  di : (or/c digest-spec? digest-impl?)
  input : input/c
  key : (or/c bytes? #f) = #f
Computes the digest of input using the digest function represented by di. See input/c for accepted values and their conversion rules to bytes.

If di supports keys (eg, the BLAKE2 family of digests), then key is used as the digest key if it is a byte string; if key is #f, the digest is used in unkeyed mode. If di does not support keys (this is true for most digests), then key must be #f or else an error is raised.

Examples:
> (digest 'sha1 "Hello world!")

#"\323Hj\351\23nxV\274B!#\205\352yp\224GX\2"

> (digest 'sha256 "Hello world!")

#"\300S^K\342\267\237\375\223)\23\5Ck\370\2111NJ?\256\300^\317\374\273}\363\32\331\345\32"

procedure

(hmac di key input) → bytes?

  di : (or/c digest-spec? digest-impl?)
  key : bytes?
  input : input/c
Like digest, but computes the HMAC of input using digest di and the secret key key. The key may be of any length, but (digest-size di) is a typical key length [HMAC].

3.2 Low-level Digest Functions

procedure

(make-digest-ctx di [#:key key]) → digest-ctx?

  di : (or/c digest-spec? digest-impl?)
  key : (or/c bytes? #f) = #f
Creates a digest context for the digest function represented by di. A digest context can be incrementally updated with message data.

Examples:
> (define dctx (make-digest-ctx 'sha1))
> (digest-update dctx "Hello ")
> (digest-update dctx "world!")
> (digest-final dctx)

#"\323Hj\351\23nxV\274B!#\205\352yp\224GX\2"

procedure

(digest-ctx? v) → boolean?

  v : any/c
Returns #t if v is a digest context, #f otherwise.

procedure

(digest-update dctx input) → void?

  dctx : digest-ctx?
  input : input/c
Updates dctx with the message data corresponding to input. The digest-update function can be called multiple times, in which case dctx computes the digest of the concatenated inputs.

procedure

(digest-final dctx) → bytes?

  dctx : digest-ctx?
Returns the digest of the message accumulated in dctx so far and closes dctx. Once dctx is closed, any further operation performed on it will raise an exception.

procedure

(digest-copy dctx) → (or/c digest-ctx? #f)

  dctx : digest-ctx?
Returns a copy of dctx, or #f is the implementation does not support copying. Use digest-copy (or digest-peek-final) to efficiently compute digests for messages with a common prefix.

procedure

(digest-peek-final dctx) → bytes?

  dctx : digest-ctx?
Returns the digest without closing dctx, or #f if dctx does not support copying.

procedure

(make-hmac-ctx di key) → digest-ctx?

  di : (or/c digest-spec? digest-impl?)
  key : bytes?
Like make-digest-ctx, but creates an HMAC context parameterized over the digest di and using the secret key key.

Bibliography

[HMAC] “RFC 2104: HMAC: Keyed-Hashing for Message Authentication.” http://www.ietf.org/rfc/rfc2104.txt

  top  ← prev  up  next →