[tlspool] / lib / python / py-tlspool.i

/* This is the specifics module for SWIG mapping to Python.
 * It includes generic definitions from ../swig-tlspool.i
 *
 * This separation enables us to override function names, for instance
 * to raw/internal names, and then to add language-specific wrappers.
 *
 * From: Rick van Rein <rick@openfortress.nl>
 */

%module tlspool


/* Renames, prefixing "_" when wrapped below for better parameter handling
 */
%rename(_pid) tlspool_pid;
%rename(_open_poolhandle) tlspool_open_poolhandle;
%rename(_ping) tlspool_ping;
%rename(_starttls) tlspool_starttls;
%rename(_control_detach) tlspool_control_detach;
%rename(_control_reattach) tlspool_control_reattach;
%rename(_prng) tlspool_prng;


// type maps to translate between SWIG's abstract data types and Python types

%typemap(in) ctlkey_t {
        ssize_t inlen = 0;
        if ((PyString_AsStringAndSize ($input, (char **) &($1), &inlen) == -1) || (inlen != TLSPOOL_CTLKEYLEN)) {
                PyErr_SetString (PyExc_ValueError, "Control keys are binary strings of length 16");
                return NULL;
        }
}

%typemap(out) ctlkey_t {
        if ($result == NULL) {
                $1 = Py_None;
        } else {
                $1 = PyString_FromStringAndSize ($result, TLSPOOL_CTLKEYLEN);
        }
}


// apply the settings above as modifiers to the generic TLS Pool wrapping

%include "../swig-tlspool.i"


// helper function to raise OSError with the parameter set to C-reachable errno

%inline %{

PyObject *raise_errno (void) {
        return PyErr_SetFromErrno (PyExc_OSError);
}

%}



// full-blown Python code to include

