chickadee » message-digest » make-message-digest-primitive

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

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!)

BLOCK-LENGTH must be a positive fixnum and identifies the message digest algorithm accumulator length in bytes. The default is 4.

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.