LuaCrypto: A Lua frontend to OpenSSL

LuaCrypto
A Lua frontend to OpenSSL

## Introduction

LuaCrypto is a Lua frontend to the OpenSSL cryptographic library. The OpenSSL features that are currently exposed are digests (MD5, SHA-1, HMAC, and more) and crypto-grade random number generators.

The API tries to hide the OpenSSL setup and teardown, so in most cases it is not simply a pass-through to the existing OpenSSL API. Since this is still a very early version of the software, the API may undergo significant future changes! You have been warned.

## Building

LuaCrypto could be built to Lua 5.0 or to Lua 5.1. In both cases, the language library and headers files for the target version must be installed properly.

LuaCrypto offers a Makefile and a separate configuration file, `config`, which should be edited to suit your installation before runnig `make`. The file has some definitions like paths to the external libraries, compiler options and the like. In particular, you must set the correct path to your installed OpenSSL libraries. Another important setting is the version of Lua language, which is not obtained from the installed software.

## Installation

The LuaCrypto compiled binary should be copied to a directory in your C path. Lua 5.0 users should install Compat-5.1 also.

## Reference

### Parameters

dtype
  This parameter is always a string naming the hashing algorithm to use for a digest operation. The list of supported algorithms may change with each version of the OpenSSL library. Refer to the OpenSSL documentation for a complete and up to date list. As of 0.9.7, the supported types are:
  - md5
  - md4
  - md2
  - sha1
  - sha
  - mdc2
  - ripemd160

### Message Digest (EVP) - crypto.evp

crypto.evp.digest(dtype, string [, raw])
  This function generates the message digest of the input `string` and returns it. The hashing algorithm to use is specified by `dtype`. The optional `raw` flag, defaulted to false, is a boolean indicating whether the output should be a direct binary equivalent of the message digest, or formatted as a hexadecimal string (the default).
crypto.evp.new(dtype)
  Creates a new EVP message digest object using the algorithm specified by `dtype`.
evp:reset()
  Resets the EVP message digest object to a clean slate.
evp:clone()
  Returns a new message digest object which is a clone of the object and its current state, including any data loaded to this point.
evp:update(string)
  Appends the data in `string` to the current internal data set to be hashed. Returns the object so that it can be reused in nested calls.
evp:digest([string] [, raw])
  Generates the message digest for the loaded data, optionally appending on new data provided by `string` prior to hashing. The optional `raw` flag, defaulted to false, is a boolean indicating whether the output should be a direct binary equivalent of the message digest, or formatted as a hexadecimal string (the default).

### HMAC - crypto.hmac

crypto.hmac.digest(dtype, string, key [, raw])
  This function returns the HMAC of the `string`. The hashing algorithm to use is specified by `dtype`. The value provided in `key` will be used as the seed for the HMAC generation. The optional `raw` flag, defaulted to false, is a boolean indicating whether the output should be a direct binary equivalent of the HMAC or formatted as a hexadecimal string (the default).
crypto.hmac.new(dtype, key)
  Creates a new HMAC object using the algorithm specified by `type`. The HMAC seed key to use is provided by `key`.
hmac:reset()
  Resets the HMAC object to a clean slate.
hmac:clone()
  Returns a new HMAC object which is a clone of the object and its current state, including data loaded to this point. DOES NOT WORK YET. Just returns a new pointer to the same object.
hmac:update(string)
  Appends the data in `string` to the current internal data set to be hashed.
hmac:digest([string] [, raw])
  Generates the HMAC for the loaded data, optionally appending on new data provided by `string` prior to hashing. The optional `raw` flag, defaulted to false, is a boolean indicating whether the output should be a direct binary equivalent of the message digest or formatted as a hexadecimal string (the default). 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.

$Id: manual.html,v 1.1 2006/08/25 03:24:17 nezroy Exp $