%pythoncode %{


import os
import socket

if not 'IPPROTO_SCTP' in dir (socket):
        socket.IPPROTO_SCTP = 132


def pid (pidfile=None):
        """This function returns the process identity of the TLS Pool.
           When no pidfile is provided, the default path as configured in the
           TLS Pool libary will be used.  An Exception is thrown when there is
           no TLS Pool.
        """
        process_id = _pid (pidfile)
        if process_id < 0:
                _tlspool.raise_errno ()
        else:
                return process_id

def open_poolhandle (path=None):
        """This function returns the OS-specific socket handle value for the
           TLS Pool.  It is already connected, and shared with the internal
           management of this module, so it must not be closed by the caller.
           When no path is provided, the default path is used instead.
           This function blocks until a connection to the TLS Pool succeeds.
           The path is only used in the first call, and only when no prior
           contact to the TLS Pool has been made; if that has happened, then
           this function returns the previously found socket handle.
        """
        fd = _open_poolhandle (path)
        if fd < 0:
                _tlspool.raise_errno ()
        else:
                return fd

def ping (YYYYMMDD_producer=_tlspool.TLSPOOL_IDENTITY_V2,
                        facilities=_tlspool.PIOF_FACILITY_ALL_CURRENT):
        """This function takes in a string with a date in YYYYMMDD format, followed
           by a user@domain producer identifier.  It takes in an integer value
           that is the logical or of PIOF_FACILITY_xxx values.  This is sent to
           the TLS Pool through tlspool_ping() and the response is returned as a
           similar tuple (YYYYMMDD_producer, facilities) as returned by the
           TLS Pool.  This function blocks until a connection to the TLS Pool has
           been found.  It is a good first command to send to the TLS Pool.
        """
        pp = ping_data ()
        pp.YYYYMMDD_producer = YYYYMMDD_producer
        pp.facilities = facilities
        if _ping (pp) < 0:
                _tlspool.raise_errno ()
        else:
                return (pp.YYYYMMDD_producer, pp.facilities)

def make_tlsdata (localid='', remoteid='',
                flags=0, local_flags=0,
                ipproto=socket.IPPROTO_TCP, streamid=0, service='',
                timeout=0, ctlkey=None):
        """Make a new tlsdata structure, based the fields that may be supplied
           as flags, or otherwise as defaults.  Note that the field "local" is
           renamed to "local_flags" for reasons of clarity.  This helper function
           returns a tlsdata structure or raises an exception.
        """
        tlsdata = starttls_data ()
        if ctlkey is not None:
                tlsdata.ctlkey = ctlkey
        tlsdata.service = service
        tlsdata.localid = localid
        tlsdata.remoteid = remoteid
        tlsdata.flags = flags
        tlsdata.local = local_flags
        tlsdata.ipproto = ipproto
        tlsdata.streamid = streamid
        tlsdata.timeout = timeout
        return tlsdata

class Connection:
        """The tlspool.Connection class wraps around a connection to be protected
           by the TLS Pool.  It uses the global socket for attaching to the
           TLS Pool, but the individual instances of this class do represent
           individual connections managed by the TLS Pool.
           New instances can already collect a large number of parameters
           that end up in the tlsdata structure of tlspool_starttls(),
           but these values may also be created through getters/setters.
           Some values have reasonable defaults, but some must have been
           set before invoking the starttls() method on the instance.
           The tlsdata fields all have defaults, as specified under
           tlspool.make_tlsdata().
        """

        def __init__ (self, cryptsocket, plainsocket=None, **tlsdata):
                self.cryptsk = cryptsocket
                self.cryptfd = cryptsocket.fileno ()
                self.plainsk = plainsocket
                self.plainfd = plainsocket.fileno () if plainsocket else -1
                self.tlsdata = make_tlsdata (**tlsdata)

        def close (self):
                assert (self.plainsk is not None)
                assert (self.plainfd >= 0)
                self.plainsk.close ()
                self.plainsk = None
                self.plainfd = -1

        def tlsdata_get (self, tlsvar):
                return self.tlsdata [tlsvar]

        def tlsdata_set (self, tlsvar, value):
                self.tlsdata [tlsvar] = value

        def starttls (self):
                """Initiate a TLS connection with the current settings, as
                   provided during instantiation or through getter/setter
                   access afterwards.  The variables that are required at
                   this point are service and, already obliged when making
                   a new instance, cryptfd.
                """
                assert (self.cryptsk is not None)
                assert (self.cryptfd >= 0)
                assert (self.tlsdata.service != '')
                try:
                        af = self.cryptsk.family
                except:
                        af = socket.AF_INET
                try:
                        if   self.cryptsk.proto in [socket.IPPROTO_UDP]:
                                socktp = socket.SOCK_DGRAM
                        elif self.cryptsk.proto in [socket.IPPROTO_SCTP]:
                                socktp = socket.SOCK_SEQPACKET
                        else:
                                socktp = socket.SOCK_STREAM
                except:
                        socktp = socket.SOCK_STREAM
                plainsockptr = socket_data ()
                plainsockptr.unix_socket = self.plainfd
                # Provide None for the callback function, SWIG won't support it
                # We might at some point desire a library of C routine options?
                rv = _starttls (self.cryptfd, self.tlsdata, plainsockptr, None)
                self.plainfd = -1
                self.cryptfd = -1
                self.cryptsk = None
                if rv < 0:
                        _tlspool.raise_errno ()
                if self.plainsk is None:
                        self.plainfd = plainsockptr.unix_socket
                        self.plainsk = socket.fromfd (self.plainfd, af, socktp)
                return self.plainsk

        def prng (self, length, label, ctxvalue=None):
                """Produce length bytes of randomness from the master key, after
                   mixing it with the label and optional context value in ctxvalue.
                   The procedure has been described in RFC 5705.
                   #TODO# Find a way to return the random bytes, and use the length
                """
                buf = prng_data ()
                rv = _prng (label, ctxvalue, length, buf, self.tlsdata.ctlkey)
                if rv < 0:
                        _tlspool.raise_errno ()
                else:
                        return buf

        def control_detach (self):
                """Detach control of this connection.  Although the connection
                   itself will still be available, control over it is diminished
                   and its continuation is no longer dependent on the current
                   connection.  You may need to pass tlsdata.ctlkey to another
                   process, or use control_reattach(), before this is reversed
                   in this process or another.
                """
                _control_detach (self.tlsdata.ctlkey)

        def control_reattach (self, ctlkey=None):
                """Reattach control of this connection.  The connection may have
                   called control_detach() in this process or another.  To help
                   with the latter case, its tlsdata.ctlkey must have been moved
                   into this instance.
                """
                _control_reattach (self.tlsdata.ctlkey)

class SecurityMixIn:
        """The SecurityMixIn class can be added as a subclass before a
           (subclass of) SocketServer.BaseServer and it adds the facilities
           of starttls(), startgss() and startssh() which add security through
           one of the mechanisms.  In addition, have_xxx() can be used to
           query in advance if startxxx() should be doable with the present
           combination of TLS Pool and client code.
           
           Set a tlsdata field in the subclass, using the tlspool.make_tlsdata()
           helper function, to bootstrap the same kind of behaviour on all
           clients for which this class will be instantiated.  Such a tlsdata
           class variable will automatically be cloned into instances.
           Example code:
           
                from tlspool import SecurityMixIn
                from SocketServer import BaseHandler
                
                class MyHandler (SecurityMixIn, BaseHandler):
                        
                        tlsdata = make_tlsdata (service=...)
                        
                        def handle (self):
                                ...
                                self.starttls ()
                        
                        def handle_secure (self):
                                ...
           
           Alternatively, you can setup the tlsdata structure, or any part of it,
           at a later time, through the tlsdata variable that will then be
           instantiated during object initialisation.  Any such changes to fields
           must be completed before invoking starttls() on this object.
        """

        _pingdata = None
        tlsdata = None

        def __init__ (self):
                if self.tlsdata is None:
                        self.tlsdata = make_tlsdata ()

        def have_tls (self):
                """Check whether STARTTLS is supported on the current TLS Pool"""
                if self._pingdata is None:
                        self._pingdata = ping ()
                return (self._pingdata [1] & PIOF_FACILITY_STARTTLS) != 0

        def have_ssh (self):
                """Check whether STARTSSH is supported on the current TLS Pool"""
                if self._pingdata is None:
                        self._pingdata = ping ()
                return (self._pingdata [1] & PIOF_FACILITY_STARTSSH) != 0

        def have_gss (self):
                """Check whether STARTGSS is supported on the current TLS Pool"""
                if self._pingdata is None:
                        self._pingdata = ping ()
                return (self._pingdata [1] & PIOF_FACILITY_STARTGSS) != 0

        def starttls (self):
                """Modify the current socket to make it a TLS socket.  Use the
                   tlsdata as currently setup (see class-level documentation).
                   Afterwards, call handle_secure() to start from scratch with
                   a secure connection.  Also see the man page on the underlying
                   C library call, tlspool_starttls(3).
                   
                   Some protocols start TLS immediately, for instance HTTPS;
                   for such protocols, the handle() method would immediately
                   call starttls() and the actual handler code would move
                   into secure_handle().
                   
                   Other protocols, such as XMPP and IMAP, start in plaintext
                   and exchange pleasantries until they agree on running TLS.
                   This is the point where starttls() can be invoked.
                   
                   The methods startssh() and startgss() are place holders for
                   future alternatives to start other security wrappers than
                   TLS, after negotiating them in a manner similar to STARTTLS.
                """
                if type (self.request) == tuple:
                        sox = self.request [1]
                else:
                        sox = self.request
                assert (type (sox) == socket._socketobject)
                try:
                        af = sox.family
                except:
                        af = socket.AF_INET
                try:
                        if   sox.proto in [socket.IPPROTO_UDP]:
                                socktp = socket.SOCK_DGRAM
                        elif sox.proto in [socket.IPPROTO_SCTP]:
                                socktp = socket.SOCK_SEQPACKET
                        else:
                                socktp = socket.SOCK_STREAM
                except:
                        socktp = socket.SOCK_STREAM
                plainsockptr = socket_data ()
                plainsockptr.unix_socket = -1
                rv = _starttls (sox.fileno (), self.tlsdata, plainsockptr, None)
                if rv < 0:
                        _tlspool.raise_errno ()
                assert (plainsockptr.unix_socket >= 0)
                sox2 = socket.fromfd (plainsockptr.unix_socket, af, socktp)
                if type (self.request) == tuple:
                        self.request [1] = sox2
                else:
                        self.request     = sox2
                self.handle_secure ()

        def startssh (self):
                raise NotImplementedError ("Python wrapper does not implement STARTSSH")

        def startgss (self):
                raise NotImplementedError ("Python wrapper does not implement STARTGSS")

        def handle (self):
                """When not overridden, the handle() method replaces the one in
                   later-mentioned classes in the inheritance structure.  This
                   means that this is the default behaviour when the SecureMixIn
                   precedes the handler class.  This particular version of handle()
                   does nothing but invoke starttls(), which in turn invokes
                   handle_secure() after the TLS handshake has succeeded.
                """
                print 'STARTTLS.BEGIN'
                self.starttls ()
                print 'STARTTLS.END'

        def handle_secure (self):
                """This method may be overridden to handle the secure part of the
                   connection, after starttls() has been called from within
                   handle().  This function is special in the sense that it may
                   refer to self.tlsdata and rely on the localid and remoteid
                   as being negotiated over TLS.
                   
                   Since any prior actions in handle() are usually unauthenticated,
                   it is common to start from scratch with the protocol.  The secure
                   layer however, tends to enable more features, such as blunt
                   password submission and, perhaps, privileged operations available
                   to the authenticated self.tlsdata.remoteid user.
                   
                   As an example, if the handler class is BaseHTTPRequestHandler,
                   its handle() method could be invoked on the secured content
                   (possibly after authorisation) with an override as follows:
                   
                        def handle_secure (self):
                                BaseHTTPRequestHandler.handle (self)
                """
                pass

%}

%include "defines.h"