The Auxiliary Lua API

The auxiliary Lua APIs provide additional functionality including HTTP(S) client libraries, a mail (SMTP) client, (secure) sockets, and SSL certificate management.

The auxiliary Lua APIs are not part of the standard libraries and must therefore be compiled and integrated with your build. The source code for these APIs can be found in the xrc directory. The wfs and the lspappmgr example servers include all of the auxiliary APIs. Refer to one of these two examples for how to include and initialize the optional auxiliary Lua APIs.

In addition to the C code in the xrc subdirectories, the xrc/lua and subdirectories include Lua code that must be included in your build. The makefiles for the wfs and the lspappmgr assemble these files into the ".lua" directory in the lsp.zip ZIP file. The lsp.zip file is integrated into the example's executable and made available as the default I/O by the C startup code. The Lua function "require" is designed such that it searches for Lua modules in the ".lua" directory. As an example, an LSP page calling 'require("mail")' loads mail.lua and other required Lua modules from this directory. In other words, calling "require" unzips the files from the integrated ZIP file and loads the files as Lua modules.

Universal Binary JSON

The UBJSON API is identical in functionality to the standard JSON API, but uses Universal Binary JSON as the encoding format and not the standard JSON format.

ba.ubjson.parser()
ba.ubjson.encode(table [,table] [,size])
ba.ubjson.decode(data [,stacksize [,namelen [,offset]]])
-- Prints ["Hello World"]
print(ba.json.encode(ba.ubjson.decode(ba.rndbs(5)..ba.ubjson.encode{"Hello World"},1,0,5)))

ByteArray

The ByteArray, which is included in the Socket library, is a mutable companion to Lua's immutable string type. The ByteArray automatically converts to a string, when needed. In addition, the socket:write method can, in most cases, use the ByteArray directly without doing any additional copying. The ByteArray supports the following meta-methods: __index, __newindex, __tostring, and __len.

ba.bytearray.create(size)
ba.bytearray.create(string)

Create a 'size' length ByteArray or create a ByteArray from string.

ba.bytearray.setsize(array, i [, j])

Changes the array's start and optionally, the end marker. Changing the start and end markers makes it possible to (temporarily) shrink the array to a smaller size. All meta-methods are affected by calling this function. The start and end markers i and j can be negative. If j is absent, then it is assumed to be equal to -1.

ba.bytearray.size(array)

Returns three values: the array's real size, the start marker position, and the end marker position. If ba.bytearray.setsize() has not been called, the start marker is one and the end marker is the allocated array size.

ba.bytearray.tostring(array, [, i [, j]])

Returns a (sub)string representation of the array that optionally starts at i and continues until j; i and j can be negative. If i is absent, then it is assumed to be equal to 1, If j is absent, then it is assumed to be equal to -1 (which is the same as the array length).

Examples

In the following examples, the __tostring metamethod is triggered when the array is printed.

local array = ba.bytearray.create(23)
for i=1,20 do array[i]=64+i end

