You are looking at historical revision 26413 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.

This extension is split into many modules. The extension module message-digest exports every other modules except message-digest-ports.

Message Digest Primitive

Usage

(use 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 a positive-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 uninitialized memory.

The <context> should be a unique object. At least the object cannot be shared with another activated primitive.

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

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> <BLOB> <COUNT>)). Must accumulate the <BLOB>. Will be called zero or more times.

The foreign type specifier scheme-pointer is suitable as a foreign-lambda argument type for the <BLOB> argument since the data-region is a contiguous array of bytes.

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

FINAL is a (procedure (<CONTEXT> <BLOB>)). Must build the message-digest result in the supplied result <BLOB>, which will have a length of at least DIGEST-LENGTH.

(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 Type

Usage

(use message-digest-type)

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 lower-case 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.

srfi-4-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 srfi-4-vector.

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.

setup-message-digest-buffer!

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

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

Message Digest Parameters

Common handlers.

Not thread specific.

Usage

(use message-digest-parameters)

message-digest-chunk-read-maker

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

Supplies the procedure used to create an input procedure.

CONSTRUCTOR is a (procedure (INPUT-PORT #!optional SIZE) (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) => SIZE
[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) => CONVERTER
[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 CONVERTER is #f.

Message Digest BV

Digest routines for string & blob.

Usage

(use message-digest-bv)

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 (DEPRECATED)

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

Update the DIGEST with a substring STRING START END.

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 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 (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-object

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

Update the DIGEST with some SOURCE.

SOURCE maybe an input-port (as in message-digest-update-port), procedure (as in message-digest-update-procedure), string, blob, srfi-4-vector, or anything a supplied message-digest-chunk-converter recognizes & can convert into a <byte-source>.

Message Digest Item

Provides digest operations for whole Scheme objects.

Usage

(use message-digest-item)

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-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. Reads until #!eof encountered.

RESULT-FORM default is 'hex.

Performs all three phases.

message-digest-port

[procedure] (message-digest-port PRIMITIVE INPUT-PORT [RESULT-FORM]) => <result>

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

RESULT-FORM default is 'hex.

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)

Update the DIGEST with a U8VECTOR.

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

get-output-digest

[procedure] (get-output-digest PORT [RESULT-TYPE 'hex]) => string

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

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

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

(use message-digest-basic)

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

(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"

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 port-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, 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

Author

Kon Lovett

Version history

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