Websites Navigation: Airbit | Shop | m-shell.net
Languages: EN | DE

Module digest: Message Digests

This module computes standard digests on messages of arbitrary length. A message digest is a short (e.g. 16), fixed length string of bytes computed from a message, with the following characteristics:
  • The same message always produces the same digest.
  • The probability of two different random messages resulting in the same digest is close to 1 to the number of different digests.
  • Deriving the original message (or set of messages) from the digest is computationally (nearly) equivalent to trying all possible messages and looking for a matching digest.
This module currently supports the MD2, MD5, and SHA1 digest algorithms.

To compute a digest, proceed as follows:

  1. Create a message digest for the desired algorithm with digest.new.
  2. Add data to the digest ("digest" the data) with digest.add or digest.add16 (for 16-bit strings), until the entire data has been digested.
  3. Obtain the message digest with digest.get.
  4. Call digest.clear to reset the digest and start a new digestion with the same algorithm.
Usage examples:

// a function to compute the MD5 of a file
function filemd5(name)
  d=digest.new("MD5");
  f=io.open(name);
  buf=io.read(f, 256);
  while buf#null do
    digest.add(d, buf); buf=io.read(f, 256)
  end;
  io.close(f);
  return digest.get(d)
end

// A function to compute the SHA1 digest of a string
// (lower 8 bits only).
// The digest is returned as a hexadecimal string.
function sha1(s)
  d=digest.new("SHA1");
  digest.add(d, s);
  return digest.get(d)
end

print encoding.tohex(sha1("Lucky Luke"))
→ d977763133f671049ca991a32e6a107b33be97d0

digest.add

• function add(digest, data) → null

Digest the low bytes of all characters in string data with digest, or digest the single byte with number data.

// Compute the MD5 of the bytes 0 to 255
d=digest.new("MD5")
for b=0 to 255 do
  digest.add(d, b)
end
print encoding.tohex(digest.get(d))
→ e2c865db4162bed963bfaa9ef6ac18f0

digest.add16

• function add16(digest, data) → null

Digest the low and high bytes of all characters in string data with digest. This function can be used to properly digest multi-byte strings (in UTF-16 little endian), as digest.add discards the high bytes.

digest.clear

• function clear(digest) → null

Clear all data digested so far with digest, and start a new digestion.

digest.get

• function get(digest) → String

Finalize the current digestion with digest and get the result as a string of bytes.

Repeated calls to digest.get without digesting more data in between will return the same digest.

Note that calling digest.get may add padding bytes to be able to compute the digest. Thus, subsequent digests after adding more data will most likely be different from those obtained without intermediate calls to digest.get.

digest.new

• function new(algorithm) → Native Object

Create a new digest with algorithm (a string, not case sensitive), and return it. Currently supported algorithms are:

Alg.DescriptionRFCBits
MD2Older message digest algorithm for general digital signature applications, and optimized for 8-bit machines.1319128
MD5Widely used message digest algorithm for general digital signature applications.1321128
SHA1Secure Hash Algorithm (version 1) for use with the Digital Signature Standard.3174180

Throws ErrArgument if algorithm is not the name of a supported algorithm.

// create an MD5 digest object
d=digest.new("md5")
// get the hash (hex) of the empty message
print encoding.tohex(digest.get(d))
→ d41d8cd98f00b204e9800998ecf8427e


© 2004-2011 airbit AG, CH-8008 Zürich
Document AB-M-LIB-888
mShell Home  > Documentation  > Manuals