Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

message-digest

Outdated egg!
message-digest
Documentation
Usage
Examples
Bugs and Limitations
Notes
Requirements
Author
Version history
License

Documentation

Message Digest provides support for message digest primitives. A message-digest is a function taking some input source and returning a fixed-length hash.

For best results the source object(s) to be accumulated into the digest should be something easily treated as a {}{bytevector}}.

Message Digest Primitive

Essentially the reification of a message digest algorithm.

Usage

(use message-digest-primitive)

message-digest-primitive?

[procedure] (message-digest-primitive? OBJ) -> boolean
[procedure] (check-message-digest-primitive LOC OBJ [NAM])
[procedure] (error-message-digest-primitive LOC OBJ [NAM])

message-digest-primitive Accessors

[procedure] (message-digest-primitive-context-info PRIM) -> *
[procedure] (message-digest-primitive-digest-length PRIM) -> fixnum
[procedure] (message-digest-primitive-init PRIM) -> procedure
[procedure] (message-digest-primitive-update PRIM) -> procedure
[procedure] (message-digest-primitive-raw-update PRIM) -> (or #f procedure)
[procedure] (message-digest-primitive-final PRIM) -> procedure
[procedure] (message-digest-primitive-block-length PRIM) -> fixnum
[procedure] (message-digest-primitive-name PRIM) -> symbol

make-message-digest-primitive

[procedure] (make-message-digest-primitive CONTEXT-INFO DIGEST-SIZE INIT! UPDATE! FINAL! [BLOCK-LENGTH] [NAME] [RAW-UPDATE!]) -> message-digest-primitive

Create a message-digest-primitive object, defining a message digest algorithm.

The processing of a message digest is split into three phases: initialization, update, & finalization. These are represented by procedures: INIT!, UPDATE!/RAW-UPDATE!, & FINAL!, respectively.

CONTEXT-INFO: (or (CONTEXT-INFO -> context-object) positive-fixnum)

(CONTEXT-INFO -> CONTEXT) ; returns the context-object, which should be unique. At least the object cannot be shared with another activated primitive.
positive-fixnum : a memory-block of length CONTEXT-INFO bytes is allocated; the memory is automatically free'ed. The context-object here is a {pointer}} to a block of uninitialized memory.

DIGEST-SIZE: positive-fixnum

The count of bytes in the result.

BLOCK-LENGTH: positive-fixnum ; default 4

The primitive's accumulator length in bytes.

NAME: (or symbol string) ; default uninterned-symbol.

Identifies the message digest algorithm. The suggested form is <algorithm>-primitive, 'md5-primitive for example.

INIT!: (CONTEXT -> void))

sets up the CONTEXT.

UPDATE!: (CONTEXT SOURCE COUNT -> void)).

Must accumulate the SOURCE, beginning at 0, for COUNT bytes. Will be called zero or more times. SOURCE is usually an (or blob string) object.
COUNT is the actual number of bytes in the SOURCE. Only the first COUNT bytes in the SOURCE are valid. COUNT is a positive-fixnum.

RAW-UPDATE!: (CONTEXT POINTER COUNT -> void)).

Must accumulate the memory at POINTER, beginning at 0, for COUNT bytes. Will be called zero or more times.
COUNT is the actual number of bytes in the SOURCE. Only the first COUNT bytes in the memory at POINTER are valid. COUNT is a positive-fixnum, limited by (message-digest-chunk-size).

FINAL!: (CONTEXT DESTINATION -> void)).

Must build the message-digest result in the supplied result DESTINATION, which will have a byte-count of at least DIGEST-SIZE. DESTINATION is usually an (or blob string) object.

Message Digest Type

Usage

(use message-digest-type)

Common Argument Definitions

RESULT-FORM is a message-digest-result-form, one of:

'byte-string 'string: the result bytes as a string; these are raw bytes, not characters!
'blob: the result bytes as a blob.
'u8vector: the result bytes as a u8vector.
'hex-string 'hex 'hexstring: the result bytes encoded as a string of lower-case hexadecimal digits.

DIGEST is a message-digest.

ENDIAN is one of 'big-endian, 'little-endian.

SOURCE is a Scheme object.

The buffer argument for the update phase is translated as:

string: buffer is SOURCE.
blob: buffer is SOURCE.
srfi-4-vector: buffer from (...vector->blob/shared SOURCE).
procedure: updates with buffer from (procedure) until #f.
input-port: like procedure above but from ((message-digest-chunk-read-maker) SOURCE).
pointer: buffer is SOURCE, thru the digest primitive raw-update usually.
*: buffer from (message-digest-chunk-converter SOURCE).

