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
Digests |
| Size |
'blake2s-128, 'md2, 'md4, 'md5 |
| 16 |
'sha0, 'sha1, 'blake2b-160, 'blake2s-160, 'ripemd160 |
| 20 |
'tiger1, 'tiger2 |
| 24 |
'sha224, 'sha512/224, 'sha3-224, 'blake2s-224 |
| 28 |
'sha256, 'sha512/256, 'sha3-256, 'blake2b-256, 'blake2s-256 |
| 32 |
'sha384, 'sha3-384, 'blake2b-384 |
| 48 |
'sha512, 'sha3-512, 'blake2b-512, 'whirlpool |
| 64 |
'shake128, 'shake256 |
| varies |
Future versions of this library may add other forms of digest specifiers.
procedure
(digest-impl? v) → boolean?
v : any/c
procedure
(get-digest di [factories]) → (or/c digest-impl? #f)
di : digest-spec?
factories : (or/c crypto-factory? (listof crypto-factory?)) = (crypto-factories)
procedure
di : (or/c digest-spec? digest-impl? digest-ctx?)
> (digest-size 'sha1) 20
> (digest-size 'sha256) 32
procedure
di : (or/c digest-spec? digest-impl? digest-ctx?)
> (digest-block-size 'sha1) 64
procedure
(digest-security-strength di cr?)
→ (or/c #f security-strength/c) di : (or/c digest-spec? digest-impl? digest-ctx?) cr? : boolean?
If cr? is true, the result reflects di’s strength in contexts requiring collision resistance (such as digital signatures); if cr? is false, the result reflects di’s strength assuming collision resistance is not required (such as with HMAC).
> (digest-security-strength 'sha1 #t) 0
> (digest-security-strength 'sha1 #f) 128
> (digest-security-strength 'sha384 #t) 192
Added in version 1.8 of package crypto-lib.
procedure
(generate-hmac-key di) → bytes?
di : (or/c digest-spec? digest-impl?)
The random bytes are generated with crypto-random-bytes.
3.1 High-level Digest Functions
procedure
di : (or/c digest-spec? digest-impl?) input : input/c key : (or/c bytes? #f) = #f
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.
> (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
di : (or/c digest-spec? digest-impl?) key : bytes? input : input/c
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
> (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
procedure
(digest-update dctx input) → void?
dctx : digest-ctx? input : input/c
procedure
(digest-final dctx) → bytes?
dctx : digest-ctx?
procedure
(digest-copy dctx) → (or/c digest-ctx? #f)
dctx : digest-ctx?
procedure
(digest-peek-final dctx) → bytes?
dctx : digest-ctx?
procedure
(make-hmac-ctx di key) → digest-ctx?
di : (or/c digest-spec? digest-impl?) key : bytes?
Bibliography
[HMAC] | “RFC 2104: HMAC: Keyed-Hashing for Message Authentication.” http://www.ietf.org/rfc/rfc2104.txt |