luagcrypt

Luagcrypt is a Lua binding to the Libgcrypt cryptographic library. Symmetric encryption/decryption (AES, etc.) and hashing (MD5, SHA-1, SHA-2, etc.) are supported.

It is compatible with Lua 5.1, 5.2 and 5.3 and runs on Linux, OS X and Windows.

Installation

The minimum requirement is Libgcrypt 1.4.2 (libgcrypt-11), but at least Libgcrypt 1.6.0 (libgcrypt-20) is recommended. After ensuring that the Lua and Libgcrypt development headers and libraries are available, you can invoke make to build luagcrypt.so with Lua 5.2. See the Makefile file for available variables.

An alternative cross-platform method uses LuaRocks. Once you have checked out this repository, you can invoke:

luarocks make

Note for Windows users: the rockspec file uses libgcrypt-20 which is used since Wireshark 1.12. Older Wireshark versions use Libgcrypt 1.4.6 (libgcrypt-11). Header files and precompiled libraries (libgcrypt-20.dll and its dependency libgpg-error-0.dll) can be found here:

• Libgcrypt 1.8.3 for Wireshark 3.0: 64-bit, 32-bit (libgcrypt-20.dll, should be compatible with Wireshark 2.4 as well)
• Libgcrypt 1.7.6 for Wireshark 2.4/2.6: 64-bit, 32-bit (libgcrypt-20.dll)
• Libgcrypt 1.6.2 for Wireshark 2.2/2.0/1.12: 64-bit, 32-bit (libgcrypt-11.dll)

Be sure to build with Lua 5.2 (64-bit, 32-bit) if you intend to use the library with Wireshark.

Documentation

The interface closely mimics the Libgcrypt API. The following text assume the module name to be gcrypt = require("luagcrypt") for convenience.

Available functions under the module scope:

• Symmetric cryptography - cipher = gcrypt.Cipher(algo, mode[, flags])
• Hashing - md = gcrypt.Hash(algo[, flags])
• version = gcrypt.check_version([req_version]) - retrieve the Libgcrypt version string. If req_version is given, then nil may be returned if the required version is not satisfied.

For the documentation of available functions, see the Libgcrypt manual. The above constructors correspond to the gcry_*_open routines. Resource deallocation (gcry_*_close) are handled implicitly by garbage collection. Length parameters are omitted when these can be inferred from the string length. For example, Libgcrypt's gcry_cipher_setkey(cipher, key, key_len) matches cipher:setkey(key) in Lua.

An error is thrown if any error occurs, that is, when the Libgcrypt functions return non-zero. (The error message text may change in the future.)

Constants like GCRY_CIPHER_AES256 are exposed as gcrypt.CIPHER_AES256 (without the GCRY_ prefix).

Example

The test suite contains representative examples, see luagcrypt_test.lua.

Another full example to calculate a SHA-256 message digest for standard input:

local gcrypt = require("luagcrypt")
-- Initialize the gcrypt library (required for standalone applications that
-- do not use Libgcrypt themselves).
gcrypt.init()

-- Convert bytes to their hexadecimal representation
function tohex(s)
    local hex = string.gsub(s, ".", function(c)
        return string.format("%02x", string.byte(c))
    end)
    return hex
end

local md = gcrypt.Hash(gcrypt.MD_SHA256)

-- Keep reading from standard input until EOF and update the hash state
repeat
    local data = io.read(4096)
    if data then
        md:write(data)
    end
until not data

-- Extract the hash as hexadecimal value
print(tohex(md:read()))

Tests

The basic test suite requires just Libgcrypt and Lua and can be invoked with make check (which invokes luagcrypt_test.lua).

Run the code coverage checker with:

make checkcoverage LUA_DIR=/usr

License

Copyright (c) 2016 Peter Wu peter@lekensteyn.nl

This project ("luagcrypt") is licensed under the MIT license. See the LICENSE file for more details.