Should none of the above interpretations be available then an error is signaled.

A byte-source is one of string, blob, or srfi-4-vector.

message-digest-result-type is (or blob string u8vector)

message-digest-result-form

[parameter] (message-digest-result-form [RESULT-FORM]) -> symbol

The initial RESULT-FORM value is 'hex-string.

A RESULT-FORM of #f resets to the initial value.

initialize-message-digest

[procedure] (initialize-message-digest PRIM) -> message-digest

Returns a new, initialized, message-digest for the supplied algorithm PRIM.

Initialized here means the intialization phase is completed.

message-digest?

[procedure] (message-digest? OBJ) -> boolean
[procedure] (check-message-digest LOC OBJ [NAM])
[procedure] (error-message-digest LOC OBJ [NAM])

message-digest-algorithm

[procedure] (message-digest-algorithm DIGEST) -> message-digest-primitive

Returns the message digest algorithm used by this DIGEST.

Mostly for use when developing an update operation.

Do not mess with this object!

finalize-message-digest

[procedure] (finalize-message-digest DIGEST [RESULT-FORM]) -> message-digest-result-type

Finalize the DIGEST and return the result in the RESULT-FORM.

RESULT-FORM: message-digest-result-form ; default (message-digest-result-form).

Finalize here means the finalization phase is completed. The DIGEST is not in a useful state.

finalize-message-digest!

[procedure] (finalize-message-digest! DIGEST BUFFER) -> message-digest-result-type

Finalize the DIGEST and return the result in the BUFFER.

The BUFFER must be a string, blob, or u8vector of sufficient size; checked at runtime. Does not perform any initialization of the BUFFER.

The result starts at the beginning of the BUFFER, and runs for (message-digest-primitive-digest-length (message-digest-algorithm DIGEST)) bytes. Result is binary only.

Finalize here means the finalization phase is completed. The DIGEST is not in a useful state.

setup-message-digest-buffer!

[procedure] (setup-message-digest-buffer! DIGEST SIZE)

Ensure the DIGEST has a buffer of at least SIZE bytes.

Message Digest Chunk

An inchoate Chunking API.

Usage

(use message-digest-chunk)

;(DEPRECATED)
(use message-digest-parameters)

message-digest-chunk-port-read-maker

[parameter] (message-digest-chunk-port-read-maker [CONSTRUCTOR]) -> procedure

Supplies the procedure used to create an input procedure.

