You are looking at historical revision 18851 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 should be something easily treated as a byte-block.

Parameters

message-digest-chunk-read-maker

[parameter] (message-digest-chunk-read-maker [READER-CREATOR])

The procedure used to create an input procedure.

[procedure] (READER-CREATOR INPUT-PORT) => PROCEDURE/0

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

The READER must return an object suitable for treatment as a byte-source. See SOURCE.

message-digest-chunk-size

[parameter] (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, default 1024.

message-digest-chunk-converter

[parameter] (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.

[procedure] (CONVERTER OBJECT) => {{object}}

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

The CONVERTER must return an object suitable for treatment as a byte-source. See SOURCE.

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])
[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 ID) => {{message-digest-primitive}}

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

CONTEXT-INFO is either a procedure that returns an object 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.

DIGEST-LENGTH is the count of bytes in the RESULT-STRING.

{{(INIT CONTEXT)}}

Initialization phase procedure. Sets up the CONTEXT, if necessary.

{{(UPDATE CONTEXT BUFFER COUNT)}}

Accumulation phase procedure. Must accumulate the BUFFER, where BUFFER 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 BUFFER argument since the contents of both are a bytevector.

Where the actual number of bytes in the BUFFER can be determined COUNT will be a positive-integer.

{{(FINAL CONTEXT RESULT-STRING)}}

Finalization phase procedure. Must build the resulting message-digest in the supplied RESULT-STRING, a string of length DIGEST-LENGTH.

Message Digest

Common Argument Definitions

RESULT-FORM is one of:

'string

the result bytes as a string. Note - 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, see make-message-digest-primitive, is translated as:

string

BUFFER = SOURCE.

blob

BUFFER = SOURCE.

srfi-4-vector

BUFFER = (XXXvector->blob/shared SOURCE).

object

BUFFER = (message-digest-chunk-converter SOURCE).

(Note - the above considered byte sources)

procedure

updates with BUFFER = (procedure) until #f = (procedure).

input-port

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

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

message-digest

[procedure] (message-digest? OBJ) => {{boolean}}
[procedure] (check-message-digest LOC OBJ [NAM])
[procedure] (error-message-digest LOC OBJ [NAM])
[procedure] (message-algorithm DIGEST)
[procedure] (message-context DIGEST)

initialize-message-digest

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

Create, initialize and return a message-digest for the supplied algorithm PRIMITIVE.

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.

message-digest-update-object

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

Update the DIGEST with some SOURCE.

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

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

Update the DIGEST with a character CHAR.

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 should return either a string or a blob but any object meeting the criteria of SOURCE, except a procedure or an input-port, is acceptable.

message-digest-update-port

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

Update the DIGEST with contents from an INPUT-PORT until EOF.

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

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.

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.

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.

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.

*message-digest-update

[procedure] (*message-digest-update DIGEST SOURCE LENGTH)

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.

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.

get-output-digest-string

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

Closes the PORT and returns the RESULT as a string.

get-output-digest-hexstring

[procedure] (get-output-digest-hexstring PORT)

Closes the PORT and returns the RESULT as a string.

get-output-digest-blob

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

Closes the PORT and returns the RESULT as a blob.

get-output-digest-u8vector

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

Closes the PORT and returns the RESULT as a u8vector.

call-with-output-digest

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

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

RESULT-FORM default is 'hex.

with-output-to-digest

[procedure] (with-output-to-digest PRIMITIVE THUNK [RESULT-FORM])

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.

Auxillary Procedures

byte-string->hexadecimal

[procedure] (byte-string->hexadecimal STRING [START [END]]) => {{string}}
[procedure] (string->hex STRING [START [END]]) => {{string}}

Returns a hex-encoded representation of STRING, on the interval [START END). Defaults are [0 string-length).

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.

Usage

(use message-digest)

To access the message-digest port abstraction:

(use message-digest-port)

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"

Notes

• Unlike the Chicken 3 version does not provide the ->blob and ->blob/shared procedures.

Requirements

miscmacros check-errors

Bugs and Limitations

• Uses a string for the message-digest result, should use a blob.
• byte-string->hexadecimal does not really belong here.

Author

kon lovett

Version history

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.