EscherLua - HTTP request signing lib

Lua implementation of the AWS4 compatible Escher HTTP request signing and authentication library. The library is compatible with the Nginx's HttpLuaModule and Openresty.

We are using it for our OpenResty based API gateway server for authenticating the requests, and route the request to our microservices with a different signature.

Prerequisite

In order to run the tests, Docker must be installed.

Setup

Some tips to setup the local development environment:

make build

Running tests

make tests

Examples

Authentication:

local escher = Escher({
    algoPrefix = "AWS4",
    vendorKey = "AWS4",
    hashAlgo = "SHA256",
    credentialScope = "us-east-1/host/aws4_request",
    authHeaderName = "X-EMS-Auth",
    dateHeaderName = "X-EMS-Date",
    date = "2011-09-09T23:36:00.000Z" -- give date for testing purposes only
})

local request = {
    method = "GET",
    url = "/",
    headers = {
        { "X-EMS-Date", "20110909T233600Z" },
        { "Host", "host.foo.com" },
        { "X-EMS-Auth", "AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20110909/us-east-1/host/aws4_request, SignedHeaders=x-ems-date;host, Signature=3a2b15801d517d0010be640f0685fa60b5d793396be38e0566ede3d334554479" }
    },
    body = ""
}

local my_key = "AKIDEXAMPLE"

local function keyDb(key)
    if key == my_key then
        return "1/K7MDENG+bPxRfiCYEXAMPLEKEY"
    end
end

local headersToSign = { "x-ems-date" }

local auth_key = escher:authenticate(request, keyDb, headersToSign)

assert(auth_key == my_key, "Auth key mismatch") -- should not throw error

Signing a request:

local escher = Escher({
    algoPrefix = "AWS4",
    vendorKey = "AWS4",
    hashAlgo = "SHA256",
    credentialScope = "us-east-1/host/aws4_request",
    authHeaderName = "X-EMS-Auth",
    dateHeaderName = "X-EMS-Date",
    date = "2011-09-09T23:36:00.000Z", -- give date for testing purposes only
    apiSecret = "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY",
    accessKeyId = "AKIDEXAMPLE"
})

local request = {
    method = "GET",
    url = "/",
    headers = {
        { "Host", "host.foo.com" }
    },
    body = ""
}

local headersToSign = { "x-ems-date" }

escher:signRequest(request, headersToSign)

--[[
request should now look like this:
{
    body = "",
    method = "GET",
    url = "/",
    headers = {
        { "Host", "host.foo.com" },
        { "X-EMS-Date", "Fri, 09 Sep 2011 23:36:00 GMT" },
        { "X-EMS-Auth", "..." }
    }
}
--]]

About Escher

More details are available at our Escher documentation site.