message-digest-utils

  1. message-digest-utils
  2. Documentation
    1. Common Argument Definitions
    2. Message Digest Byte Vector
      1. Usage
      2. message-digest-update-blob
      3. message-digest-update-string
      4. message-digest-string
      5. message-digest-blob
      6. message-digest-string!
      7. message-digest-blob!
    3. Message Digest Int
      1. Usage
      2. message-digest-update-char-u8
      3. message-digest-update-char
      4. message-digest-update-char-be
      5. message-digest-update-char-le
      6. message-digest-update-u8
      7. message-digest-update-u16
      8. message-digest-update-u16-be
      9. message-digest-update-u16-le
      10. message-digest-update-u32
      11. message-digest-update-u32-be
      12. message-digest-update-u32-le
      13. message-digest-update-u64
      14. message-digest-update-u64-be
      15. message-digest-update-u64-le
    4. Message Digest Update Item
      1. Usage
      2. message-digest-update-file
      3. message-digest-update-procedure
      4. message-digest-update-port
      5. message-digest-update-object
    5. Message Digest Item
      1. Usage
      2. message-digest-object
      3. message-digest-file
      4. message-digest-port
      5. message-digest-object!
      6. message-digest-file!
      7. message-digest-port!
    6. Message Digest SRFI 4
      1. Usage
      2. message-digest-update-u8vector
      3. message-digest-u8vector
      4. message-digest-u8vector!
    7. Message Digest Port
      1. Usage
      2. Common Argument Definitions
      3. digest-output-port
      4. open-output-digest
      5. get-output-digest
      6. call-with-output-digest
      7. with-output-to-digest
    8. Message Digest Chunk
      1. Usage
      2. message-digest-chunk-port-read-maker
      3. message-digest-chunk-fileno-read-maker
      4. message-digest-chunk-size
      5. message-digest-chunk-converter
  3. Examples
  4. Bugs and Limitations
  5. Notes
  6. Requirements
  7. Author
  8. Repository
  9. Version history
  10. 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.

Common Argument Definitions

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

'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.
'string 'byte-string
DEPRECATED - the result bytes as a string; these are raw bytes, not necessarily characters!

DIGEST is a message-digest.

PRIM/DIGEST is a message-digest-primitive or 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.

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

Initialized here means the intialization phase is completed.

Message Digest Byte Vector

Digest routines for string & blob.

Usage

(import message-digest-byte-vector)

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/DIGEST STRING [RESULT-FORM [START [END]]]) -> message-digest-result-type

Returns the RESULT for the digest algorithm PRIM/DIGEST 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/DIGEST BLOB [RESULT-FORM [START [END]]]) -> message-digest-result-type

Returns the result for the digest algorithm PRIM/DIGEST 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/DIGEST STRING BUFFER [START [END]]) -> message-digest-result-type

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

message-digest-blob!

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

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

Message Digest Int

Provides digest update operations for character and integer datatypes.

Usage

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

(import 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 the THUNK result, until it returns #f.

THUNK
(-> (or BYTE-SOURCE false))
BYTE-SOURCE
(or string blob srfi-4-vector )

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

(import message-digest-item)

message-digest-object

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

Returns the result for the digest algorithm PRIM/DIGEST 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/DIGEST FILENAME [RESULT-FORM]) -> message-digest-result-type

Returns the result for the digest algorithm PRIM/DIGEST 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/DIGEST INPUT-PORT [RESULT-FORM]) -> message-digest-result-type

Returns the result for the digest algorithm PRIM/DIGEST 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/DIGEST SOURCE BUFFER [START [END]]) -> message-digest-result-type

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

message-digest-file!

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

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

message-digest-port!

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

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

Message Digest SRFI 4

Provides digest operations for SRFI-4 packed-vectors.

Usage

(import 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/DIGEST U8VECTOR [RESULT-FORM [START [END]]]) -> message-digest-result-type

Returns the result for the digest algorithm PRIM/DIGEST 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/DIGEST U8VECTOR BUFFER [START [END]]) -> message-digest-result-type

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

Message Digest Port

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

Usage

(import 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) -> digest-output-port

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

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/DIGEST PROC [RESULT-FORM]) -> message-digest-result-type

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

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

with-output-to-digest

[procedure] (with-output-to-digest PRIM/DIGEST 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).

Message Digest Chunk

An inchoate Chunking API.

Usage

(import message-digest-chunk)

message-digest-chunk-port-read-maker

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

Supplies the procedure used to create an input procedure.

CTOR
(PORT #!optional SIZE) -> (-> byte-source)
PORT
source open input port
SIZE
chunk size, default (message-digest-chunk-size)

The default CTOR returns a reader from PORT in SIZE bytes.

message-digest-chunk-fileno-read-maker

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

Supplies the procedure used to create an input procedure.

CTOR
(FD #!optional TOTAL SIZE) -> (-> byte-source)
FD
source open fileno
TOTAL
total size, default (file-size FD))
SIZE
chunk size, default (message-digest-chunk-size)

The default CTOR returns a reader conditioned on memory-mapped-file support.

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
positive-integer, default 1024

message-digest-chunk-converter

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

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

CONV
(* -> byte-source) or #f, default #f

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

Examples

(import message-digest-port md5)

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

(import miscmacros message-digest-type message-digest-byte-vector)

(define (next-string) "generate another string")

;for repeated digest operations, re-use the digest object
;lowers allocation & gc
(let ((md (setup-message-digest (md5-primitive))))
  (repeat 666 (message-digest-string md (next-string))) )

Bugs and Limitations

Notes

Requirements

check-errors blob-utils string-utils memory-mapped-files message-digest-primitive message-digest-type

Author

Kon Lovett

Repository

This egg is hosted on the CHICKEN Subversion repository:

https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/message-digest-utils

If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.

Version history

4.3.1
Fix a build dependency.
4.3.0
Support message-digest re-use. Fix with-output-to-digest/call-with-output-digest.
4.2.7
Fix dependency versions.
4.2.6
Fewer heap operations for string digests.
4.2.0
Add message-digest.types.scm.
4.1.2
.
4.0.0
CHICKEN 5 release.

License

 Copyright (C) 2006-2021 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.