doc.txt

Digest Jens Axel Søgaard

----------------------------------------------------------------------
  _Digest_                                          Jens Axel Søgaard
----------------------------------------------------------------------

----------------------------------------------------------------------
HISTORY
----------------------------------------------------------------------
2007-feb-03  First release

----------------------------------------------------------------------
INTRODUCTION
----------------------------------------------------------------------

This library provides bindings to the message digest algorithms
in libcrypto. The supported message digests are as follows:
 
  _md2_  _md4_  _md5_ _sha_ _sha1_ _ripemd160_

Functions are provided to calculate the message digest for both
byte strings and ports. Furthermore there is support for incremental
calculation.

Libcrypto is part of the normal distribution of PLT Scheme.

----------------------------------------------------------------------
MESSAGE DIGEST OF BYTE STRINGS
----------------------------------------------------------------------

> md2 : bytes -> string
> md4 : bytes -> string
> md5 : bytes -> string
> sha : bytes -> string
> sha1 : bytes -> string
> ripemd160 : bytes -> string

These functions receive a byte string and returns a string
with each byte represented as two hexadecimal digits:

  > (md5 #"abc")
  "900150983cd24fb0d6963f7d28e17f72"


> md2-bytes : bytes -> bytes
> md4-bytes : bytes -> bytes
> md5-bytes : bytes -> bytes
> sha-bytes : bytes -> bytes
> sha1-bytes : bytes -> bytes
> ripemd160 : : bytes -> bytes

These functions receive a byte string and return a byte string:

  > (md5-bytes #"abc")
  #"\220\1P\230<\322O\260\326\226?}(\341\177r"


> bytes->hex-string : bytes -> string 

Converts a message digest represented as a byte string
into a hexadecimal string.

  > (bytes->hex-string (md5-bytes #"abc"))
  "900150983cd24fb0d6963f7d28e17f72"

----------------------------------------------------------------------
GENERAL MESSAGE DIGEST
----------------------------------------------------------------------

> digest : bytes symbol -> string
> bytes-digest : bytes symbol -> bytes

These functions calculates the message digest of the first argument,
using the algorithm indicated by the symbol.

  > (digest #"abc" 'md5)
  "900150983cd24fb0d6963f7d28e17f72"
  > (digest #"abc" 'sha1)
  "a9993e364706816aba3e25717850c26c9cd0d89d"


> digest-port : port symbol -> string
> bytes-digest-port : port symbol -> bytes

Calculates the message digest of the bytes produces
by reading from the port until the eof-object is reached.

  > (digest-port (open-input-string "abc") 'md5)
  "900150983cd24fb0d6963f7d28e17f72"

----------------------------------------------------------------------
INCREMENTAL CALCULATION OF A MESSAGE DIGEST
----------------------------------------------------------------------

> make-digest-context : symbol -> context
> init-context : context ->
> update-context : context bytes -> 
> final-context->bytes : context -> bytes
> final-contxt->hex-string : context -> string

These functions provide the interface to the incremental
calculation of a message digest.

make-digest-context makes and initializes a new 
message digest context. The function update-context
is called repeatedly with the bytes to be digested.
When all bytes have been digest, wither final-context->bytes
or final-context->hex-string is called to calculate the
final result.

  > (define c (make-digest-context 'md5))
  > (update-context c #"a")
  > (update-context c #"b")
  > (update-context c #"c")
  > (final-context->hex-string c)
  "900150983cd24fb0d6963f7d28e17f72"

The initialization routine init-context makes it
possible to reuse the digest context:

  > (init-context c)
  > (update-context c #"a")
  > (final-context->hex-string c)
  "0cc175b9c0f1b6a831c399e269772661"

And it even works:

  > (md5 #"a")
  "0cc175b9c0f1b6a831c399e269772661"


----------------------------------------------------------------------
KEYWORDS
----------------------------------------------------------------------

Keywords: _message_ _digest_ _hash_ _hashing_ _libcrypto_