You are looking at historical revision 22405 of this page. It may differ significantly from its current revision.

• egg

message-digest

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 byteblock or, even better, a bytevector.

Message Digest Primitive

Common Argument Definitions

PRIMITIVE is a 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 PRIMITIVE)
[procedure] (message-digest-primitive-digest-length PRIMITIVE)
[procedure] (message-digest-primitive-init PRIMITIVE)
[procedure] (message-digest-primitive-update PRIMITIVE)
[procedure] (message-digest-primitive-final PRIMITIVE)
[procedure] (message-digest-primitive-name PRIMITIVE)

make-message-digest-primitive

[procedure] (make-message-digest-primitive CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL [NAME]) => message-digest-primitive

Create a message-digest-primitive object. The reification of a message digest algorithm.

CONTEXT-INFO is either a (procedure () <context>), or an integer. When an integer a memory-block of length CONTEXT-INFO is allocated (and automatically free'ed).

<context> is an opaque object, except when the CONTEXT-INFO is an integer. In which case it is known that the object is a pointer to a block of non-garbage collected memory.

The <context> must always be a new object.

DIGEST-LENGTH is the count of bytes in the result string.

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

INIT is a (procedure (<context>)). Sets up the <context>. (Technically the creation of a new <context> is part of the initialization phase but this detail is hidden from the user.)

UPDATE is a (procedure (<context> <bytevector> <count>)). Must accumulate the <bytevector>, where <bytevector> is a string or blob. Will be called one or more times.

The foreign type specifier scheme-pointer is suitable as a foreign-lambda argument type for the <bytevector> argument since the data-region of both is a bytevector.

<count> is the actual number of bytes in the <bytevector>. Since this value is supplied it means only the first <count> bytes in the <bytevector> are valid.

FINAL is a (procedure (<context> <bytevector>)). Must build the message-digest result in the supplied result <bytevector> of length at least DIGEST-LENGTH.

Currently the result <bytevector> will only be a string but developers should accept a string or blob.

(Note that INIT, UPDATE & FINAL are side-effecting procedures!)

NAME must be a symbol or a string and identifies the message digest algorithm. The suggested form is <algorithm name>-primitive. Example: 'md5-primitive. The default is a nearly useless generated, uninterned symbol.

Message Digest

Common Argument Definitions

RESULT-FORM is one of:

'string

the result bytes as a string; these are raw bytes, not characters!

'hex

the result bytes encoded as a string of hexadecimal digits.

'blob

the result bytes as a blob.

'u8vector

the result bytes as a u8vector.

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> = SOURCE.

blob

<buffer> = SOURCE.

packed-vector

<buffer> = (...vector->blob/shared SOURCE).

procedure

updates with <buffer> = (procedure) until #f = (procedure).

input-port

like procedure above but from ((message-digest-chunk-read-maker) SOURCE).

*

<buffer> = (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 packed-vector.

message-digest-chunk-read-maker

[procedure] (message-digest-chunk-read-maker) => (procedure (input-port) (procedure () <byte-source>))
[procedure] (message-digest-chunk-read-maker CONSTRUCTOR)

Supplies the procedure used to create an input procedure.

CONSTRUCTOR is a (procedure (input-port #!optional positive-integer) (procedure () <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-size

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

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

[procedure] (message-digest-chunk-converter) => (procedure (*) <byte-source>)
[procedure] (message-digest-chunk-converter [CONVERTER])

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

CONVERTER is a (procedure (*) <byte-source>).

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

The default is #f.

initialize-message-digest

[procedure] (initialize-message-digest PRIMITIVE) => message-digest

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

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]) => <result>

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

RESULT-FORM default is 'hex.

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

message-digest-update-object

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

Update the DIGEST with some SOURCE.

message-digest-update-bytevector

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

Update the DIGEST with the BYTEVECTOR, a blob or string.

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

Using some other vector-like object for the BYTEVECTOR than the documented is performed at your own risk.

message-digest-update-blob

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

Update the DIGEST with a BLOB.

message-digest-update-string

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

Update the DIGEST with a STRING.

message-digest-update-substring

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

Update the DIGEST with a substring STRING START END.

message-digest-update-u8vector

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

Update the DIGEST with a U8VECTOR.

message-digest-update-subu8vector

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

Update the DIGEST with a subvector U8VECTOR START END.

message-digest-update-char-u8

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

Update the DIGEST with 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-procedure

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

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

THUNK is a (procedure () <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-file

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

Update the DIGEST with the contents of file FILENAME.

message-digest-object

[procedure] (message-digest-object PRIMITIVE SOURCE [RESULT-FORM]) => <result>

Returns the RESULT for the digest algorithm PRIMITIVE applied to SOURCE in the RESULT-FORM.

RESULT-FORM default is 'hex.

Performs all three phases.

message-digest-string

[procedure] (message-digest-string PRIMITIVE STRING [RESULT-FORM]) => <result>

Returns the RESULT for the digest algorithm PRIMITIVE applied to STRING in the RESULT-FORM.

RESULT-FORM default is 'hex.

Performs all three phases.

message-digest-blob

[procedure] (message-digest-blob PRIMITIVE BLOB [RESULT-FORM]) => <result>

Returns the <result> for the digest algorithm PRIMITIVE applied to BLOB in the RESULT-FORM.

RESULT-FORM default is 'hex.

Performs all three phases.

message-digest-u8vector

[procedure] (message-digest-u8vector PRIMITIVE U8VECTOR [RESULT-FORM]) => <result>

Returns the <result> for the digest algorithm PRIMITIVE applied to U8VECTOR in the RESULT-FORM.

RESULT-FORM default is 'hex.

Performs all three phases.

message-digest-file

[procedure] (message-digest-file PRIMITIVE FILENAME [RESULT-FORM]) => <result>

Returns the <result> for the digest algorithm PRIMITIVE applied to the file FILENAME in the RESULT-FORM.

RESULT-FORM default is 'hex.

Performs all three phases.

Utility Procedures

Byte Packing

BUFFER is either a symbol in {string blob u8vector}, a string, a blob, or a u8vector}. The {{BUFFER is interpreted as:

symbol

Construct a new instance of the specified type with necessary space.

...

Use the supplied object, ensuring enough space available.

The packing routines are either functional or side-effecting, depending on the supplied BUFFER object. The default is 'string.

START is the byte-offset (index) in the BUFFER to begin packing. The default is 0.

ORDER is a symbol in {big-endian little-endian}. The default is (machine-byte-order).

SIZE is an integer in {1 2 4 8}. The default is 4.

<byte-buffer> is either a string, a blob, or a u8vector.

pack-u8

[procedure] (pack-u8 N (#:buffer BUFFER) (#:start START))) => <byte-buffer>

Returns the BUFFER with the low-order 8 bits of the integer N packed at index START. SIZE is assumed 1.

pack-u16

[procedure] (pack-u16 N (#:buffer BUFFER) (#:start START) (#:order ORDER))) => <byte-buffer>

Returns the BUFFER with the low-order 16 bits of the integer N packed at index START in the byte ORDER. SIZE is assumed 2.

pack-u32

[procedure] (pack-u32 N (#:buffer BUFFER) (#:start START) (#:order ORDER))) => <byte-buffer>

Returns the BUFFER with the low-order 32 bits of the integer N packed at index START in the byte ORDER. SIZE is assumed 4.

pack-u64

[procedure] (pack-u64 N (#:buffer BUFFER) (#:start START) (#:order ORDER))) => <byte-buffer>

Returns the BUFFER with the low-order 64 bits of the integer N packed at index START in the byte ORDER. SIZE is assumed 8.

pack-integer

[procedure] (pack-integer N (#:buffer BUFFER) (#:start START) (#:order ORDER) (#:size SIZE))) => <byte-buffer>

Returns the BUFFER with the low-order SIZE bits of the integer N packed at index START in the byte ORDER.

Old API

make-binary-message-digest (DEPRECATED)

[procedure] (make-binary-message-digest SOURCE CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL [CALLER]) => string

Returns the message-digest for SOURCE as a string of bytes.

SOURCE is a Scheme-object.

The meaning of the other fields are as for make-message-digest-primitive.

The optional CALLER is for identification.

See message-digest-chunk-size to set the number of bytes read from a port.

See message-digest-chunk-read-maker to set the chunk reader procedure creator.

See message-digest-chunk-converter to set the chunk representation translation procedure.

make-message-digest (DEPRECATED)

[procedure] (make-message-digest SOURCE CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL [CALLER]) => string

Exactly as make-binary-message-digest but returns the message-digest for SOURCE using byte-string->hexadecimal.

message-digest-primitive-apply (DEPRECATED)

[procedure] (message-digest-primitive-apply PRIMITIVE SOURCE [CALLER])

Returns a binary-message-digest of SOURCE using PRIMITIVE.

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 PRIMITIVE) => digest-output-port

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

The initialization phase.

close-output-digest

[procedure] (close-output-digest PORT [RESULT-FORM]) => <result>

Closes the PORT and returns the <result> in the RESULT-FORM.

RESULT-FORM default is 'hex.

The finalization phase.

get-output-digest-string

[procedure] (get-output-digest-string PORT) => string
[procedure] (get-output-digest-byte-string PORT) => string

Closes the PORT and returns the result string.

The finalization phase.

get-output-digest-hexstring

[procedure] (get-output-digest-hexstring PORT) => string

Closes the PORT and returns the result as a string of hexadecimal digits.

The finalization phase.

get-output-digest-blob

[procedure] (get-output-digest-blob PORT) => blob

Closes the PORT and returns the result blob.

The finalization phase.

get-output-digest-u8vector

[procedure] (get-output-digest-u8vector PORT) => u8vector

Closes the PORT and returns the result u8vector.

The finalization phase.

call-with-output-digest

[procedure] (call-with-output-digest PRIMITIVE PROCEDURE/1 [RESULT-FORM]) => <result>

Invoke the procedure PROCEDURE PORT with digest-output-port and return <result> in the RESULT-FORM.

RESULT-FORM default is 'hex.

Performs all three phases.

with-output-to-digest

[procedure] (with-output-to-digest PRIMITIVE THUNK [RESULT-FORM]) => <result>

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

RESULT-FORM default is 'hex.

Performs all three phases.

Usage

(use message-digest)

Examples

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

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

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

(use message-digest)

; Uses a string as the buffer so the packed buffer is interpreted properly.
; A blob or u8vector would be converted to a string by the port i/o machinary
; with loose of information; like all of it.
(call-with-output-digest (md5-primitive) (pack-u32 #xabcdef012345 #:order 'big-endian))
;=> ""

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, though, that the message-digest port API is implemented using only the existing public API.

• Should the default message-digest result-form be held by a "parameter" object?

Requirements

miscmacros check-errors

Bugs and Limitations

• The Utility Procedures do not belong here.
• Uses a string for the message-digest <result> in the finalization phase. Should use a blob since the <result> is actually a bytevector.
• The chunk-converter and port-reader interface is clumsy.
• Since Chicken does not really have a binary port concept the digest-output-port will only accumulate strings. Should a more nuanced set of sources be necessary use the Byte Packing API above.

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 number update routines will not accept an integer represented as a flonum.

Author

Kon Lovett

Version history

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

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-2010 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.