vortex.tls — LuaVortex TLS module: TLS profile support

This modules includes all functions required secure BEEP sessions using TLS.

Here is an example how a client can activate TLS on an established connection:

-- now enable tls support on the connection
if not vortex.tls.init (ctx) then
    error ("Expected to find proper authentication initialization, but found an error")
    return false
end

-- enable TLS on the connection
conn, status, status_msg = vortex.tls.start_tls (conn)

-- check connection after tls activation
if not conn.is_ok () then
    error ("Expected to find proper connection status after TLS activation..")
    return false
end

-- check status
if status ~= 2 then
    error ("Expected to find status code : " .. tostring (vortex.status_OK) .. ", but found: " .. tostring (status))
end

Module API

vortex.tls.init(ctx)

Allows to init TLS module on the provided vortex.ctx reference. This is required before any TLS operation is done.

Parameters:ctx (vortex.ctx) – vortex context where TLS module will be initialized
Return type:true it initialization was completed, otherwise false is returned.
vortex.tls.start_tls(conn[, serverName][, tls_notify][, tls_notify_data])

Allows to start the TLS process on the given connection.

The function creates a new connection object reusing the transport of the received connection. This means you have to update connection reference to the returned value.

In the case no tls_notify handler is provided, the function will return a tuple with 3 elements (connection, status, status_msg): where connection is the connection with TLS activated, status is a integer status code that must be checked and status_msg is a textual status.

In the case tls_notify handler is provided the function returns nil and the resulting tuple is returned on tls_notify.

Providing a tls_notify handler makes this function to not block the caller during the TLS process. Calling without tls_notify will cause the caller to be blocking until the process finish (no matter its result).

Parameters:
  • conn (vortex.connection) – The connection where the TLS process will take place.
  • serverName (string or nil.) – the server name to configure on the TLS channel. This is used to signal server side to use a particular certificate according to the serverName.
  • tls_notify (TLS status notification handler) – User defined handler that will be used to notify TLS termination status.
  • tls_notify_data (object) – User defined data that will notified along with corresponding data at tls notify handler.
vortex.tls.accept_tls(ctx[, accept_handler][, accept_handler_data][, cert_handler][, cert_handler_data][, key_handler][, key_handler_data])

Allows to enable accepting incoming requests to activate TLS profile.

Parameters:
  • ctx (vortex.ctx) – The context to be configured to accept incoming TLS profile.
  • accept_handler (TLS accept request handler) – The handler to be called to accept or deny a particular incoming TLS request.
  • accept_handler_data (object) – User defined data that will notified along with corresponding data at accept handler.
  • cert_handler (TLS certificate location handler) – The handler to be called to get the path to the certificate to be used to activate the TLS process.
  • cert_handler_data (object) – User defined data that will notified along with corresponding data at cert handler.
  • key_handler (TLS key location handler) – The handler to be called to get the path to the private key to be used to activate the TLS process.
  • key_handler_data (object) – User defined data that will notified along with corresponding data at key handler.
vortex.tls.is_enabled(conn)

Allows to check if the provided connection has successfully activated TLS profile

Parameters:conn (vortex.connection) – the connection to check for TLS activation.