print(#array) -- 23
ba.bytearray.setsize(array,1,20)
print(#array) -- 20
print(ba.bytearray.size(array)) -- 23	1	20
print(array) -- ABCDEFGHIJKLMNOPQRST

local t={}
 -- #array length is 20
for i=1,#array do table.insert(t,array[i]) end
ba.bytearray.setsize(array) -- same as: (array,1,-1); length is now 23

array[1]="abcdefghijklmnopqrstuvz"
print(array) -- abcdefghijklmnopqrstuvz

array[4]=t -- Copy table into ByteArray starting at position 4
print(array) -- abcABCDEFGHIJKLMNOPQRST

ba.bytearray.setsize(array,-3) -- Same as (array,-3,-1)
print(#array,array) -- 3	RST

ba.bytearray.setsize(array) -- Restore normal size
for i=1,#array do array[i]='*' end -- Fill with '*'

ba.bytearray.setsize(array,4)
array[1]=t -- Copy table
print(array) -- ABCDEFGHIJKLMNOPQRST
ba.bytearray.setsize(array,1,-4)
print(array) -- ***ABCDEFGHIJKLMNOPQ

Crypto Library

ba.crypto.hash([algorithm [, algorithm, key]])

Creates and returns a cryptographic hash function with the given algorithm, which can be used to generate hash digests. The algorithm defaults to sha1 if no arguments are provided. Valid options for the first argument "algorithm" are one of the following strings: md5, sha1, sha256, sha384, sha512, and hmac. The optional second and third argument must be provided when the first argument is hmac. The second and third arguments are ignored for all other hash functions. When the first argument is hmac, the second argument must be one of the following: "md5", "sha1", "sha256", "sha384", or "sha512". The third argument "key" is the secret HMAC key.

The returned function accepts the following arguments:

The following example shows how to calculate B64(MD5(username password)):

local hfunc = ba.crypto.hash"md5"
hfunc(username)
hfunc(password)
local data = hfunc(true,"b64")

The hash function returns a copy of itself when being fed data, thus making it possible to chain the functions. The following example produces the same result as the above example:

local data = ba.crypto.hash"md5"(username)(password)(true,"b64")

The following example shows how to create an MD5 HMAC for the username and password by using the secret key "qwerty".

local data = ba.crypto.hash("hmac","md5","qwerty")(username)(password)(true,"b64")
DK = ba.crypto.PBKDF2(PRF, Password, Salt, c, dkLen)

PBKDF2 is a simple cryptographic key derivation function, which is resistant to dictionary attacks and rainbow table attacks. It is based on iteratively deriving HMAC many times with some padding. The PBKDF2 algorithm is described in the Internet standard RFC 2898 (PKCS #5).

Asymmetric Encryption

Encrypt, decrypt, sign, and verify using RSA X.509 keys and X.509 certificates.

ba.crypto.keysize(key [,op])
Returns the key-size.
ba.crypto.encrypt(data, cert [,op])
Encrypt data using the public key component.
ba.crypto.decrypt(encdata, key [,op])
Decrypt data using the private key component.
ba.crypto.sign(data, key [,op])
Sign data using the private key component.
ba.crypto.verify(encdata, cert [,op])
Verify data using the public key component.
Function arguments

All asymmetric encryption functions take the same set of arguments.

  • string data - the data to be encrypted. The length of the data must be no larger than key-size - 11 or exactly key-size if the nopadding option is set to true.
  • string encdata - the encrypted data to be decrypted. The length of the data must be exactly key-size.
  • string key - an X.509 key. Password protected keys require the password option.
  • string cert - an X.509 certificate. For ba.crypto.verify, the cert can be a table with "n" and "e", matching the public key component for an RSA certificate. This mode is designed for JWT verification of RS256 signed signatures. In this case, the function return true for verified and false if not verified.
  • table op - options:
    • string password - required for password protected X.509 keys.
    • boolean nopadding - set the no padding option.

Symmetric Encryption

ba.crypto.symmetric(algorithm, key, IV [, mode])

Encrypt or decrypt data using a symmetric cipher.

Arguments:

Returns an object with the following methods:

s:setauth(auth)
Set the optional Additional Authenticated Data (AAD) for GCM and CCM.
s:encrypt(data [,"PKCS7"])
Encrypt data. The function returns the encrypted data and a 16 byte tag (hash) when using the cipher GCM and CCM. Max data size is 0xFFF0. Larger data sets must be encrypted in chunks. The argument "PKCS7" must be set for the last encrypted chunk.
s:decrypt(encdata [,tag [,"PKCS7"]])
Decrypt data. The tag (hash) is required when using the cipher GCM and CCM. Max data size is 0xFFF0.

Examples:

AES-GCM example:

local fp = ba.openio"disk":open"FILE NAME"

local key = "0123456789ABCDEF" -- Preferably use ba.rndbs(16) or ba.rndbs(32)
local iv = "0123456789AB" -- Preferably use ba.rndbs(12)

local encrypt = ba.crypto.symmetric("GCM", key, iv)
local decrypt = ba.crypto.symmetric("GCM", key, iv)

local auth='Optional "Additional Authenticated Data" (AAD)'
encrypt:setauth(auth)
decrypt:setauth(auth)

while true do
   local data=fp:read(0x500)
   if not data or #data ~= 0x500 then
      -- Last chunk is padded using PKCS7
      local cipher,tag = encrypt:encrypt(data,"PKCS7")
      print(decrypt:decrypt(cipher,tag,"PKCS7"))
      break
   end
   local cipher,tag = encrypt:encrypt(data)
   print(decrypt:decrypt(cipher,tag))
end
fp:close()
  

Fernet (AES-CBC) Decrypt Example:

Fernet is common in the Python world and provides a simple method for encrypting and decrypting a message. The following article shows how to use it from Python as well as providing a good introduction to the format: pythoninformer.com.

local function decodeFernet(key,token)
   key,token=ba.b64decode(key),ba.b64decode(token)
   if key and token and token:byte(1) == 0x80 then
      local signingKey,encryptionKey=key:sub(1,16),key:sub(17)
      local iv,cipher,hmac = token:sub(10,25),token:sub(26,-33),token:sub(-32)
      if hmac ~= ba.crypto.hash("hmac","sha256",signingKey)(token:sub(1,-33))() then
         return nil, "Invalid HMAC"
      end
      local datetime = ba.datetime(ba.socket.n2h(8,token,2))
      local plain=ba.crypto.symmetric(
         "CBC",encryptionKey,iv,"decrypt"):decrypt(cipher,"PKCS7")
      return plain,datetime
   end
   return nil, "Invalid key or token"
end

local key="M516vNeYFaEauWp_C7Dovyms7ZF1xNyizKPFZ4ucBS0="
local token=[[
gAAAAABftfpRGg8HwvomaO8Uj71gJgplLDJH05-
OcprsFgw2aAYt1b7ngdUv7vsfPGNdxr-WjpaFY8
gx9Gf-j8qiJrpFaVg3BQ==
]]

local text,datetime = decodeFernet(key,token)
if text then
   print("Text:",text)
   print("DateTime:",datetime)
else
   print("Error:",datetime) -- datetime is now error
end
  

Cryptographic Parameters

The following functions enable extraction of cryptographic parameters used with JSON Web Tokens and JSON Web Signatures.

ba.crypto.keyparams(privkey)
Extracts and returns the public key parameters from an X.509 PEM encoded key, such as the key returned by ba.create.key. The function is currently limited to ECC keys and the function returns the public ECC (x,y) coordinates.
ba.crypto.sigparams(signature)
Extracts and returns the signature parameters from a DER encoded binary string, such as the return value from ba.crypto.sign. The function is currently limited to ECC keys and the function returns the signature pair (r,s).

JSON Web Token (JWT) Library

A compact JWT library designed for creating and signing JSON Web Tokens (JWT). The library supports HS256 and ES256 signatures. The library is loaded as follows:

local jwt=require"jwt"
jwt.jwkh(privatekey)
Returns a JSON Web Token (JOSE) header with a JSON Web Key (JWT). The JWT includes the ECC key's public X,Y coordinates, which may be used by some servers for signature verification.
jwt.sign(key, payload [, header])

Arguments:

Returns: a table with the values protected, payload, signature

jwt.scomp(key, payload [, header])

This function is identical to jwt.sign, except for the return value, which is a JWS compact string in the following format:

The structure of a JWS token using compact serialization

HS256 Signature Example:

  1. Copy and run the LSP example below using, for example, the Mako Server
  2. Copy the result printed in the browser
  3. Navigate to jwt.io and select HS256
  4. Make sure the payload on jwt.io is identical to the payload in the example below
  5. Set the secret to my-secret
  6. Paste the copied signature to the Encoded form
  7. You should see Signature Verified at the bottom
<?lsp
local header = { alg="HS256", typ = "JWT"}
local payload = {
  sub = "1234567890",
  name = "John Doe",
  iat = 1516239022
}
print(require"jwt".scomp("my-secret",payload, header))
?>

JSON Web Token Signature Example:

The following example shows how to create a JSON Web Token with an ECDSA P-256 JSON Web Signature. A JSON Web Signature may need a JSON Web Key (JWT) with the key's public X,Y coordinates. The following example uses function jwt.jwkh to create a JOSE header with a JWK including the X,Y coordinates (the public key).


<?lsp
local key=[[
 Insert private key from: https://jwt.io/
]]

local payload={
  sub = "1234567890",
  name = "John Doe",
  admin = true,
  iat = 1516239022
}

local jwt = require"jwt"
print(jwt.scomp(key, payload, jwt.jwkh(key)))
?>

Run the example as follows:

  1. Copy the above example and save the file as an LSP page
  2. Navigate to jwt.io and select the ES256 algorithm
  3. Copy the complete private key from jwt.io and paste the key into the above example for the 'key' variable
  4. Run the lsp page using the server
  5. Copy the output (the result) and paste the result into the encoded field at jwt.io
  6. The Signature should now be verified

Notice that the jwt.io service does not use the jwk in the header for validation. The service relies on verifying the signature by using the x.509 encoded public key on the page. The service fails if you remove the public key. Some services are able to use the jwk with the embedded public key for verification purposes.

Mail (SMTP) Client Library

The SMTP library provides functionality to send e-mail messages. The SMTP library supports authentication and secure SMTP. The implementation conforms to the Simple Mail Transfer Protocol, RFC 2821.

The SMTP library provided with the Barracuda Embedded Web Server is an enhanced version of the LuaSocket SMTP library, which also supports SSL/TLS and STARTTLS email encryption. See email encryption protocols for more information.

The SMTP library is designed for blocking sockets and cannot be used with our asynchronous socket API. If you are not using the SMTP library from an LSP page, make sure you run the SMTP code in the context of the Lua Thread Library. See threading for more information.

Simplified SMTP Client Library

We have created a wrapper library that simplifies the use of the LuaSocket SMTP library. You can choose to directly use the LuaSocket SMTP library or the simplified SMTP library provided by Real Time Logic. The simplified SMTP client library does not require that you have detailed knowledge of MIME encoding or knowledge in how to use LTN012, Filters sources and sinks. The following documentation is for the simplified SMTP library. See the LuaSocket SMTP documentation if you prefer to use the more technical API.

The Simplified SMTP client library, called "mail", makes it easy to send text and html emails. The library also makes it easy to embed images for the html and to add file attachments. The following example shows how to send an email using a standard SMTP server.

require "socket.mail" -- Load mail lib

local mail=socket.mail{server = "smtp.example.com"} -- Create a mail object

-- Send one email
local ok,err=mail:send{
   subject="Hello",
   from='Bob <bob@example.com>',
   to='Alice <alice@example.com>',
   body=[[
     Hello Alice,
     This is a test.
   ]]
}

Simplified SMTP Client Library API

socket.mail{
server = string,
[port = number,]
[user = string,]
[password = string,]
[shark=SharkSSL object,]
[starttls=true]
}

Creates a simplified SMTP client object. The socket.mail function takes a table as argument with the following required and optional attributes:

mail:send{
subject=string,
from=string,
to=string|table,
[replyto=string,]
[cc=string|table,]
[bcc=string|table,]
[txtbody=string|fp,]
[htmlbody=string|fp,]
[htmlimg=table,]
[attach=table,]
[encoding="QUOTED" | "B64" | "8BIT" | "NONE"]
[charset=string]
}

In the above, string|fp means either a string with text/binary data or a file pointer. A file pointer can be from opening a file using the standard Lua I/O function or from a Barracuda I/O. Examples: fp=io.open("/path/img.gif"), fp=ba.openio("disk"):open("/path/img.gif").

Email addresses:
Email addresses can be any of the following:

Mail Examples

Creating the mail object

The following example configures and creates a mail object for the secure Google SMTP server:

local mail=socket.mail{
   shark=ba.sharkclient(), -- Use TLS
   server="smtp.gmail.com",
   user="YOUR GOOGLE EMAIL ADDRESS",
   password="YOUR GOOGLE PASSWORD",
}

Notice that we use the SharkSSL object returned by ba.sharkclient() in the above example.

The following example configures and creates a mail object for the STARTTLS version of the hotmail SMTP server:

local mail=socket.mail{
   shark=ba.sharkclient(), -- Use TLS
   starttls=true, -- Start as a normal socket and then later upgrade to TLS
   server="smtp.live.com",
   user="YOUR HOTMAIL EMAIL ADDRESS",
   password="YOUR HOTMAIL PASSWORD",
   port="587",
}
Sending emails

The following example sends an HTML email to Alice by opening and reading the file "emails/alice.html":

local ok,err=mail:send{
   from='Bob <bob@example.com>',
   to='Alice <alice@example.com>',
   subject="Hello",
   htmlbody=io:open"emails/alice.html"
}

It is good practice to embed a plain text version of the HTML email. The following example sends a combined text and HTML email:

local ok,err=mail:send{
   from='Bob <bob@example.com>',
   to='Alice <alice@example.com>',
   subject="Hello",
   txtbody="This is the text body",
   htmlbody=[[
        <html>
          <body>
            <h1>This is the html body</h1>
          </body>
        </html>
   ]]
}

The following email shows how to send a combined text and HTML image. The HTML includes an embedded image. The email also includes one attachment:

local ok,err=mail:send{
   from='Bob <bob@example.com>',
   to='Alice <alice@example.com>',
   subject="Hello",
   txtbody="This is the text body",
   htmlbody=[[
        <html>
          <body>
            <h1>This is the html body</h1>
            <img src="cid:the-unique-id" alt="Text shown by text only clients">
          </body>
        </html>
   ]],
   htmlimg = {
      id="the-unique-id",
      name="logo.gif",
      source=io:open"logo.gif"
   },
   attach={
      description="A document",
      name="my-document.pdf",
      source=io:open"my-document.pdf"
   }
}

Notice how the image source attribute is set to a unique ID. You must create a special HTML file where each embedded image has its own unique ID.

Sending E-Mails Via a Proxy

The SMTP server's domain name can be a name (string) or an already established socket connection. Using a socket connection is useful when the SMTP client requires connecting to the Internet via a proxy. The following example shows how to send an email using Google Mail and how to establish the connection via a local proxy by using the HTTP client library and the "proxycon" setting.

require "socket.mail" -- Load mail lib

local http = require"httpc".create{
      proxy="localhost", -- Using local proxy
      socks=true, -- Enable SOCK5
      proxycon=true, -- Use the HTTP lib for opening a proxy connection
      proxyport=1080, -- SOCKS5 port number
}
-- Connect to google mail at port number 465
local ok,status = http:request{url="http://smtp.googlemail.com:465"}
if status == "prxready" then -- If proxy connection ready
   local mail=socket.mail{
      server=ba.socket.http2sock(http), -- Extract socket object
      shark=ba.sharkclient(), -- Implicit if not set
      user="john.doe@gmail.com",
      password="the-password",
   }
   -- Send email
   local ok,err=mail:send{
      subject="Hello",
      from='John Doe <john.doe@gmail.com>',
      to='Janie Doe <janie@doe.com>',
      body="Hi Janie"
   }
end

HTTP(S) Client Libraries

The Barracuda HTTP(S) client library, which is implemented in C code, can be accessed from Lua by using the Lua bindings for the HTTP implementation. The Lua bindings are found in xrc/lua/lhttp.c.

In addition to the low level C implementation, two additional HTTP libraries implemented in Lua are provided. The additional libraries wrap around the low level library and simplify the use of the low level implementation. The two Lua scripts are found in the xrc/lua/ directory. The two scripts are also embedded in the wfs and the extended Lua interpreter.

The libraries are loaded as follows:

The HTTP(S) Client Libraries implementation conforms to the HTTP/1.1 standard, RFC 2616.

Important information:
The HTTP client libraries use blocking socket calls and should therefore run in the context of the Server HTTP Thread Pool such as an LSP page or the Lua Thread Library. See threading for more information.

The following example shows how to send JSON data as part of the HTTP body to a JSON echo service. The service responds with the original data and additional JSON data. Note that many JSON services are designed to accept POST data as URL encoded data and not directly as JSON as used in the following example. The method http:json() has been specifically designed to post JSON using URL encoded key/value pairs.

local rdata -- rec data
local sdata={ -- data to send
   hello = "world",
   vector = { i=10, j=15 }
}

local http = require"httpc".create()

local ok,err=http:request{
   url="http://postman-echo.com/post",
   method="POST",
   header={["Content-Type"]="application/json; charset=utf-8"}
}
if ok then
   ok,err=http:write(ba.json.encode(sdata))
   if ok then
      rdata,err=http:read"*a"
   end
end
if rdata then
   print("Rec Data:", rdata)
   print("Valid JSON: ", ba.json.decode(rdata) and "yes" or "no")
else
   print("Err:",err)
end

The "httpc" library

The library is loaded and an HTTP instance is created as follows:

local http = require"httpc".create([op])
The HTTP Option Table:

Returns an instance of the low level HTTP library.

The option table:
  • shark = SharkSSL object -- The SharkSSL object is required when using secure connections (when the URLs starts with https://). The SharkSSL object provided by ba.sharkclient() is used if the shark attribute is not set for HTTPS connections.
  • persistent=bool -- Set/disable persistent HTTP1.1 connections. The Default is to enable persistent connections.
  • intf = string -- Bind to interface-name/IP-address. The default is to bind to any interface.
  • ipv6 = bool -- Use of IPv6 address translation. Note, the server must have been compiled with IPv6 support.
  • proxy = string -- Use a HTTPS or SOCKS5 proxy with IP address or domain name "proxy".
  • proxyport = number -- Proxy port number defaults to 8080 for HTTPS proxy and 1080 for SOCKS5 proxy.
  • socks = bool -- Set to true if you are using a SOCKS5 proxy. The default is to use HTTPS proxy by using HTTP CONNECT.
  • proxyuser = string -- Proxy authenticate using username.
  • proxypass = string -- Proxy authenticate using password.
  • proxycon = bool -- Set to true to initiate proxy connection but without sending any data to the server. The HTTP client library may be used to initiate socket connections via a proxy for other protocols. When the required proxy parameters are set and when proxycon is set to 'true', a connection is established via the requested proxy when http:request() is called. If successful, http:request() returns the special error code "prxready". See the MQTT proxy example for details.

Methods:

The methods associated with the object returned by require"httpc".create()

http:timeout(milliseconds)

Set the number of milliseconds before connect, read, and write times out. The default is 20000 i.e. 20 seconds. A value of zero waits indefinitely. The maximum value is 3240,000.

http:request(op)

Returns true on success.
On error: returns nil followed by an error code or a number. The error code is provided if some form of socket error occured. The number is only returned if a proxy is installed. The number corresponds to the HTTP status. Example: 407 Proxy Authentication Required.

The option table:
Required attributes:
  • url = string -- URL to the server resource.
  • method = string -- Valid values: DELETE, GET, HEAD, PATCH, POST,and PUT.
Optional attributes:
  • header = table -- A table with key value pairs. Include additional HTTP headers.
  • query = table -- A table with key value pairs. Include url encoded data in the query component of the request URL. Example: query={key1="a", key2={"b1", "b2", "b3"}}
  • user = string -- Authenticate using username.
  • password = string -- Authenticate using password.
  • size = number -- Size is an optional length when sending data to a server using POST or PUT. The client sends data using chunked transfer encoding if no size is specified.
  • trusted = bool -- Force method http:request to accept only trusted connections when connecting to a server. This option requires that you have a SharkSSL object with an installed Certificate Authority Store. The connection is closed and the function returns nil,"nottrusted" if the certificate is not trusted, expired, or if the domain name does not match the domain name in the certificate. See also http:trusted.
http:status()

Returns the HTTP server response code.

http:header()

Returns a table with the HTTP header key/value pairs.

http:headerpairs()

Returns an iterator that will traverse all the HTTP header key/value pairs.

http:cookie()

Returns an iterator that will extract and traverse all cookies sent by the server.

The server may send multiple "Set-Cookie" headers:

   Set-Cookie: name=value [; expires=date] [; path=path] [; domain=domain] [; secure]

The iterator returns the cookie name, value, and an optional table. The table is returned if the cookie returned by the server contains more than just the cookie name. The table provides {key, value} pairs, where the keys can be one of the following: expires, path, domain, and secure.

   for name,value,t in x:cookie() do
      print("cookie name:", name, ",value", value)
      if t then
         for k,v in pairs(t) do
            print(k,v)
         end
      end
   end
http:read(size)

Read size bytes.

size is one of:
  • "*a" for all data.
  • Number(n) for reading n bytes.
  • Not provided. Makes the read function silently consume and discard response data.
http:write(n)

Write n bytes.

Returns true on success.
On error: returns nil followed by an error code or a number. The error code is provided if some kind of socket error occured. The number is the HTTP response code. For example, if uploading data fails and the server sends a HTTP response code while the client is uploading, the uploading is aborted immediately, and the HTTP response code is returned to the caller.

The caller can set a "Expect: 100-continue" header prior to uploading data, but this is not necessary since the write function asynchronously detects if the server denied the upload. Any 100 continue messages sent by the server are silently consumed by the write function.

Note: The data is uploaded using chunked transfer encoding unless the size attribute was set on the http:request() option table. Not all servers support chunked transfer encoding.

http:certificate()

Returns the peer's certificate chain as a table if the connection is secure and the peer sent a certificate. A second return value is set to true if the certificate is valid i.e. if validated by the certificate store.

http:cipher()

Returns the cipher suite and SSL protocol version being used if the connection is secure. See socket:cipher() for more information on the return values.

http:trusted()

Returns the peer's "trust" status.

http:peername()

Returns a string of the client name/IP address, the connected port number, and a boolean value set to true for IPv6 and false for IPv4.

http:sockname()

Returns a string of the server name/IP address, the connected port number, and a boolean value set to true for IPv6 and false for IPv4.

http:close()

Close the connection.

The "http" library

The "http" library wraps around the low level C implementation and simplifies the use of the low level implementation.

The library is loaded and an HTTP instance is created as follows:

local http = require"http".create([op])

Redirect management:

Many server applications may send a 302 temporary redirect request or a 301 permanent redirect request when accessing resources. The server resource may for example redirect to the same resource, but request the client to add or change URL encoded data when accessing the server. The "http" library automatically manages 301 and 302 requests. The client library computes the new URL and sends a new request. This sequence continues until the server returns a non 301/302 response or the redirect counter detects an infinite redirect loop. The extra http:url() method provided by the "http" library returns the computed URL and query data the server may have requested the client to perform.

Default http:request() options:

One of the benefits of the Lua implemented wrapper is that it simplifies the use of the option table. Options that are required on method http:request() can be set when creating the HTTP client instance. The following example illustrates this:

local http=require"http"

-- Set default options that are required by http:request()
local op={
   url="https://localhost/mypage.lsp",
   method="GET"
}
local h=http.create(op)

 -- Use default options: method "GET" and url https://localhost/mypage.lsp"
h:request()
h:read"*a" -- silently consume the response

h:request{method="HEAD"} -- Override default "GET" method
print(h:status())

h:request() -- We are using "GET".
h:close() -- We are done

An instance of the "httpc" library would have thrown an exception when calling h:request(), but the Lua version remembers the extra options added when we created the object.

You can optionally provide an option table and override any of the default settings. The HEAD request above illustrates this.

Methods:

The "http" library provides, in addition to the "httpc" methods, the following method:

http:url()

Returns the url and query data as a table for the current connection. The url and query data may be different on server response than the values set when connecting since the server can send redirect responses. The redirect response is internally managed by the "http" library.

The "httpm" library

The "httpm" (HTTP Managed) library extends the "http" library and simplifies common tasks such as uploading and downloading data, sending HTTP POST requests, and communicating with a server using JSON.

The library is loaded and an HTTP instance is created as follows:

local http = require"httpm".create([op])

Methods:

The "httpm" library provides, in addition to the "http" methods, the following methods:

http:stat(url [,op])

Returns a table of attributes for the named url -- the resource . If the resource does not exist, 'nil' followed by an error code is returned. The fields of the table are named as follows:

This function is by default using the HTTP method "HEAD". You can change the HTTP method by setting op={method="method-type"}

Examples:

local http = require"httpm"
local h=http.create(my-option-table)
local st,err=h:stat("http://my-server/my-resource")
if st then print(st.size,st.mtime) end
-- Override default options
tab,err=h:stat("http://my-server/my-resource",
                     { method="GET", query={foo="bar"}})
if st then print(st.size,st.mtime) end

http:post(url,tab [,op])

Send a HTTP POST request to a server. This function emulates a HTML form submit in a browser.

The method returns http-status,response-body on success and nil,error-msg on error.

The following example is sending url encoded data in the query component of the URL and in the body of the message.

local http = require"httpm"
local h=http.create(my-option-table)
local ok,err=h:post("https://myserver/myresource",
                    {foo="Hello"},
                    {query={bar="world"}})
http:upload(conf [,op])

Upload a file to a server. This function is by default using the HTTP method "PUT". You can change the HTTP method by setting op={method="POST"}

The function can be used in two modes:


The HTTP library is monitoring response data from the server while the upload is in progress. The upload is automatically terminated if the server sends an error response. It is for this reason not necessary to do the typical one byte test upload prior to uploading the actual data to test if the server accepts the upload. HTTP 100-continue messages sent from the server are silently consumed.

http:download(conf [,op])

Download a file from a server and save the file. The function can be used in two modes:

http:json(url, data [,op])

Load JSON-encoded data from the server using a HTTP GET request. This function, which is designed for server side Lua code, is similar in functionality to the jQuery.getJSON() function in the JQuery JavaScript library.

Example 1:

-- Get IP address from http://www.jsontest.com/
local http=require"httpm".create()
local t,err=http:json("http://ip.jsontest.com/",{})
if t then -- If we got a Lua table (decoded JSON)
   print("IP address:",t.ip)
end

Example 2:

-- Connect to a Web-File-Manager in a Barracuda server
-- and request a JSON directory listing.
local t,err = http:json("http://localhost/fs/", {cmd="lj"})
if t then
   for _,r in ipairs(t) do -- Iterate all resources
      response:write("name=",r.n,", size=",r.s < 0 and "DIR" or r.s,
                     ", date=",os.date("%c",r.t),"<br>")
   end
else
   response:write(err)
end

See also how to send JSON as part of the HTTP body.

Socket API

The TCP and UDP socket API provide easy to use functions for creating client and server TCP connections and for working with UDP sockets. The TCP socket API is integrated with our own SSL stack SharkSSL™, thus making it very easy to create secure custom protocols. The TCP socket API enables interceptions of HTTP client and server connections at any point, making it possible to morph an HTTP(S) connection into an HTTP(S) tunnel, which can be used for (secure) custom protocols that can bypass proxies and firewalls.

Note that UDP socket is not supported on all embedded/RTOS platforms.

The socket API can be used in three modes:

See the section Designing Socket Protocols in Lua for an introduction to the Lua socket API.

The Barracuda socket API is not identical to the standard LuaSocket, but a compatibility layer is included that makes it possible to use code designed for the Lua socket API such as the mail (SMTP) client.

Functions

ba.socket.bind(port [,op])

Creates and returns a TCP server object bound to a local port, ready to accept client connections.

The option table:
  • intf = string -- Bind to interface-name/IP-address. The default is to bind to all interfaces.
  • ipv6 = bool -- Use IPv6 address translation for 'intf'. Note, the server must have been compiled with IPv6 support. One can typically open two connections on the same port and interface if one is an IPv4 address and the other is an IPv6 address.
  • shark = SharkSSL object -- Accept SSL connections.
ba.socket.connect(address, port [,op])

Creates and returns a TCP client object connected to a remote host/address at a given port.

The option table:
  • intf = string -- Bind to interface-name/IP-address. The default is to bind to any interface.
  • ipv6 = bool -- Use IPv6 address translation for 'address'. Note, the server must have been compiled with IPv6 support.
  • shark = SharkSSL object -- Connect using an SSL connection. The SharkSSL object must be initialized as a TLS client.
  • timeout = number -- Set the maximum time to wait in milliseconds for connection establishment. The timeout value is supported for asynchronous connections and for synchronous (blocking connections) on platforms where the porting layer interfaces to a BSD socket API.

Examples:

The two examples below connect to Real Time Logic's web server at port 443 (the HTTPS/TLS) port. The first example validates Real Time Logic's certificate using the list of Certificate Authority (CA) certificates the SharkSSL object returned by ba.sharkclient() is initialized with. The second example creates a new SharkSSL object with an empty certificate store, thus the example is unable to validate the certificate. See sock:trusted() for more information on the return values.

local s = ba.socket.connect("realtimelogic.com", 443, {shark=ba.sharkclient()})
print(s:trusted()) -- prints: true
print(s:trusted("sharkssl.com")) -- prints: nil	cert
s:close()

local s = ba.socket.connect("realtimelogic.com", 443, {shark=ba.create.sharkssl()})
print(s:trusted()) -- prints: nil	cn
print(s:trusted("sharkssl.com")) -- prints nil	none
s:close()
ba.socket.udpcon([address, port] [,op])

Creates and returns a connected or unconnected UDP object. The object is unconnected if address and port are not provided.

The option table:
  • intf = string -- Bind to interface-name/IP-address.
  • port = number -- Bind to port number.
  • ipv6 = bool -- Create an IPv6 socket. Note, the server must have been compiled with IPv6 support.
ba.socket.req2sock(request)

Extracts the active socket connection from the request object. This function, which can only be called from an LSP page or a directory function, makes it possible to morph an HTTP(S) connection into an HTTP(S) tunnel, which can be used for (secure) custom protocols. This function can also upgrade a WebSocket request to a WebSocket connection. The LSP page response object cannot be used after this function is called. Thus if you want to send an HTTP response, the response must be flushed by calling response:flush prior to calling this function. Note: an HTTP response is sent automatically by this function when upgrading a WebSocket request to a WebSocket connection.

This function returns the socket object and any additional data the server received following the HTTP header when upgrading regular HTTP to a socket connection. The second return value is nil if no additional data is available or if upgrading to a WebSocket connection.

ba.socket.http2sock(httpclient)

Extracts the active socket connection from an HTTP client object. The function is typically called after sending the request and calling http:status(). This function can also upgrade a WebSocket request to a WebSocket connection.

The following example connects to a web server running on localhost:80, extracts the socket connection from the HTTP client object, and starts an asynchronous coroutine that reads data until end of stream. End of stream is assumed when the receive function receives no data for 2 seconds.

require"http"

local function recData(s)
   local data,err
   data=true
   while data do
      -- s:read returns nil when no data received for 2 seconds
      data,err = s:read(2000)
      trace(data) -- Print response data to trace.
   end
   if err then trace("Read failed", err) end
   -- Socket is closed on return
end

local c = require"httpc".create()
c:request{url="http://localhost",method="GET"}
local s,err=ba.socket.http2sock(c)
if s then
   s:event(recData, "s")
end
ba.socket.toip(address[,ipv6])

Looks up address by using DNS and translates address to an IP address. Forces the use of IPv6 address translation if the optional parameter is true. Note, the server must have been compiled with IPv6 support.

This function is useful when using asynchronous sockets since DNS lookup may take some time (DNS lookup is blocking). Lua code can be designed such that the address is resolved by code that is allowed to block. The address can be cached such that the non blocking coroutines can use the IP address when connecting to peers.

ba.socket.event(function [,args])
Runs a Lua callback function as a cosocket. The provided function (parameter one) is immediately resumed with the first parameter being the socket, and subsequent parameters being the optional "args". The Lua callback function is resumed in the context of the thread running the Socket Event Dispatcher as soon as the Lua callback function calls the first socket function. All socket operations performed in the function will appear to be blocking, but most functions are asynchronous behind the scene. The function that may block is ba.socket.connect, when using a domain name that must be resolved to an IP address by DNS lookup. See cosockets for more information.

The function returns the socket object.

See also socket:event.
ba.socket.getsock()

Returns the socket object of the current Lua thread state if the current state is a socket coroutine. See also method socket:owner.

ba.socket.h2n(size,number)

Host (integer) to network (big endian data stream) conversion.

size - number of bytes to convert from the number -- e.g. 2 converts a 16 bit number and 4 converts a 32 bit number.
number - the number to convert.

The function returns the converted number as a binary string, where the data is stored in network endian format.

ba.socket.fh2n(size,number)

Host (float) to network (big endian data stream) conversion.

size - number of bytes to convert from the number -- must be 4 for float and 8 for double precision. No other values are accepted.
number - the number to convert.

The function returns the converted number as a binary string, where the data is stored in network endian format.

ba.socket.n2h(size,string [, start])

Network (big endian data stream) to host (integer) conversion.

size - the byte size to read and convert -- e.g. 2 converts a 16 bit number and 4 converts a 32 bit number.
string - the binary data string
start - defaults to 1 and is the offset position in the string.

The function returns the converted data as a number in host endian format.

ba.socket.fn2h(size,string [, start])

Network (big endian data stream) to host (float) conversion.

size - the byte size to read and convert must be 4 for float and 8 for double precision. No other values are accepted.
string - the binary data string
start - defaults to 1 and is the offset position in the string.

The function returns the converted data as a number in host endian format.

ba.socket.stat()

Returns the total number of socket objects and the number of active socket objects. An active connection may not necessarily be connected.

Socket Object Methods

Socket objects returned by ba.socket.bind(), ba.socket.connect(), ba.socket.req2sock(), and ba.socket.http2sock() have the following methods associated with them:

TCP: socket:read([timeout])
UDP: socket:read([timeout][,true])

Reads data from socket. The function blocks indefinitely if timeout (in milliseconds) is not provided. The function automatically yields if the caller is a socket coroutine and no data is available on the socket. The maximum timeout value for a synchronous connection is 3240,000.

UDP: use recv when the optional boolean is not set or is false. Use recvfrom when the boolean value is set to true.

Limitations: a cosocket must call the socket:read() method from within its own cosocket (the cosocket loop) -- in other words, when in cosocket mode, method socket:read() cannot be called unless method socket:owner() returns true. An exception is thrown if the read method is called on a cosocket outside its own cosocket. A cosocket that is operating in Remote Proceedure Call (RPC) mode should call method socket:disable() when no data is expected. Code outside of the cosocket can re-enable the cosocket by calling method socket:enable().

Returns:

See WebSocket frames for more information on the return values for WebSocket connections.

unconnected:sendto(datagram, ip, port)

Sends a datagram to the specified IP address and port number.

Datagram is a string with the datagram contents. The maximum datagram size for UDP is 64K minus IP layer overhead. However, datagrams larger than the link layer packet size will be fragmented, which may deteriorate performance and/or reliability. Ip is the IP address of the recipient. Host names are not allowed for performance reasons.

If successful, the method returns true. In case of error, the method returns nil followed by an error message.

Note: In UDP, the send method never blocks and the only way it can fail is if the underlying transport layer refuses to send a message to the specified address (i.e. no interface accepts the address).

socket:write(data [, i [, j]] [,utf8])
socket:write(data, utf8)

Send data over a TCP connection or connected UDP connection. A UDP connection has the same features and limitations as sendto. The optional arguments i and j work exactly as the standard string.sub Lua function to allow the selection of a substring to be sent.

Argument utf8 is a boolean value that can be set to true or false for WebSocket connections. WebSocket frames default to binary. Setting the utf8 argument to true sends a WebSocket text frame. See WebSocket frames for more information.

A blocking socket blocks if the TCP queue is full. A cosocket automatically yields if the TCP send queue is full. See cosockets flow control for more information.

Returns: Limitations: you cannot send empty (websocket) messages. The method returns false if he data length is zero.
socket:accept()

Waits for remote connections on the server socket object and returns a socket object representing that connection. This method can only be called by a coroutine in accept mode, a mode enabled by ba.socket.bind.

socket:disable()
Disable an asynchronous socket coroutine or a non blocking asynchronous coroutine. The function is typically called by the coroutine itself when your design requires that the coroutine stops receiving socket events. The TCP IP stack will then buffer the incoming messages until it's sliding window queue is full. The peer will then stop sending messages.

The function can also be called by code outside of the coroutine, but this construction requires that the coroutine has yielded in socket:read and not in socket:write. The call fails if the coroutine his currently suspended in socket:write.

The coroutine is immediately suspended when called from within the coroutine. The function will not resume before another coroutine or other code running in the context of a native thread calls method socket:enable. Any parameters provided to socket:enable is then returned as arguments when socket:disable returns.

The Lua socket proxy example shows how to use methods socket:disable and socket:enable.
socket:enable([args])
Enable a socket coroutine in state 'disabled'. The optional arguments are provided as return values to socket:disable, however this requires that the coroutine was suspended in socket:disable. The optional arguments are ignored if the coroutine was disabled by another coroutine i.e. if the coroutine is currently suspended in socket:read. The Lua socket proxy example shows how to use methods socket:disable and socket:enable.
socket:event(function [, "r|s" [, args]])

Run a Lua callback function as an asynchronous socket coroutine or a cosocket. This method is similar to function ba.socket.event, but allows the caller to bind or connect a socket before enabling socket events.

The provided function (parameter one) is immediately resumed, with the first parameter being the socket and subsequent parameters being the optional "args". The Lua callback function is resumed in the context of the thread running the Socket Event Dispatcher as soon as the Lua callback function calls the first socket function.

The provided Lua function can run as coroutine in two modes:

Parameter two must be "r" for listen sockets i.e. sockets returned by ba.socket.bind. A listen socket can only receive "accept" events.

socket:maxsize(size)

Set the maximum TLS frame size (in bytes) for a secure TCP connection. Setting the max TLS frame size for a connection is useful when communicating with small devices/microcontrollers. The maximum value and the default value is 8K.

socket:queuelen([len])
Set or get the socket queue length. The queue length specifies how many bytes that can be buffered internally when a non asynchronous caller calls socket:write on a cosocket. The default length is 16K. See cosockets flow control for more information.
socket:owner()

Returns true if the current Lua thread state is the socket coroutine that owns the socket connection. See also function ba.socket.getsock.

socket:peername()

Returns a string of the client name/IP address, the connected port number, and a boolean value set to true for IPv6 and false for IPv4.

socket:sockname()

Returns information about the local side of the TCP connection. Returns a string with the local IP address, the connected port number, and a boolean value set to true for IPv6 and false for IPv4.

socket:websocket()

Returns true if the socket is a WebSocket connection, otherwise false is returned.

socket:setoption(option [, value])

Sets an option for the TCP or UDP object. The first argument 'option' is a string with the option name, and value depends on the option being set:

TCP:

UDP:

The function returns true on success and nil,error if the operation failed.

Error codes for 'keepalive':

socket:state()

Returns the socket state:

notconCreated but not connected
execExecuting
acceptAsynchronous accept
connectAsynchronous connect
upgradeAsynchronous upgrade to TLS
disableddisabled
readWaiting in asynchronous read
writeWaiting in asynchronous write
terminatedTerminated/closed
socket:close()

Close the socket connection.

socket:upgrade(shark)

Upgrade a standard socket to a secure socket. The method is typically used by protocols that connect in non-secure mode and then later upgrade to secure communication. STARTTLS is an example of a protocol that upgrades to SSL/TLS.

  local s=ba.socket.connect(myaddress, myport)
  -- Send handshake data
  s:upgrade(ba.sharkclient())
socket:certificate()

Returns the peer's certificate chain as a table if the connection is secure and the peer sent a certificate. A second return value is set to true if the certificate's chain of trust is validated by the certificate store. However, a 'true' value does not provide complete verification since the domain name and certificate expiration time are not checked. For full validation, use sock:trusted().

socket:cipher()

Returns the cipher suite and SSL protocol version being used if the connection is secure.

Cipher suites: Protocol versions:
socket:trusted([host-name])

Returns the peer's "trust" status.

If the argument host-name is not provided, the certificate's common name is compared with the address provided when the connect function was called. Server connections must provide the host-name argument.

See ba.socket.connect() for example code.

Pipe API

The pipe API is supported on POSIX operating systems including Linux and QNX.

ba.pipe.mkfifo(pathname [, mode])

This function maps directly to the POSIX C function mkfifo().

ba.pipe.open(pathname [,cosocket [, args...]])

The function creates and returns a named pipe handle as a socket object. The socket object runs in cosocket mode and inherits the cosocket flow control mechanism. The pipe is opened in write only mode if no cosocket function is provided and in read/write mode if a cosocket (argument 2) is provided. Note that the function fails if opened in write only mode and if no other process is reading on the pipe.

Lua Thread Library (Thread Pool)

Let's revisit the diagram from the introduction.

The Lua Thread Library (the thread pool) is seen in the bottom right corner in the above diagram. The thread pool is typically used when running Lua code that is not part of a typical web-server request/response. One can for example design code to run at regular intervals by using a timer and trigger a function to run for a prolonged time in the thread pool.

ba.thread.run(function)

Delegate the execution of function to one of the threads in the Lua thread pool. The execution is queued if no thread(s) are available -- i.e. if the thread(s) are busy executing other functions. The function remains in a FIFO queue until a thread becomes ready.

There are no time limits on the execution time for the provided function. The thread executing the function becomes ready when the function returns (terminates).

See the Lua socket web server example for more information.

ba.thread.configure([maxthreads])

Set or get the maximum number of allowed threads in the thread pool. The default value is one. Threads never terminate, thus setting a higher value followed by a lower value does not reduce the thread pool size. Threads are not created unless there are no available threads when function ba.thread.run() is called.

ba.thread.create()

Dynamically create a new thread. The function returns a thread object. The thread is activated by calling the run method on the returned object.

Example:
local function myThreadFunc()
   for i=1,10 do
      print("Hello")
      ba.sleep(1000)
   end
end

local thread=ba.thread.create()
thread:run(myThreadFunc)

SharkSSL

(Secure SSL/TLS communication management)

SharkSSL is an extremely compact SSL/TLS stack, supporting TLSv1.0 to TLSv1.2. SharkSSL provides security for network communications, such as for securing HTTP and SMTP communication. The SharkSSL stack supports both client-side and server-side connections, enabling the client to confirm the server's identity and vice-versa.

When using secure communication such as secure sockets or the HTTP library in secure mode, a SharkSSL object is required. The various API's such as the HTTP client library and the socket library take an option table as argument. This table must have the attribute "shark" set to an instance of SharkSSL when using secure communication.

ba.create.sharkssl([certstore [,op]])

Create a SharkSSL object. Parameter certstore (the CA list) is an object created with ba.create.certstore(); parameter op is an optional configuration table. As an alternative to using a cerstore object, you may also use the more compact SharkSslCAList object format. The documentation for function ba.sharkclient() includes an example that shows how to create a SharkSSL client object by using a binary SharkSslCAList object.

Note: for client connections, you may consider using ba.sharkclient(), which returns a ready to use SharkSSL object initialized with the certificates in the the file .certificate/cacert.shark.

The returned object has the following method:

sharkssl:addcert(sharkcert)
sharkcert, the certificate and key, is an object created with ba.create.sharkcert(). You can add multiple certificates such as RSA certificates and ECC certificates.
Typical use cases:
  1. Create a client SharkSSL object that verifies the server using the supplied CA
    clientObj=ba.create.sharkssl(certstore)
  2. Create a client SharkSSL object that accepts any server, including self signed certificates.
    clientObj=ba.create.sharkssl()
  3. Create a standard server object that does not require client certificates.
    serverObj=ba.create.sharkssl(nil, {server=true}); serverObj:addcert(sharkcert)

The above 3 use cases show the typical web client and server configurations.


The option (op) table:
  • server=bool -- The SSL/TLS protocol is a client server protocol. You must select the correct protocol for client and server connections. The default is to create a client SSL object. Set server=true if the ssl object is used as an option when calling ba.create.servcon.
  • insize=number -- The internal SharkSSL start "read" buffer size. The size automatically grows if needed. The default value is 8192 bytes.
  • outsize=number -- The internal SharkSSL "write" buffer size. The default value is 8192 bytes.
  • cachesize=number -- The SSL session resumption cache size. The default 'cachesize' value for a SSL client object is 8. The default 'cachesize' value for a SSL server object is set to the web server's maximum number of connections. The server's maximum number of connections is set by the C startup code by calling HttpServerConfig::setNoOfHttpConnections().
ba.create.certstore()

Create a Certificate Authority Store. A Certificate Authority or CA for short is an entity that issues digital certificates for use by other parties. In layman's terminology, a CA is like a certified (government) passport issuer. A CA is typically used by a client SharkSSL object, but can also be used by a server SharkSSL object if the server requires client certificate validation.

The object returned by ba.create.certstore() have the following method associated with them:

addcert(io,name)
addcert(data)

This function adds a certificate in PEM or p7b format to the CA store. A convenient way to get CA's is to export the certificates from a browser in PEM or p7b format. The p7b format is a container format that can contain many CA's.

The method can add certificates in two modes:

  • Mode 1: Provide a Barracuda I/O interface (io) and the path+name (name) to the location of the CA.
  • Mode 2: Load the file data manually and insert the data.

The following example downloads the "CA Root Certificates bundle" maintained by CURL, creates a CA store, and installs the downloaded bundle in the CA store. Note that the download must be over a secure connection, but we are unable to verify the download since we do not have a CA store with CA certificates when downloading. We set the "shark" attribute to a SharkSSL object with an empty CA store when downloading.

local store=ba.create.certstore()
local http=require"httpc".create()
http:request{
   -- Create a temporary shark object and use the empty store.
   shark=ba.create.sharkssl(store),
   method="GET",
   url="https://curl.haxx.se/ca/cacert.pem"
}
local data,err=http:read"*a"
if data then
   local certs = store:addcert(data)
   print("Number of CA certs installed:",certs)
   -- Use 'store'
end

See also ba.sharkclient().

ba.create.sharkcert(io, certfile, keyfile[, password])
ba.create.sharkcert(certdata, keydata[, password])

A SharkSSL certificate is a combination of the certificate (the public part) and the certificate key (the private part).

The function can create a SharkSSL certificate in two modes:

The password is an optional argument that must be provided if the key is encrypted.

ba.create.key([{op}])

Create an ECC or RSA key. An ECC key is created if no options are provided. Note that creating RSA keys is extremely time consuming.

Parameters: The function returns the key in PEM format.
ba.create.csr(privkey, dn [, san], certtype, keyusage [, hashid ])

Generate a Certificate Signing Request (CSR).

Parameters:

The function returns the CSR in PEM format.

Example:
local privkey = ba.create.key()
local certtype = {"SSL_CLIENT", "SSL_SERVER"}
local keyusage = {
   "DIGITAL_SIGNATURE",
   "NON_REPUDIATION",
   "KEY_ENCIPHERMENT",
   "DATA_ENCIPHERMENT",
   "KEY_AGREEMENT",
   "KEY_CERT_SIGN",
   "CRL_SIGN"
}
local d = "realtimelogic.com"
local csr=ba.create.csr(privkey, {commonname=d} , d..";www."..d, certtype, keyusage)
ba.create.certificate(csr [, cert], privkey, validfrom, validto, serial [,hashid])

Parameters:

The function returns the certificate in PEM format.

Example:
local csr = ba.create.csr(.......) -- See example above
local validFrom=os.date"*t"
local validTo=os.date"*t"
validTo.year = validTo.year + 10
local cert = ba.create.certificate(
   csr, caCert, caKey, validFrom, validTo, 0x000001)
ba.parsecert(asn1)

Parses raw ASN.1 certificate data and returns a table.

Example:
local cert="the X.509 cert data"
local t = ba.parsecert(
            ba.b64decode(cert:match".-BEGIN.-\n%s*(.-)\n%s*%-%-"))
if t then print("Cert info", ba.json.encode(t)) end
ba.sharkclient()

Trust is the single most important aspect when it comes to establishing an encrypted TLS connection. A TLS client such as HTTPS, SMTP, secure MQTT, etc, cannot establish trusted communication with the server unless the client trusts the server's certificate. Trust can only be established by keeping a copy of the signer of the server's certificate. See the tutorial Introduction to Public Key Infrastructure for details.

This function returns a SharkSSL client object initialized with the certificates in the the file "vmio" -> .certificate/cacert.shark.

The following example shows the internal ba.sharkclient() implementation:

-- This code is only executed one time,
-- when the function is initially called.
-- A cached copy is otherwise returned.
local f=ba.openio('vm'):open'.certificate/cacert.shark'
local c=f:read'*a'
f:close()
return ba.create.sharkssl(c)

The function throws an exception if '.certificate/cacert.shark' is not found in the VM IO or if the file is corrupt/invalid. The Barracuda App Server does not automatically include cacert.shark and you may have to assemble the cacert.shark file. The Mako Server's resource file mako.zip includes a ready to use cacert.shark assembled from Curl's CA Certs. The Mako server's cacert.shark is huge and not suitable for memory constrained devices. The following example shows how to assemble a cacert.shark trusting only certificates signed by Let's Encrypt:

curl https://letsencrypt.org/certs/isrgrootx1.pem > cacert.pem
curl https://letsencrypt.org/certs/isrg-root-x2.pem >> cacert.pem
SharkSSLParseCAList -b cacert.shark cacert.pem

The above command line example shows how to create a compact SharkSslCAList object (cacert.shark), which can be created by using the SharkSSLParseCAList command line tool. However, a SharkSSL client object can also be created by using a SharkSSL Certificate Authority Store (ba.create.certstore). The following example shows how to replace the original ba.sharkclient() with your own version.

do -- New scope
   local sharkClient -- closure
   -- replace ba.sharkclient
   function ba.sharkclient()
      if not sharkClient then
         -- Create when function is initially called
         local vmio = ba.openio("vm")
         local sn=".certificate/cacert.pem"
         if not vmio:stat(sn) then
            error("Cannot find "..sn)
         end
         local store = ba.create.certstore()
         store:addcert(vmio,sn)
         sharkClient=ba.create.sharkssl(store)
      end
      return sharkClient
   end
end

Barracuda Web Server Listen Object

ba.create.servcon(port|con [,op])

Create a Barracuda Web Server connection listen object and install the object in the Socket Event Dispatcher. The web-server listen object(s) are typically installed by the C startup code, but can optionally be installed by the server startup script (.config). The benefit of having Lua code manage the objects is that it is easier to configure the server listen objects.

See the Lua web-server startup script examples/mako/lsp/.openports in the Barracuda Embedded Web Server SDK for an example on how to dynamically detect free server port numbers and configure multiple secure and non-secure server connection objects.

For security reasons, objects created with this function are self referencing, which means they will not be collected by the garbage collector if you do not keep a reference to these objects. The Barracuda Socket Event Dispatcher cannot operate without at least one connection. If you close all listen objects, the Socket Event Dispatcher will eventually run out of active connections and malfunction. It is, for this reason, vital that you keep at least one listen object active at all times.

Parameters:
port | con - Port number or an existing server listening object.
  • port: integer -- the port number should be 80 for HTTP connections and 443 for HTTPS connections.
  • con: object -- This mode is designed specifically for setting new SSL certificates in a running server without having to stop the server. The option (op) table must include the "shark" attribute and the "con" argument must be an existing secure connection object. The new connection object inherits all settings from the "con" object, except for the "shark" attribute. The "con" object is unreferenced and allowed to garbage collect. Existing connections on the "con" object are left connected until they either close or the garbage collector collects the "con" object.
op - The option table:
  • intf: string -- Bind to interface-name/IP-address. The default is to bind to all interfaces.
  • ipv6: bool -- Create an IPv6 server object. Note, the server must have been compiled with IPv6 support.
  • shark: SharkSSL object -- Accept SSL connections.

You can open any number of server connection objects as long as the combination of all of the following is unique: port number, interface, and protocol version (IPv4/IPv6). This means that you can have many server connection objects listening on port 80 if you have more than one interface and/or protocol version.

Objects returned by ba.create.servcon() have the following methods associated with them:

servcon:setport(port [,op])

Change the port number and configuration options in an active server connection object. The parameters are identical to the parameters for function ba.create.servcon(), except for parameter shark, which is ignored if provided.

The function is internally creating a new connection object. The original connection is closed if the new object is created successfully. This function differs from closing an active connection and then creating a new object by leaving any active "accepted" socket connections from the original server connection running.

servcon:close()

Close the active server listening object, remove the listening object from the Socket Event Dispatcher, and remove the self reference on the object.

The following example shows how to create a secure (SSL) listen object. You may download the complete example and run the example on your server.

-- Servers do not use a 'cert store' unless mutual authentication is required.
local shark=ba.create.sharkssl(nil, {server=true})
-- x509certData and x509KeyData are Lua strings containing cert and key.
local x509cert = ba.create.sharkcert(x509certData,x509KeyData)
shark:addcert(x509cert) -- Certificate required for servers.
ba.create.servcon(port, {shark=shark})

forkpty

The forkpty library provides a combined fork, exec, and child process pseudo-terminal. The code is available for Linux, Mac, and QNX. Windows users may use the simpler io.popen library. For simpler tasks, use ba.exec.

The code can be used for executing and managing Linux executables such as "ls", "kill", etc. The forkpty library provides a advanced child process management.

Download: the Web Shell, a fully working web-based terminal (alternative to using SSH), which is using the forkpty library for the shell process management and communication. The CGI plugin is also using the forkpty library for process management.

pty,err=ba.forkpty([X,] prog [, args...])

Arguments:

Starts program prog in a separate process and returns a process object that is used for child process management. The pty process object support full duplex read and write operations.

On success, the function returns a pty child process communication object with 4 methods:

  1. pty:read: Read child's stdout.
  2. pty:write: Write to child's stdin.
  3. pty:pause: Pause or resume child process.
  4. pty:winsize: Set the child's terminal screen size.
  5. pty:close: Gracefull kill.
  6. pty:terminate: Immediate kill.

The external process can be managed in two modes, polling, or asynchronous read. Polling the pty is typically used when designing web-clients that use AJAX for polling the child process for new data. Asynchronous read is typically used together with SMQ, where a web-client is using a persistent asynchronous communication channel with the server. The optional "function" must be supplied for asynchronous read operation. The default mode is designed for polling mode. The examples below assume that you do not provide a function. Asynchronous mode is explained later.

PTY Methods

pty:read([bool|number])

Read stdout,stderr from the child process.

Note: when operating in asynchronous mode, pty:read() always blocks and the arguments are ignored.

Return values:

Example:
local data,err = pty:read()
if data then
 -- manage data
elseif err then
  if err = "terminated" then
    -- Terminated
  else
    -- pty error
  end
end
ok,err = pty:write(string)

Send data to the child process's stdin.

ok is nil on error. See pty:read for how to manage the error code.

pty:pause(true|false)

Pause or resume a paused child process.

ok,err=pty:winsize(lines, cols)

Set the child's terminal screen size.

local status [, WIFEXITED, WIFSIGNALED, WTERMSIG] = pty:close([true])

Return the exit code for the <defunc> child process or gracefully kill the active child process.

The function returns immediately unless the optional parameter is set to true. The function waits for the child to terminate if the optional parameter is set to true.

status is the child process exit code.

Status codes:

if status is nil, the second parameter is the error message. The child process is immediately kill if any errors are detected.

Example:
local status, WIFEXITED, WIFSIGNALED, WTERMSIG = pty:close()
if status == nil then
   print("Failed, msg:", WIFEXITED)
elseif status < 0 then
   print("Running")
elseif status == 0 then
   print("Exited");
else
   print("Exited with error code:", status , WIFEXITED, WIFSIGNALED, WTERMSIG);
end

Note, pty:close() is designed to be called repeatedly until the child terminates i.e. until it returns a value that is not less than zero.

local ok, status [, WIFEXITED, WIFSIGNALED, WTERMSIG] = pty:terminate()

Close the connection to the <defunc> child process or immediately kill the active child process.

Asynchronous PTY Mode

The PTY object is self-referencing in asynchonous mode. Normally, a reference must be kept to the pty objected returned by ba.forkpty to prevent garbage collection (GC). When in asynchronous mode, a reference is automatically created by ba.forkpty to prevent GC. This reference is valid as long as the coroutine executes.

The following example shows how to use asynchronous mode:

-- The asynchronous receive function keeps reading until the process terminates
function recData(pty)
   while true do
      local d,e = pty:read() -- Read data. Arguments to pty:read are ignored.
      if not d then -- Child process terminated
         break
      end
      trace(d,e)
   end
   trace("\nexit coroutine", e and e or "OK")
   -- coroutine automatically cleans up on exit, but we are allowed to call:
   -- local ok, status [, WIFEXITED, WIFSIGNALED, WTERMSIG] = pty:terminate()
end

local pty,err -- Local variables i.e. we do not need a reference to prevent GC
pty,err = ba.forkpty(recData, "/bin/ls", "-l") -- Execute ls -l
trace(pty,err)

In asynchronous mode, a function must be provided as the first argument to ba.forkpty. This function is executed as a Lua coroutine and is automatically yielded by read when no data is available. The function is resumed when there is data available or if the child process terminates.

All pty:xxx functions operate as normal, except for read when called from within the coroutine.

LuaIo

The LuaIo module implements Lua mapping between the Barracuda I/O interface and Lua. The LuaIo API makes it possible to implement a Barracuda I/O interface using Lua.

The purpose with the LuaIo is to provide filtering on existing I/O's or implement new I/O types in Lua. As an example, a SQL mapped LuaIo could provide WebDAV access to a SQL database.

Error handling:

The I/O functions return nil or false on error. Functions returning a table return nil on error and functions returning status information return false on error. In addition to returning nil/false, the functions can optionally return one of the following error codes (string):

-- Open resource in read or write mode. mode ="r" or "w"
local function open(name, mode)
   -- open resource, return nil on error.
   -- Resource management functions
   local function read(maxsize)
      -- Return data
   end
   local function write(data)
      -- Return true or false
   end
   local function seek(offset)
      -- Return true or false
   end
   local function flush()
      -- Return true or false
   end
   local function close()
      -- Return true or false
   end
   local res={
      read=read,
      write=write,
      seek=seek,
      flush=flush,
      close=close
   }
   return res -- Table with functions: read,write,seek,flush,close
end

-- Directory iterator
local function files(name)
   -- Find resource, return nil if not found.
   local function read()
      -- Iterate to first/next resource, return true if more files or false
      -- if no more files.
   end
   local function name()
      -- return resource name
   end
   local function stat()
      -- return table with mtime,size, and isdir (true/false)
   end
   return {read=read,name=name,stat=stat} -- Return table with functions
end

-- Return resource information
local function stat(name)
   -- return table with mtime,size, and isdir (true/false) if found or
   -- nil if not found
end

-- Create directory
local function mkdir(name)
   -- Return true on success and false on error
end

-- Remove directory
local function rmdir(name)
   -- Return true on success and false on error
end

-- Remove file
local function remove(name)
   -- Return true on success and false on error
end

-- Table with the Lua I/O callback functions
local iofuncs {
   open=open,
   files=files,
   stat=stat,
   mkdir=mkdir,
   rmdir=rmdir,
   remove=remove
}

-- Create a Lua I/O instance
local io=ba.create.luaio(iofuncs)

-- Install the Lua I/O in any Barracuda resource that takes an I/O
-- interface as argument.

TraceLogger

TraceLogger

The TraceLogger lets you intercept the output from the server's trace buffer, control what data the server's trace buffer should log, and display the traced data in real-time in a browser window. The TraceLogger's web interface URI is by default set to /rtl/tracelogger/ and the JavaScript code in index.html file opens a persistent real-time communication link with "../tracelogger.service/". Note: the output from function trace and _G.print is also sent to the trace buffer. The TraceLogger is an optional component that must be installed by the C startup code. As an example, the Mako Server includes this optional component.

ba.create.tracelogger()

Create a TraceLogger directory object. The function returns a TraceLogger directory object specifically designed to act a web-service for the JavaScript code in the TraceLogger client's index.html file.

Example code: study the Mako Server's .config script.

Note: the TraceLogger directory object is automatically referenced and will not garbage collect unless method dir:close() is called. The TraceLogger interfaces to the global trace buffer and you can for this reason only create one TraceLogger instance.

The created directory object has the following additional directory method:

dir:configure([op])

Set and/or get the server's trace buffer settings.

The option (op) table:
  • request=bool (default false) -- Trace the HTTP method type and URL for each request.
  • requestheaders=bool (default false) -- Trace the HTTP headers for each request.
  • responseheaders=bool (default false) -- Trace all HTTP response headers.
  • responsebody=bool (default false) -- Trace all response data created by dynamic pages such as LSP and CSP.
  • http11state=bool (default false) -- Trace the server's internal HTTP 1.1 state machine.
  • priority=number (default 5) -- Set the trace priority.
dir:close()

Shuts down all active connections, removes the directory from the virtual file system (if installed), and releases the reference so the garbage collector can remove the directory object.

Reverse Proxy

Ref Wikipidia:

A reverse proxy is a type of proxy server that retrieves resources on behalf of a client from one or more servers. These resources are then returned to the client as though they originated from the server itself.

The purpose with the reverse proxy is to make it possible to integrate existing web solutions with the Barracuda Application Server and/or provide a means to implement cross site scripting.

The reverse proxy behaves as a Barracuda Server directory object. One or several instances of the reverse proxy can be inserted into the Barracuda virtual file system. The reverse proxy can also implement authentication and authorization just like any other Barracuda directory object. One can for this reason provide security to less secure backend servers. The reverse proxy also offers SSL termination.

ba.create.redirector(name,domain,port[,baseuri][,priority])
Create a standard reverse proxy.
Parameters:
ba.create.redirector(name[,priority])
Create a cross site scripting redirector.
Parameters:

Creating a standard reverse proxy:

The most common operation is to create a standard reverse proxy. The following example creates a reverse proxy for a backend server with IP address 127.0.0.1

  rproxy=ba.create.redirector("backend","127.0.0.1",80)
  myRootDir:insert(rproxy)

The backend server 127.0.0.1 can now be access as: http://localserver/backend/ Use the baseuri if you only want to access a subset of the backend server:

  rproxy=ba.create.redirector("backend","127.0.0.1",80,"subdir")

The backend server URL http://127.0.0.1/subdir/ can now be accessed as: http://localserver/backend/

The basic proxy does not provide a rewrite module, thus absolute encoded URLs in web pages retrieved from a backend server such as images will not show up in the browser unless the reverse proxy is installed as a root directory.

  rproxy=ba.create.redirector(nil,"127.0.0.1",80,-1) -- Priority=-1
  rproxy:insert() -- Insert as root directory

The above is the most common case for inserting an existing web application into a barracuda server. The reverse proxy is inserted as a root directory with a priority that is less than the root directory for the existing application. This will make sure the Barracuda server first searches for the requested resource locally and then delegates the request to the reverse proxy only if the requested resource was not found in the Barracuda Server.

Cross site scripting redirector:

  rproxy=ba.create.redirector("gateway")
  myRootDir:insert(rproxy)

Any server and web page can now be access as: http://localserver/gateway/domain-name/path

e.g. http://localserver/gateway/www.cnn.com

The Lua Debug Module

The Lua debug module dbgmon implements the Debug Adapter Protocol and can be used by any debugger implementing this protocol. Module dbgmon is implemented in C code and interfaces to the Lua debug API.

See the how to use the debugger example on GitHub for more information on how to use this module.

Load the module as follows:

local dbgmon = require"dbgmon"

The returned value dbgmon is a table with the following functions:

dbgmon.connect(op)

The function establishes a persistent TCP connection with a debugger. The function can be configured to operate as a TCP client or TCP server. The function operates as a TCP client and attempts to connect to "localhost:4711" if called without arguments. The function does not return until a debugger TCP connection is established or a TCP error occurs. The argument 'op' is an optional configuration table that takes the following values:

dbgmon.close()

Close any active TCP debugger connection and resume normal operation.

dbgmon.pause()

Pause the debug session and resume normal operation without closing the TCP debugger connection.

dbgmon.resume()

Resume a paused debug session.