CONSTRUCTOR is a (INPUT-PORT #!optional SIZE) -> (-> byte-source). The first argument is the chunk source port and the second argument is the size of chunks.

The default CONSTRUCTOR will return a procedure that reads from INPUT-PORT in (message-digest-chunk-size) bytes.

message-digest-chunk-fileno-read-maker

[parameter] (message-digest-chunk-fileno-read-maker [CONSTRUCTOR]) -> procedure

Supplies the procedure used to create an input procedure.

CONSTRUCTOR is a FD #!optional SIZE) -> (-> byte-source)). The first argument is the chunk source open fileno and the second argument is the size of chunks.

The default CONSTRUCTOR will return a procedure that reads from FD in (file-size FD) bytes.

message-digest-chunk-size

[parameter] (message-digest-chunk-size [SIZE]) -> positive-integer

The number of bytes to read from a binary-stream during the message-digest update phase. Used by the default message-digest-chunk-read-maker.

SIZE is a positive-integer, with default 1024.

message-digest-chunk-converter

[parameter] (message-digest-chunk-converter [CONVERTER]) -> (or #f procedure)

The procedure used to translate an arbitrary object into something suitable for an UPDATE procedure. See make-message-digest-primitive.

CONVERTER is a (* -> byte-source) or #f.

The default CONVERTER is #f.

Should the CONVERTER be #f or return #f then no translation is attempted.

message-digest-chunk-read-maker (DEPRECATED)

[parameter] (message-digest-chunk-read-maker [CONSTRUCTOR]) -> procedure

Synonym for message-digest-chunk-port-read-maker.

Message Digest BV

Digest routines for string & blob.

Usage

(use message-digest-bv)

message-digest-update-blob

[procedure] (message-digest-update-blob DIGEST BLOB [START [END]])

Update the DIGEST with a BLOB, optionally sliced by START END.

message-digest-update-string

[procedure] (message-digest-update-string DIGEST STRING [START [END]])

Update the DIGEST with a STRING, optionally sliced by START END.

message-digest-string

[procedure] (message-digest-string PRIM STRING [RESULT-FORM [START [END]]]) -> message-digest-result-type

Returns the RESULT for the digest algorithm PRIM applied to STRING, optionally sliced by START END, in the RESULT-FORM.

RESULT-FORM default is (message-digest-result-form).

message-digest-blob

[procedure] (message-digest-blob PRIM BLOB [RESULT-FORM [START [END]]]) -> message-digest-result-type

Returns the result for the digest algorithm PRIM applied to BLOB, optionally sliced by START END, in the RESULT-FORM.

RESULT-FORM default is (message-digest-result-form).

message-digest-string!

[procedure] (message-digest-string! PRIM STRING BUFFER [START [END]]) -> message-digest-result-type

Returns the RESULT for the digest algorithm PRIM applied to STRING, optionally sliced by START END, in the BUFFER.

message-digest-blob!

[procedure] (message-digest-blob! PRIM BLOB BUFFER [START [END]]) -> message-digest-result-type

Returns the result for the digest algorithm PRIM applied to BLOB, optionally sliced by START END, in the {BUFFER}.

message-digest-update-substring (DEPRECATED)

[procedure] (message-digest-update-substring DIGEST STRING START END)

Update the DIGEST with a substring STRING START END.

Message Digest Int

Provides digest update operations for character and integer datatypes.

Usage

(use message-digest-int)

message-digest-update-char-u8

[procedure] (message-digest-update-char-u8 DIGEST CHAR)

Update the DIGEST with the low-order 8-bits of a character CHAR.

message-digest-update-char

[procedure] (message-digest-update-char DIGEST CHAR [ENDIAN])

Update the DIGEST with a the character CHAR 32-bit integer value treated as ENDIAN.

ENDIAN default is (machine-byte-order).

message-digest-update-char-be

[procedure] (message-digest-update-char-be DIGEST CHAR)

Update the DIGEST with a the character CHAR 32-bit integer value treated as big-endian.

message-digest-update-char-le

[procedure] (message-digest-update-char-le DIGEST CHAR)

Update the DIGEST with a the character CHAR 32-bit integer value treated as little-endian.

message-digest-update-u8

[procedure] (message-digest-update-u8 DIGEST U8)

Update the DIGEST with an 8-bit integer U8.

message-digest-update-u16

[procedure] (message-digest-update-u16 DIGEST U16 [ENDIAN])

Update the DIGEST with a 16-bit integer U16 treated as ENDIAN.

ENDIAN default is (machine-byte-order).

message-digest-update-u16-be

[procedure] (message-digest-update-u16-be DIGEST U16)

Update the DIGEST with a 16-bit integer U16 treated as big-endian.

message-digest-update-u16-le

[procedure] (message-digest-update-u16-le DIGEST U16)

Update the DIGEST with a 16-bit integer U16 treated as little-endian.

message-digest-update-u32

[procedure] (message-digest-update-u32 DIGEST U32 [ENDIAN])

Update the DIGEST with a 32-bit integer U32 treated as ENDIAN.

ENDIAN default is (machine-byte-order).

message-digest-update-u32-be

[procedure] (message-digest-update-u32-be DIGEST U32)

Update the DIGEST with a 32-bit integer U32 treated as big-endian.

message-digest-update-u32-le

[procedure] (message-digest-update-u32-le DIGEST U32)

Update the DIGEST with a 32-bit integer U32 treated as little-endian.

message-digest-update-u64

[procedure] (message-digest-update-u64 DIGEST U64 [ENDIAN])

Update the DIGEST with a 64-bit integer U64 treated as ENDIAN.

ENDIAN default is (machine-byte-order).

message-digest-update-u64-be

[procedure] (message-digest-update-u64-be DIGEST U64)

Update the DIGEST with a 64-bit integer U64 treated as big-endian.

message-digest-update-u64-le

[procedure] (message-digest-update-u64-le DIGEST U64)

Update the DIGEST with a 64-bit integer U64 treated as little-endian.

Message Digest Update Item

Provides digest update operations for Scheme objects.

Usage

(use message-digest-update-item)

message-digest-update-file

[procedure] (message-digest-update-file DIGEST FILENAME)

Update the DIGEST with the contents of file FILENAME.

message-digest-update-procedure

[procedure] (message-digest-update-procedure DIGEST THUNK)

Update the DIGEST with a THUNK until it returns #f.

THUNK is a (-> byte-source).

message-digest-update-port

[procedure] (message-digest-update-port DIGEST INPUT-PORT)

Update the DIGEST with byte-source from an INPUT-PORT until #!eof encountered.

Uses the message-digest-chunk-read-maker to create a reader for the port.

message-digest-update-object

[procedure] (message-digest-update-object DIGEST SOURCE [START [END]])

Update the DIGEST with some SOURCE.

SOURCE maybe

input-port: as in message-digest-update-port
procedure: as in message-digest-update-procedure
string
blob
srfi-4-vector
*: ((message-digest-chunk-converter) SOURCE) -> byte-source.

If START END supplied, and possible, the byte-source is sliced.

Message Digest Item

Provides digest operations for whole Scheme objects.

Usage

(use message-digest-item)

message-digest-object

[procedure] (message-digest-object PRIM SOURCE [RESULT-FORM [START [END]]]) -> message-digest-result-type

Returns the result for the digest algorithm PRIM applied to SOURCE, optionally sliced by START END, in the RESULT-FORM.

RESULT-FORM default is (message-digest-result-form).

message-digest-file

[procedure] (message-digest-file PRIM FILENAME [RESULT-FORM]) -> message-digest-result-type

Returns the result for the digest algorithm PRIM applied to the file FILENAME in the RESULT-FORM. Reads until #!eof encountered.

RESULT-FORM default is (message-digest-result-form).

message-digest-port

[procedure] (message-digest-port PRIM INPUT-PORT [RESULT-FORM]) -> message-digest-result-type

Returns the result for the digest algorithm PRIM applied to INPUT-PORT in the RESULT-FORM. Reads until #!eof encountered.

RESULT-FORM default is (message-digest-result-form).

message-digest-object!

[procedure] (message-digest-object! PRIM SOURCE BUFFER [START [END]]) -> message-digest-result-type

Returns the result for the digest algorithm PRIM applied to SOURCE, optionally sliced by START END, in the BUFFER.

message-digest-file!

[procedure] (message-digest-file! PRIM FILENAME BUFFER) -> message-digest-result-type

Returns the result for the digest algorithm PRIM applied to the file FILENAME in the BUFFER. Reads until #!eof encountered.

message-digest-port!

[procedure] (message-digest-port! PRIM INPUT-PORT BUFFER) -> message-digest-result-type

Returns the result for the digest algorithm PRIM applied to INPUT-PORT in the BUFFER. Reads until #!eof encountered.

Message Digest SRFI 4

Provides digest operations for SRFI-4 packed-vectors.

Usage

(use message-digest-srfi-4)

message-digest-update-u8vector

[procedure] (message-digest-update-u8vector DIGEST U8VECTOR [START [END]])

Update the DIGEST with a U8VECTOR, optionally sliced by START END.

message-digest-u8vector

[procedure] (message-digest-u8vector PRIM U8VECTOR [RESULT-FORM [START [END]]]) -> message-digest-result-type

Returns the result for the digest algorithm PRIM applied to U8VECTOR, optionally sliced by START END, in the RESULT-FORM.

RESULT-FORM default is (message-digest-result-form).

message-digest-u8vector!

[procedure] (message-digest-u8vector! PRIM U8VECTOR BUFFER [START [END]]) -> message-digest-result-type

Returns the result for the digest algorithm PRIM applied to U8VECTOR, optionally sliced by START END, in the BUFFER.

message-digest-update-subu8vector (DEPRECATED)

[procedure] (message-digest-update-subu8vector DIGEST U8VECTOR START END)

Update the DIGEST with a subvector U8VECTOR START END.

message-digest-update-bytevector (DEPRECATED)

[procedure] (message-digest-update-bytevector DIGEST BYTEVECTOR [LENGTH])

Update the DIGEST with the BYTEVECTOR, a blob, string, or srfi-4-vector.

The LENGTH is the byte count. Default is the size in bytes of the BYTEVECTOR.

Message Digest Port

Provides a port abstraction for a message-digest-primitive.

Usage

(use message-digest-port)

Common Argument Definitions

PORT is a digest-output-port.

digest-output-port

[procedure] (digest-output-port? OBJ) -> boolean
[procedure] (check-digest-output-port LOC OBJ [NAM])
[procedure] (error-digest-output-port LOC OBJ [NAM])
[procedure] (digest-output-port-name PORT) -> string

open-output-digest

[procedure] (open-output-digest PRIM) -> digest-output-port

Returns a message digest output port for the supplied algorithm PRIM.

The initialization phase.

get-output-digest

[procedure] (get-output-digest PORT [RESULT-FORM]) -> string

Closes the PORT and returns the result as a RESULT-FORM.

RESULT-FORM default is (message-digest-result-form).

The finalization phase.

call-with-output-digest

[procedure] (call-with-output-digest PRIM PROC [RESULT-FORM]) -> message-digest-result-type

Returns the result of the call of PROC with an open-output-digest for PRIM in the RESULT-FORM.

RESULT-FORM default is (message-digest-result-form).

with-output-to-digest

[procedure] (with-output-to-digest PRIM THUNK [RESULT-FORM]) -> message-digest-result-type

Invoke the procedure THUNK with (current-output-port) bound to a digest-output-port and return in the RESULT-FORM.

RESULT-FORM default is (message-digest-result-form).

Usage

(use message-digest-basic)

message-digest-primitive, message-digest-type, message-digest-chunk, message-digest-bv, message-digest-int

(use message-digest)

Everything in message-digest-basic plus message-digest-srfi-4, message-digest-update-item, message-digest-item, message-digest-port

Examples

Uses the message-digest port abstraction to get an MD5 digest of a string:

(use message-digest-port md5) ; Or sha1, or sha2, ...

(call-with-output-digest (md5-primitive) (cut display "foo" <>))
;=> "acbd18db4cc2f85cedef654fccc4a4d8"

Bugs and Limitations

Only messages on a byte-boundary supported. Bit-boundary messages are not handled.
The number update routines will not process an integer represented as anything other than a fixnum or flonum.
Since Chicken does not really have a binary port the digest-output-port will only accumulate strings. For example, writing a 16-bit integer is actually writing the result of number->string and not the 16-bit value itself! To get this effect the value must first be packed into a string and then written. However, the extras#write-byte routine should function as expected with a digest-output-port.
The chunk-converter and source-reader interface is clumsy.

Notes

If someone needs to construct a message-digest phase procedure that cannot be built upon the existing public API please contact the maintainer. There are some routines that can be exported to aid in such a project. It must be pointed out that the message-digest port/file API is implemented using only the existing public API.

3.9.1: Fix reference to non-existent message-digest-single.
3.9.0: Add types.
3.8.0: Fix message-digest-primitive?; accept *.
3.7.1
3.7.0: Add message-digest-object!, message-digest-file!, and message-digest-port!.
3.6.0: Add START and/or END optional arguments.
3.5.0: Add finalize-message-digest!.
3.4.0: Deprecate message-digest-chunk-read-maker. Add message-digest-chunk-port-read-maker, message-digest-chunk-fileno-read-maker. Add message-digest-primitive-raw-update.
3.3.0: Deprecate message-digest-default-result-type. Add message-digest-result-form.
3.2.0: Add message-digest-default-result-type. message-digest-chunk-* are parameters.
3.1.1: Fix check-u8vector import.
3.1.0: Added optional message-digest-primitive-block-length.
3.0.5: Reverted 64 bit support.
3.0.4: Removed 64 bit support.
3.0.3
3.0.2: Use of compiled setup-helper.
3.0.1
3.0.0: Removed deprecated procedures to own module. Removed integer packing procedures. Split into many modules. Deprecated some procedures.
2.3.8: Treat integers as unsigned. (Ticket #534) Uses blob for finalization result buffer.
2.3.7: Remove no checks optimization compier options.
2.3.6: Deprecated close-output-digest. Restricted no checks optimization compier option.
2.3.5: The 'u8vector RESULT-FORM is slightly faster. Revert to allocated context memory.
2.3.4: Try w/o C-level memory allocation so no finalizer needed.
2.3.3: The 'blob RESULT-FORM is slightly faster.
2.3.2: Deprecated byte-string->hexadecimal. Deprecated string->hex, use string-utils string-hexadecimal#string->hex. Fix for the default message-digest-chunk-read-maker, blob was always chunk-size.
2.3.1: Moved some utility routines into own egg(s).
2.3.0: Added message-digest-update-char-u8, message-digest-update-char-be, and message-digest-update-char-le. message-digest-update-char now treats the actual bit-width of char correctly.
2.2.0: Added Byte Packing API. Downgraded message-digest-chunk-read-maker, message-digest-chunk-size & message-digest-chunk-converter from parameter.
2.1.1: Bug fix for hexstring: must use lowercase.
2.1.0: Added message digest "phase" and port APIs. Deprecated old API.
2.0.1: Bug fix for (message-digest-chunk-converter) use by make-binary-message-digest.
2.0.0: Release for Chicken 4 [From a diff provided by Christian Kellermann]

License

 Copyright (C) 2006-2018 Kon Lovett.  All rights reserved.

 Permission is hereby granted, free of charge, to any person obtaining a
 copy of this software and associated documentation files (the Software),
 to deal in the Software without restriction, including without limitation
 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 and/or sell copies of the Software, and to permit persons to whom the
 Software is furnished to do so, subject to the following conditions:

 The above copyright notice and this permission notice shall be included
 in all copies or substantial portions of the Software.

 THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.