vortex.tls — PyVortex 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):
    error ("Expected to find proper authentication initialization, but found an error")
    return False

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

# check connection after tls activation
if not conn.is_ok ():
    error ("Expected to find proper connection status after TLS activation..")
    return False

# check status
if status != vortex.status_OK:
    error ("Expected to find status code : " + str (vortex.status_OK) + ", but found: " + str (status))

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 None 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) – 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. Return type:True in the case TLS profile was activated. Otherwise False is returned. Check verify_cert() in the case you want to also check certificate status.

vortex.tls.verify_cert(conn)

Allows to check peer certificate verify status.

Parameters:conn (vortex.Connection) – the connection to check for TLS activation. Return type:True in the case certificate verification status is Ok (valid). Otherwise False is returned.