12.82 util.digest - Message digester framework

Module: util.digest ¶

This module provides a base class and common interface for message digest algorithms, such as MD5 (see rfc.md5 - MD5 message digest) and SHA (see rfc.sha - SHA message digest).

A typical way to compute a message digest would be as follows:

(use rfc.sha)       ; import actual digest implementation
(use util.digest)

(digest-message-to 'base64url <sha256> "message")

You can use different algorithms, and choose different output format (e.g. u8vector, hexadecimal string, etc.) If you need to digest with a secret key, see rfc.hmac - HMAC keyed-hashing.

User API

To digest a message, you can use the following API.

Generic Function: digest-message-to target digester message ¶

{util.digest} Compute a digest of message using algorithm implemented by digester, and returns as an instance of class target.

The message argument may be a string or a u8vector.

The digester argument must be a class inheriting <message-digest-algorithm> and implementing the digester protocol described below. Gauche provides SHA (see rfc.sha - SHA message digest) and MD5 (see rfc.md5 - MD5 message digest) by default.

The supported target class is <u8vector> and <string>. Digest result is a bytestring in general, so using <u8vector> is recommended; if you give <string>, the result is likely to be an incomplete string.

For the convnience, the following symbols are also allowed as target, in which case the output byte sequence is encoded to a readable string For the details of those encodings, see rfc.base64 - Base64 encoding/decoding.

base64

Base64 encoding (original).

base64url

URL-safe Base64 encoding.

base64url-nopad

URL-safe Base64 encoding and omitting trailing padding character (=)

base32

Base32 encoding.

base32hex

Base32hex encoding.

base16

Base16 encoding, a.k.a. hexadecimal encoding (using #[0-9A-F].

hex

Base16 encoding but use lowercase letters (using #[0-9a-f].

Generic Function: digest-to target digester ¶

Read input from the current input port until EOF, compute its digest using the algorithm specified by digester, and returns result in an instance of a class given to target. You can also give some symbols to specify encodings as target. See digest-message-to above for the details of target and digester. {util.digest}

Implementer API

The following API is for the impelmenter of the actual digest aglrithms.

Class: <message-digest-algorithm-meta> ¶

{util.digest} A metaclass of message digest algorithm implementation.

Instance Variable of <message-digest-algorithm-meta>: hmac-block-size ¶

Specifies the block size (in bytes), which is specific to each algorithm. (This is a slot for each class object that implements the algorithm, not for instance of such classes. Only the author of such digest classes needs to care. See ext/digest/sha.scm in the source tree for more details.)

Class: <message-digest-algorithm> ¶

{util.digest} A base class of message digest algorithm implementation.

The concrete subclass of message digest algorithm has to implement the following methods.

Generic function: digest-update! algorithm data ¶

{util.digest} Takes the instance of massage-digest algorithm, and updates it with the data data, which can be either a u8vector or a (possibly incomplete) string.

Generic function: digest-final! algorithm ¶

{util.digest} Finalizes the instance of message-digest algorithm, and returns the digest result in an incomplete string.

Generic function: digest class ¶

{util.digest} A wrapper of digest routines. Given message-digest algorithm class, this function reads the input data from current input port until EOF, and returns the digest result in an incomplete string.

Deprecated API

Generic function: digest-string class string ¶

{util.digest} Deprecated. Use digest-message-to for the new code.

Same as (digest-message-to <string> class string), where only a string is allowed to the string argument.

Function: digest-hexify digest-result ¶

{util.digest} Deprecated. Same as (base16-encode-message digest-result :lowercase #t) (see rfc.base64 - Base64 encoding/decoding). In typical case, you can pass hex as the target to digest-message-to to get the hexified output directly. This procedure is only kept for the backward compatibility.