Table of Contents

  1. Quick & Easy
  2. EVP
  3. HMAC

Quick & Easy

This module is written to use the new Lua 5.1 package system. To use this module, you need to do:


    local evp = require("crypto.evp")
    local hmac = require("crypto.hmac")
    

This will put the EVP and HMAC package namespaces into the evp and hmac tables respectively. The simplest usage of these packages are:


    assert(io.input(some_file))
    local md5_of_some_file = evp.digest("md5", io.read("*all"))
    
    assert(io.input(some_file))
    local hmac_of_some_file = hmac.digest("sha1", io.read("*all"), "hmackey")
    

crypto.evp

The crypto.evp library is a wrapper over the EVP_Digest* calls available in libcrypto. These calls handle all message digest creation operations for a wide variety of algorithms (SHA-1, MD5, etc). The luacrypto bindings provide two interfaces into this functionality. The first is a single function call interface that has no setup and no side-effects. The second is an object based interface that may be useful for some scenarios.

Functional Interface

output = evp.digest(type, string, [raw])

This function generates the message digest of the input string and returns it as output. The hashing algorithm to use is specified as a string by type, and this can be any one of the types allowed by OpenSSL (see their documentation for a full list). Examples include "sha1" and "md5". The optional raw flag, defaulted to false, is a boolean value indicating whether the output should be formatted as a hexadecimal string (the default), or as a direct binary equivalent of the message digest.

Object Interface

The object interface is mainly useful in cases where you want to increase efficiency. For instance, if you will be hashing a lot of different items using the same algorithm, you can create a new message digest object of the type required and reset it between each digest call, which will save you a little bit of setup overhead each time. Alternately, if you are hashing two or more items that have mostly the same content up until the end, you can load an object with the identical data, then clone off multiple copes to tack on the remaining, differing pieces of data for each.

d = evp.new(type)

Creates a new EVP message digest object of the type specified. This is the string name of the hash algorithm to use, which can be any one of the allowed OpenSSL types (see their documentation for a full list). Example types include "sha1" and "md5".

d:reset()

Resets the internals of the EVP message digest object to a clean slate.

d2 = d:clone()

Clones the message digest object and its current state, including data loaded to this point.

d:update(string)

Appends the data in string to the current internal data set to be hashed.

output = d:digest([string], [raw])

Generates the message digest for the internal data set, optionally appending on new data provided by string prior to hashing. The optional raw flag, defaulted to false, is a boolean value indicating whether the output should be formatted as a hexadecimal string (the default), or as a direct binary equivalent of the message digest.

crypto.hmac

The crypto.hmac library is a wrapper over the HMAC_* calls available in libcrypto. These calls implement Keyed-Hashing for Message Authentication (HMAC). HMAC can use any message digest type (SHA-1, MD5, etc). The luacrypto bindings provide two interfaces into this functionality. The first is a single function call interface that has no setup and no side-effects. The second is an object based interface that may be useful for some scenarios.

Functional Interface

output = hmac.digest(type, string, key, [raw])

This function generates the HMAC of the input string and returns it as output. The hashing algorithm to use is specified as a string by type, and this can be any one of the types allowed by OpenSSL (see their documentation for a full list). Examples include "sha1" and "md5". The string provided in key will be used as the seed for the HMAC generation. The optional raw flag, defaulted to false, is a boolean value indicating whether the output should be formatted as a hexadecimal string (the default), or as a direct binary equivalent of the HMAC.

Object Interface

The object interface is mainly useful in cases where you want to increase efficiency. For instance, if you will be generating HMACs for a lot of different items using the same algorithm, you can create a new HMAC object of the type required and reset it between each digest call, which will save you a little bit of setup overhead each time.

d = hmac.new(type, key)

Creates a new HMAC object of the type specified. This is the string name of the hash algorithm to use, which can be any one of the allowed OpenSSL types (see their documentation for a full list). Example types include "sha1" and "md5". The HMAC key to use is provided as a string in key.

d:reset()

Resets the internals of the HMAC object to a clean slate.

d2 = d:clone()

Clones the HMAC object and its current state, including data loaded to this point. DOES NOT WORK YET. Just returns a new pointer to the same object.

d:update(string)

Appends the data in string to the current internal data set to be hashed.

output = d:digest([string], [raw])

Generates the HMAC for the internal data set, optionally appending on new data provided by string prior to hashing. The optional raw flag, defaulted to false, is a boolean value indicating whether the output should be formatted as a hexadecimal string (the default), or as a direct binary equivalent of the message digest. Note that you can only run this method once on an object; running it a second time will product a bogus HMAC because the internal state is irrecovably destroyed after the first call.