43.23 Textual transformations—MD5 and base64 support

Some textual operations inherently require examining each character in turn, and performing arithmetic operations on them. Such operations can, of course, be implemented in SXEmacs Lisp, but tend to be very slow for large portions of text or data. This is why some of them are implemented in C, with an appropriate interface for Lisp programmers. Examples of algorithms thus provided are MD5 and base64 support.

MD5 is an algorithm for calculating message digests, as described in rfc1321. Given a message of arbitrary length, MD5 produces a 128-bit “fingerprint” (“message digest”) corresponding to that message. It is considered computationally infeasible to produce two messages having the same MD5 digest, or to produce a message having a prespecified target digest. MD5 is used heavily by various authentication schemes.

As of SXEmacs 22.1.2 there is also support for MD5 and other digest algorithms when linked against OpenSSL. See OpenSSL Support.

SXEmacs Lisp interface to MD5 consists of a single function md5:

Function: md5 object &optional start end coding noerror

This function returns the MD5 message digest of object, a buffer or string.

Optional arguments start and end denote positions for computing the digest of a portion of object.

The optional coding argument specifies the coding system the text is to be represented in while computing the digest. If unspecified, it defaults to the current format of the data, or is guessed.

If noerror is non-nil, silently assume binary coding if the guesswork fails. Normally, an error is signaled in such case.

coding and noerror arguments are meaningful only in SXEmacsen with file-coding or Mule support. Otherwise, they are ignored. Some examples of usage:

;; Calculate the digest of the entire buffer
(md5 (current-buffer))
     ⇒ "8842b04362899b1cda8d2d126dc11712"

;; Calculate the digest of the current line
(md5 (current-buffer) (point-at-bol) (point-at-eol))
     ⇒ "60614d21e9dee27dfdb01fa4e30d6d00"

;; Calculate the digest of your name and email address
(md5 (concat (format "%s <%s>" (user-full-name) user-mail-address)))
     ⇒ "0a2188c40fd38922d941fe6032fce516"

Base64 is a portable encoding for arbitrary sequences of octets, in a form that need not be readable by humans. It uses a 65-character subset of US-ASCII, as described in rfc2045. Base64 is used by MIME to encode binary bodies, and to encode binary characters in message headers.

The Lisp interface to base64 consists of four functions:

Command: base64-encode-region start end &optional no-line-break

This function encodes the region between start and end of the current buffer to base64 format. This means that the original region is deleted, and replaced with its base64 equivalent.

Normally, encoded base64 output is multi-line, with 76-character lines. If no-line-break is non-nil, newlines will not be inserted, resulting in single-line output.

Mule note: you should make sure that you convert the multibyte characters (those that do not fit into 0–255 range) to something else, because they cannot be meaningfully converted to base64. If the base64-encode-region encounters such characters, it will signal an error.

base64-encode-region returns the length of the encoded text.

;; Encode the whole buffer in base64
(base64-encode-region (point-min) (point-max))

The function can also be used interactively, in which case it works on the currently active region.

Function: base64-encode-string string &optional no-line-break

This function encodes string to base64, and returns the encoded string.

Normally, encoded base64 output is multi-line, with 76-character lines. If no-line-break is non-nil, newlines will not be inserted, resulting in single-line output.

For Mule, the same considerations apply as for base64-encode-region.

(base64-encode-string "fubar")
    ⇒ "ZnViYXI="

Command: base64-decode-region start end

This function decodes the region between start and end of the current buffer. The region should be in base64 encoding.

If the region was decoded correctly, base64-decode-region returns the length of the decoded region. If the decoding failed, nil is returned.

;; Decode a base64 buffer, and replace it with the decoded version
(base64-decode-region (point-min) (point-max))

Function: base64-decode-string string

This function decodes string to base64, and returns the decoded string. string should be valid base64-encoded text.

If encoding was not possible, nil is returned.

(base64-decode-string "ZnViYXI=")
    ⇒ "fubar"

(base64-decode-string "totally bogus")
    ⇒ nil