10.0.0.21 Git - tlspool/blob - lib/python/tlspool.py

   1 # This file was automatically generated by SWIG (http://www.swig.org).
   2 # Version 3.0.10
   3 #
   4 # Do not make changes to this file unless you know what you are doing--modify
   5 # the SWIG interface file instead.
   6
   7
   8
   9
  10
  11 from sys import version_info as _swig_python_version_info
  12 if _swig_python_version_info >= (2, 7, 0):
  13     def swig_import_helper():
  14         import importlib
  15         pkg = __name__.rpartition('.')[0]
  16         mname = '.'.join((pkg, '_tlspool')).lstrip('.')
  17         try:
  18             return importlib.import_module(mname)
  19         except ImportError:
  20             return importlib.import_module('_tlspool')
  21     _tlspool = swig_import_helper()
  22     del swig_import_helper
  23 elif _swig_python_version_info >= (2, 6, 0):
  24     def swig_import_helper():
  25         from os.path import dirname
  26         import imp
  27         fp = None
  28         try:
  29             fp, pathname, description = imp.find_module('_tlspool', [dirname(__file__)])
  30         except ImportError:
  31             import _tlspool
  32             return _tlspool
  33         if fp is not None:
  34             try:
  35                 _mod = imp.load_module('_tlspool', fp, pathname, description)
  36             finally:
  37                 fp.close()
  38             return _mod
  39     _tlspool = swig_import_helper()
  40     del swig_import_helper
  41 else:
  42     import _tlspool
  43 del _swig_python_version_info
  44 try:
  45     _swig_property = property
  46 except NameError:
  47     pass  # Python < 2.2 doesn't have 'property'.
  48
  49 try:
  50     import builtins as __builtin__
  51 except ImportError:
  52     import __builtin__
  53
  54 def _swig_setattr_nondynamic(self, class_type, name, value, static=1):
  55     if (name == "thisown"):
  56         return self.this.own(value)
  57     if (name == "this"):
  58         if type(value).__name__ == 'SwigPyObject':
  59             self.__dict__[name] = value
  60             return
  61     method = class_type.__swig_setmethods__.get(name, None)
  62     if method:
  63         return method(self, value)
  64     if (not static):
  65         if _newclass:
  66             object.__setattr__(self, name, value)
  67         else:
  68             self.__dict__[name] = value
  69     else:
  70         raise AttributeError("You cannot add attributes to %s" % self)
  71
  72
  73 def _swig_setattr(self, class_type, name, value):
  74     return _swig_setattr_nondynamic(self, class_type, name, value, 0)
  75
  76
  77 def _swig_getattr(self, class_type, name):
  78     if (name == "thisown"):
  79         return self.this.own()
  80     method = class_type.__swig_getmethods__.get(name, None)
  81     if method:
  82         return method(self)
  83     raise AttributeError("'%s' object has no attribute '%s'" % (class_type.__name__, name))
  84
  85
  86 def _swig_repr(self):
  87     try:
  88         strthis = "proxy of " + self.this.__repr__()
  89     except __builtin__.Exception:
  90         strthis = ""
  91     return "<%s.%s; %s >" % (self.__class__.__module__, self.__class__.__name__, strthis,)
  92
  93 try:
  94     _object = object
  95     _newclass = 1
  96 except __builtin__.Exception:
  97     class _object:
  98         pass
  99     _newclass = 0
 100
 101 class error_data(_object):
 102     __swig_setmethods__ = {}
 103     __setattr__ = lambda self, name, value: _swig_setattr(self, error_data, name, value)
 104     __swig_getmethods__ = {}
 105     __getattr__ = lambda self, name: _swig_getattr(self, error_data, name)
 106     __repr__ = _swig_repr
 107     __swig_setmethods__["tlserrno"] = _tlspool.error_data_tlserrno_set
 108     __swig_getmethods__["tlserrno"] = _tlspool.error_data_tlserrno_get
 109     if _newclass:
 110         tlserrno = _swig_property(_tlspool.error_data_tlserrno_get, _tlspool.error_data_tlserrno_set)
 111     __swig_setmethods__["message"] = _tlspool.error_data_message_set
 112     __swig_getmethods__["message"] = _tlspool.error_data_message_get
 113     if _newclass:
 114         message = _swig_property(_tlspool.error_data_message_get, _tlspool.error_data_message_set)
 115
 116     def __init__(self):
 117         this = _tlspool.new_error_data()
 118         try:
 119             self.this.append(this)
 120         except __builtin__.Exception:
 121             self.this = this
 122     __swig_destroy__ = _tlspool.delete_error_data
 123     __del__ = lambda self: None
 124 error_data_swigregister = _tlspool.error_data_swigregister
 125 error_data_swigregister(error_data)
 126
 127 class ping_data(_object):
 128     __swig_setmethods__ = {}
 129     __setattr__ = lambda self, name, value: _swig_setattr(self, ping_data, name, value)
 130     __swig_getmethods__ = {}
 131     __getattr__ = lambda self, name: _swig_getattr(self, ping_data, name)
 132     __repr__ = _swig_repr
 133     __swig_setmethods__["YYYYMMDD_producer"] = _tlspool.ping_data_YYYYMMDD_producer_set
 134     __swig_getmethods__["YYYYMMDD_producer"] = _tlspool.ping_data_YYYYMMDD_producer_get
 135     if _newclass:
 136         YYYYMMDD_producer = _swig_property(_tlspool.ping_data_YYYYMMDD_producer_get, _tlspool.ping_data_YYYYMMDD_producer_set)
 137     __swig_setmethods__["facilities"] = _tlspool.ping_data_facilities_set
 138     __swig_getmethods__["facilities"] = _tlspool.ping_data_facilities_get
 139     if _newclass:
 140         facilities = _swig_property(_tlspool.ping_data_facilities_get, _tlspool.ping_data_facilities_set)
 141
 142     def __init__(self):
 143         this = _tlspool.new_ping_data()
 144         try:
 145             self.this.append(this)
 146         except __builtin__.Exception:
 147             self.this = this
 148     __swig_destroy__ = _tlspool.delete_ping_data
 149     __del__ = lambda self: None
 150 ping_data_swigregister = _tlspool.ping_data_swigregister
 151 ping_data_swigregister(ping_data)
 152
 153 class starttls_data(_object):
 154     __swig_setmethods__ = {}
 155     __setattr__ = lambda self, name, value: _swig_setattr(self, starttls_data, name, value)
 156     __swig_getmethods__ = {}
 157     __getattr__ = lambda self, name: _swig_getattr(self, starttls_data, name)
 158     __repr__ = _swig_repr
 159     __swig_setmethods__["flags"] = _tlspool.starttls_data_flags_set
 160     __swig_getmethods__["flags"] = _tlspool.starttls_data_flags_get
 161     if _newclass:
 162         flags = _swig_property(_tlspool.starttls_data_flags_get, _tlspool.starttls_data_flags_set)
 163     __swig_setmethods__["local"] = _tlspool.starttls_data_local_set
 164     __swig_getmethods__["local"] = _tlspool.starttls_data_local_get
 165     if _newclass:
 166         local = _swig_property(_tlspool.starttls_data_local_get, _tlspool.starttls_data_local_set)
 167     __swig_setmethods__["ipproto"] = _tlspool.starttls_data_ipproto_set
 168     __swig_getmethods__["ipproto"] = _tlspool.starttls_data_ipproto_get
 169     if _newclass:
 170         ipproto = _swig_property(_tlspool.starttls_data_ipproto_get, _tlspool.starttls_data_ipproto_set)
 171     __swig_setmethods__["streamid"] = _tlspool.starttls_data_streamid_set
 172     __swig_getmethods__["streamid"] = _tlspool.starttls_data_streamid_get
 173     if _newclass:
 174         streamid = _swig_property(_tlspool.starttls_data_streamid_get, _tlspool.starttls_data_streamid_set)
 175     __swig_setmethods__["localid"] = _tlspool.starttls_data_localid_set
 176     __swig_getmethods__["localid"] = _tlspool.starttls_data_localid_get
 177     if _newclass:
 178         localid = _swig_property(_tlspool.starttls_data_localid_get, _tlspool.starttls_data_localid_set)
 179     __swig_setmethods__["remoteid"] = _tlspool.starttls_data_remoteid_set
 180     __swig_getmethods__["remoteid"] = _tlspool.starttls_data_remoteid_get
 181     if _newclass:
 182         remoteid = _swig_property(_tlspool.starttls_data_remoteid_get, _tlspool.starttls_data_remoteid_set)
 183     __swig_setmethods__["ctlkey"] = _tlspool.starttls_data_ctlkey_set
 184     __swig_getmethods__["ctlkey"] = _tlspool.starttls_data_ctlkey_get
 185     if _newclass:
 186         ctlkey = _swig_property(_tlspool.starttls_data_ctlkey_get, _tlspool.starttls_data_ctlkey_set)
 187     __swig_setmethods__["service"] = _tlspool.starttls_data_service_set
 188     __swig_getmethods__["service"] = _tlspool.starttls_data_service_get
 189     if _newclass:
 190         service = _swig_property(_tlspool.starttls_data_service_get, _tlspool.starttls_data_service_set)
 191     __swig_setmethods__["timeout"] = _tlspool.starttls_data_timeout_set
 192     __swig_getmethods__["timeout"] = _tlspool.starttls_data_timeout_get
 193     if _newclass:
 194         timeout = _swig_property(_tlspool.starttls_data_timeout_get, _tlspool.starttls_data_timeout_set)
 195
 196     def __init__(self):
 197         this = _tlspool.new_starttls_data()
 198         try:
 199             self.this.append(this)
 200         except __builtin__.Exception:
 201             self.this = this
 202     __swig_destroy__ = _tlspool.delete_starttls_data
 203     __del__ = lambda self: None
 204 starttls_data_swigregister = _tlspool.starttls_data_swigregister
 205 starttls_data_swigregister(starttls_data)
 206
 207 class control_data(_object):
 208     __swig_setmethods__ = {}
 209     __setattr__ = lambda self, name, value: _swig_setattr(self, control_data, name, value)
 210     __swig_getmethods__ = {}
 211     __getattr__ = lambda self, name: _swig_getattr(self, control_data, name)
 212     __repr__ = _swig_repr
 213     __swig_setmethods__["flags"] = _tlspool.control_data_flags_set
 214     __swig_getmethods__["flags"] = _tlspool.control_data_flags_get
 215     if _newclass:
 216         flags = _swig_property(_tlspool.control_data_flags_get, _tlspool.control_data_flags_set)
 217     __swig_setmethods__["ctlkey"] = _tlspool.control_data_ctlkey_set
 218     __swig_getmethods__["ctlkey"] = _tlspool.control_data_ctlkey_get
 219     if _newclass:
 220         ctlkey = _swig_property(_tlspool.control_data_ctlkey_get, _tlspool.control_data_ctlkey_set)
 221     __swig_setmethods__["name"] = _tlspool.control_data_name_set
 222     __swig_getmethods__["name"] = _tlspool.control_data_name_get
 223     if _newclass:
 224         name = _swig_property(_tlspool.control_data_name_get, _tlspool.control_data_name_set)
 225
 226     def __init__(self):
 227         this = _tlspool.new_control_data()
 228         try:
 229             self.this.append(this)
 230         except __builtin__.Exception:
 231             self.this = this
 232     __swig_destroy__ = _tlspool.delete_control_data
 233     __del__ = lambda self: None
 234 control_data_swigregister = _tlspool.control_data_swigregister
 235 control_data_swigregister(control_data)
 236
 237 class prng_data(_object):
 238     __swig_setmethods__ = {}
 239     __setattr__ = lambda self, name, value: _swig_setattr(self, prng_data, name, value)
 240     __swig_getmethods__ = {}
 241     __getattr__ = lambda self, name: _swig_getattr(self, prng_data, name)
 242     __repr__ = _swig_repr
 243     __swig_setmethods__["in1_len"] = _tlspool.prng_data_in1_len_set
 244     __swig_getmethods__["in1_len"] = _tlspool.prng_data_in1_len_get
 245     if _newclass:
 246         in1_len = _swig_property(_tlspool.prng_data_in1_len_get, _tlspool.prng_data_in1_len_set)
 247     __swig_setmethods__["in2_len"] = _tlspool.prng_data_in2_len_set
 248     __swig_getmethods__["in2_len"] = _tlspool.prng_data_in2_len_get
 249     if _newclass:
 250         in2_len = _swig_property(_tlspool.prng_data_in2_len_get, _tlspool.prng_data_in2_len_set)
 251     __swig_setmethods__["prng_len"] = _tlspool.prng_data_prng_len_set
 252     __swig_getmethods__["prng_len"] = _tlspool.prng_data_prng_len_get
 253     if _newclass:
 254         prng_len = _swig_property(_tlspool.prng_data_prng_len_get, _tlspool.prng_data_prng_len_set)
 255     __swig_setmethods__["buffer"] = _tlspool.prng_data_buffer_set
 256     __swig_getmethods__["buffer"] = _tlspool.prng_data_buffer_get
 257     if _newclass:
 258         buffer = _swig_property(_tlspool.prng_data_buffer_get, _tlspool.prng_data_buffer_set)
 259
 260     def __init__(self):
 261         this = _tlspool.new_prng_data()
 262         try:
 263             self.this.append(this)
 264         except __builtin__.Exception:
 265             self.this = this
 266     __swig_destroy__ = _tlspool.delete_prng_data
 267     __del__ = lambda self: None
 268 prng_data_swigregister = _tlspool.prng_data_swigregister
 269 prng_data_swigregister(prng_data)
 270
 271 class socket_data(_object):
 272     __swig_setmethods__ = {}
 273     __setattr__ = lambda self, name, value: _swig_setattr(self, socket_data, name, value)
 274     __swig_getmethods__ = {}
 275     __getattr__ = lambda self, name: _swig_getattr(self, socket_data, name)
 276     __repr__ = _swig_repr
 277     __swig_setmethods__["unix_socket"] = _tlspool.socket_data_unix_socket_set
 278     __swig_getmethods__["unix_socket"] = _tlspool.socket_data_unix_socket_get
 279     if _newclass:
 280         unix_socket = _swig_property(_tlspool.socket_data_unix_socket_get, _tlspool.socket_data_unix_socket_set)
 281
 282     def __init__(self):
 283         this = _tlspool.new_socket_data()
 284         try:
 285             self.this.append(this)
 286         except __builtin__.Exception:
 287             self.this = this
 288     __swig_destroy__ = _tlspool.delete_socket_data
 289     __del__ = lambda self: None
 290 socket_data_swigregister = _tlspool.socket_data_swigregister
 291 socket_data_swigregister(socket_data)
 292
 293
 294 def _pid(opt_pidfile):
 295     return _tlspool._pid(opt_pidfile)
 296 _pid = _tlspool._pid
 297
 298 def _open_poolhandle(path):
 299     return _tlspool._open_poolhandle(path)
 300 _open_poolhandle = _tlspool._open_poolhandle
 301
 302 def _ping(pingdata):
 303     return _tlspool._ping(pingdata)
 304 _ping = _tlspool._ping
 305
 306 def _starttls(cryptfd, tlsdata, privdata, swig_null_callback):
 307     return _tlspool._starttls(cryptfd, tlsdata, privdata, swig_null_callback)
 308 _starttls = _tlspool._starttls
 309
 310 def _control_detach(ctlkey):
 311     return _tlspool._control_detach(ctlkey)
 312 _control_detach = _tlspool._control_detach
 313
 314 def _control_reattach(ctlkey):
 315     return _tlspool._control_reattach(ctlkey)
 316 _control_reattach = _tlspool._control_reattach
 317
 318 def _prng(label, opt_ctxvalue, prng_len, prng_buf, ctlkey):
 319     return _tlspool._prng(label, opt_ctxvalue, prng_len, prng_buf, ctlkey)
 320 _prng = _tlspool._prng
 321
 322 def tlspool_configvar(cfgfile, varname):
 323     return _tlspool.tlspool_configvar(cfgfile, varname)
 324 tlspool_configvar = _tlspool.tlspool_configvar
 325
 326 def raise_errno():
 327     return _tlspool.raise_errno()
 328 raise_errno = _tlspool.raise_errno
 329
 330
 331
 332 import os
 333 import socket
 334
 335 if not 'IPPROTO_SCTP' in dir (socket):
 336         socket.IPPROTO_SCTP = 132
 337
 338
 339 def pid (pidfile=None):
 340         """This function returns the process identity of the TLS Pool.
 341            When no pidfile is provided, the default path as configured in the
 342            TLS Pool libary will be used.  An Exception is thrown when there is
 343            no TLS Pool.
 344         """
 345         process_id = _pid (pidfile)
 346         if process_id < 0:
 347                 _tlspool.raise_errno ()
 348         else:
 349                 return process_id
 350
 351 def open_poolhandle (path=None):
 352         """This function returns the OS-specific socket handle value for the
 353            TLS Pool.  It is already connected, and shared with the internal
 354            management of this module, so it must not be closed by the caller.
 355            When no path is provided, the default path is used instead.
 356            This function blocks until a connection to the TLS Pool succeeds.
 357            The path is only used in the first call, and only when no prior
 358            contact to the TLS Pool has been made; if that has happened, then
 359            this function returns the previously found socket handle.
 360         """
 361         fd = _open_poolhandle (path)
 362         if fd < 0:
 363                 _tlspool.raise_errno ()
 364         else:
 365                 return fd
 366
 367 def ping (YYYYMMDD_producer=_tlspool.TLSPOOL_IDENTITY_V2,
 368                         facilities=_tlspool.PIOF_FACILITY_ALL_CURRENT):
 369         """This function takes in a string with a date in YYYYMMDD format, followed
 370            by a user@domain producer identifier.  It takes in an integer value
 371            that is the logical or of PIOF_FACILITY_xxx values.  This is sent to
 372            the TLS Pool through tlspool_ping() and the response is returned as a
 373            similar tuple (YYYYMMDD_producer, facilities) as returned by the
 374            TLS Pool.  This function blocks until a connection to the TLS Pool has
 375            been found.  It is a good first command to send to the TLS Pool.
 376         """
 377         pp = ping_data ()
 378         pp.YYYYMMDD_producer = YYYYMMDD_producer
 379         pp.facilities = facilities
 380         if _ping (pp) < 0:
 381                 _tlspool.raise_errno ()
 382         else:
 383                 return (pp.YYYYMMDD_producer, pp.facilities)
 384
 385 def make_tlsdata (localid='', remoteid='',
 386                 flags=0, local_flags=0,
 387                 ipproto=socket.IPPROTO_TCP, streamid=0, service='',
 388                 timeout=0, ctlkey='TODOTODOTODOTODO'):
 389         """Make a new tlsdata structure, based the fields that may be supplied
 390            as flags, or otherwise as defaults.  Note that the field "local" is
 391            renamed to "local_flags" for reasons of clarity.  This helper function
 392            returns a tlsdata structure or raises an exception.
 393         """
 394         tlsdata = starttls_data ()
 395         if ctlkey is not None:
 396                 tlsdata.ctlkey = ctlkey
 397         tlsdata.service = service
 398         tlsdata.localid = localid
 399         tlsdata.remoteid = remoteid
 400         tlsdata.flags = flags
 401         tlsdata.local = local_flags
 402         tlsdata.ipproto = ipproto
 403         tlsdata.streamid = streamid
 404         tlsdata.timeout = timeout
 405         return tlsdata
 406
 407 class Connection:
 408         """The tlspool.Connection class wraps around a connection to be protected
 409            by the TLS Pool.  It uses the global socket for attaching to the
 410            TLS Pool, but the individual instances of this class do represent
 411            individual connections managed by the TLS Pool.
 412            New instances can already collect a large number of parameters
 413            that end up in the tlsdata structure of tlspool_starttls(),
 414            but these values may also be created through getters/setters.
 415            Some values have reasonable defaults, but some must have been
 416            set before invoking the starttls() method on the instance.
 417            The tlsdata fields all have defaults, as specified under
 418            tlspool.make_tlsdata().
 419         """
 420
 421         def __init__ (self, cryptsocket, plainsocket=None, **tlsdata):
 422                 self.cryptsk = cryptsocket
 423                 self.cryptfd = cryptsocket.fileno ()
 424                 self.plainsk = plainsocket
 425                 self.plainfd = plainsocket.fileno () if plainsocket else -1
 426                 self.tlsdata = make_tlsdata (**tlsdata)
 427
 428         def close (self):
 429                 assert (self.plainsk is not None)
 430                 assert (self.plainfd >= 0)
 431                 self.plainsk.close ()
 432                 self.plainsk = None
 433                 self.plainfd = -1
 434
 435         def tlsdata_get (self, tlsvar):
 436                 return self.tlsdata [tlsvar]
 437
 438         def tlsdata_set (self, tlsvar, value):
 439                 self.tlsdata [tlsvar] = value
 440
 441         def starttls (self):
 442                 """Initiate a TLS connection with the current settings, as
 443                    provided during instantiation or through getter/setter
 444                    access afterwards.  The variables that are required at
 445                    this point are service and, already obliged when making
 446                    a new instance, cryptfd.
 447                 """
 448                 assert (self.cryptsk is not None)
 449                 assert (self.cryptfd >= 0)
 450                 assert (self.tlsdata.service != '')
 451                 try:
 452                         af = self.cryptsk.family
 453                 except:
 454                         af = socket.AF_INET
 455                 try:
 456                         if   self.cryptsk.proto in [socket.IPPROTO_UDP]:
 457                                 socktp = socket.SOCK_DGRAM
 458                         elif self.cryptsk.proto in [socket.IPPROTO_SCTP]:
 459                                 socktp = socket.SOCK_SEQPACKET
 460                         else:
 461                                 socktp = socket.SOCK_STREAM
 462                 except:
 463                         socktp = socket.SOCK_STREAM
 464                 plainsockptr = socket_data ()
 465                 plainsockptr.unix_socket = self.plainfd
 466 # Provide None for the callback function, SWIG won't support it
 467 # We might at some point desire a library of C routine options?
 468                 rv = _starttls (self.cryptfd, self.tlsdata, plainsockptr, None)
 469                 self.plainfd = -1
 470                 self.cryptfd = -1
 471                 self.cryptsk = None
 472                 if rv < 0:
 473                         _tlspool.raise_errno ()
 474                 if self.plainsk is None:
 475                         self.plainfd = plainsockptr.unix_socket
 476                         self.plainsk = socket.fromfd (self.plainfd, af, socktp)
 477                 return self.plainsk
 478
 479         def prng (self, length, label, ctxvalue=None):
 480                 """Produce length bytes of randomness from the master key, after
 481                    mixing it with the label and optional context value in ctxvalue.
 482                    The procedure has been described in RFC 5705.
 483 #TODO# Find a way to return the random bytes, and use the length
 484                 """
 485                 assert (length > 0)
 486                 assert (1 <= len (label) <= 254)
 487                 assert (1 <= len (ctxvalue or 'X') <= 254)
 488                 buf = prng_data ()
 489 # buf.in1_len = len (label)
 490 # buf.in2_len = len (ctxvalue) if ctxvalue is not None else 255
 491 # buf.prng_len = length
 492                 rv = _prng (label, ctxvalue, length, buf.buffer, self.tlsdata.ctlkey)
 493                 if rv < 0:
 494                         _tlspool.raise_errno ()
 495                 else:
 496                         return buf.buffer [:length]
 497
 498         def control_detach (self):
 499                 """Detach control of this connection.  Although the connection
 500                    itself will still be available, control over it is diminished
 501                    and its continuation is no longer dependent on the current
 502                    connection.  You may need to pass tlsdata.ctlkey to another
 503                    process, or use control_reattach(), before this is reversed
 504                    in this process or another.
 505                 """
 506                 _control_detach (self.tlsdata.ctlkey)
 507
 508         def control_reattach (self, ctlkey=None):
 509                 """Reattach control of this connection.  The connection may have
 510                    called control_detach() in this process or another.  To help
 511                    with the latter case, its tlsdata.ctlkey must have been moved
 512                    into this instance.
 513                 """
 514                 _control_reattach (self.tlsdata.ctlkey)
 515
 516 class SecurityMixIn:
 517         """The SecurityMixIn class can be added as a subclass before a
 518            (subclass of) SocketServer.BaseServer and it adds the facilities
 519            of starttls(), startgss() and startssh() which add security through
 520            one of the mechanisms.  In addition, have_xxx() can be used to
 521            query in advance if startxxx() should be doable with the present
 522            combination of TLS Pool and client code.
 523
 524            Set a tlsdata field in the subclass, using the tlspool.make_tlsdata()
 525            helper function, to bootstrap the same kind of behaviour on all
 526            clients for which this class will be instantiated.  Such a tlsdata
 527            class variable will automatically be cloned into instances.
 528            Example code:
 529
 530                 from tlspool import SecurityMixIn
 531                 from SocketServer import BaseHandler
 532
 533                 class MyHandler (SecurityMixIn, BaseHandler):
 534
 535                         tlsdata = make_tlsdata (service=...)
 536
 537                         def handle (self):
 538                                 ...
 539                                 self.starttls ()
 540
 541                         def handle_secure (self):
 542                                 ...
 543
 544            Alternatively, you can setup the tlsdata structure, or any part of it,
 545            at a later time, through the tlsdata variable that will then be
 546            instantiated during object initialisation.  Any such changes to fields
 547            must be completed before invoking starttls() on this object.
 548         """
 549
 550         _pingdata = None
 551         tlsdata = None
 552
 553         def __init__ (self):
 554                 if self.tlsdata is None:
 555                         self.tlsdata = make_tlsdata ()
 556
 557         def have_tls (self):
 558                 """Check whether STARTTLS is supported on the current TLS Pool"""
 559                 if self._pingdata is None:
 560                         self._pingdata = ping ()
 561                 return (self._pingdata [1] & PIOF_FACILITY_STARTTLS) != 0
 562
 563         def have_ssh (self):
 564                 """Check whether STARTSSH is supported on the current TLS Pool"""
 565                 if self._pingdata is None:
 566                         self._pingdata = ping ()
 567                 return (self._pingdata [1] & PIOF_FACILITY_STARTSSH) != 0
 568
 569         def have_gss (self):
 570                 """Check whether STARTGSS is supported on the current TLS Pool"""
 571                 if self._pingdata is None:
 572                         self._pingdata = ping ()
 573                 return (self._pingdata [1] & PIOF_FACILITY_STARTGSS) != 0
 574
 575         def starttls (self):
 576                 """Modify the current socket to make it a TLS socket.  Use the
 577                    tlsdata as currently setup (see class-level documentation).
 578                    Afterwards, call handle_secure() to start from scratch with
 579                    a secure connection.  Also see the man page on the underlying
 580                    C library call, tlspool_starttls(3).
 581
 582                    Some protocols start TLS immediately, for instance HTTPS;
 583                    for such protocols, the handle() method would immediately
 584                    call starttls() and the actual handler code would move
 585                    into secure_handle().
 586
 587                    Other protocols, such as XMPP and IMAP, start in plaintext
 588                    and exchange pleasantries until they agree on running TLS.
 589                    This is the point where starttls() can be invoked.
 590
 591                    The methods startssh() and startgss() are place holders for
 592                    future alternatives to start other security wrappers than
 593                    TLS, after negotiating them in a manner similar to STARTTLS.
 594                 """
 595                 if type (self.request) == tuple:
 596                         sox = self.request [1]
 597                 else:
 598                         sox = self.request
 599                 assert (type (sox) == socket._socketobject)
 600                 try:
 601                         af = sox.family
 602                 except:
 603                         af = socket.AF_INET
 604                 try:
 605                         if   sox.proto in [socket.IPPROTO_UDP]:
 606                                 socktp = socket.SOCK_DGRAM
 607                         elif sox.proto in [socket.IPPROTO_SCTP]:
 608                                 socktp = socket.SOCK_SEQPACKET
 609                         else:
 610                                 socktp = socket.SOCK_STREAM
 611                 except:
 612                         socktp = socket.SOCK_STREAM
 613                 plainsockptr = socket_data ()
 614                 plainsockptr.unix_socket = -1
 615                 rv = _starttls (sox.fileno (), self.tlsdata, plainsockptr, None)
 616                 if rv < 0:
 617                         _tlspool.raise_errno ()
 618                 assert (plainsockptr.unix_socket >= 0)
 619                 sox2 = socket.fromfd (plainsockptr.unix_socket, af, socktp)
 620                 if type (self.request) == tuple:
 621                         self.request [1] = sox2
 622                 else:
 623                         self.request     = sox2
 624                 self.handle_secure ()
 625                 sox2.close ()
 626
 627         def startssh (self):
 628                 raise NotImplementedError ("Python wrapper does not implement STARTSSH")
 629
 630         def startgss (self):
 631                 raise NotImplementedError ("Python wrapper does not implement STARTGSS")
 632
 633         def handle (self):
 634                 """When not overridden, the handle() method replaces the one in
 635                    later-mentioned classes in the inheritance structure.  This
 636                    means that this is the default behaviour when the SecureMixIn
 637                    precedes the handler class.  This particular version of handle()
 638                    does nothing but invoke starttls(), which in turn invokes
 639                    handle_secure() after the TLS handshake has succeeded.
 640                 """
 641                 self.starttls ()
 642
 643         def handle_secure (self):
 644                 """This method may be overridden to handle the secure part of the
 645                    connection, after starttls() has been called from within
 646                    handle().  This function is special in the sense that it may
 647                    refer to self.tlsdata and rely on the localid and remoteid
 648                    as being negotiated over TLS.
 649
 650                    Since any prior actions in handle() are usually unauthenticated,
 651                    it is common to start from scratch with the protocol.  The secure
 652                    layer however, tends to enable more features, such as blunt
 653                    password submission and, perhaps, privileged operations available
 654                    to the authenticated self.tlsdata.remoteid user.
 655
 656                    As an example, if the handler class is BaseHTTPRequestHandler,
 657                    its handle() method could be invoked on the secured content
 658                    (possibly after authorisation) with an override as follows:
 659
 660                         def handle_secure (self):
 661                                 BaseHTTPRequestHandler.handle (self)
 662                 """
 663                 pass
 664
 665
 666 PIOC_CONTROL_DETACH_V2 = _tlspool.PIOC_CONTROL_DETACH_V2
 667 PIOC_CONTROL_REATTACH_V2 = _tlspool.PIOC_CONTROL_REATTACH_V2
 668 PIOC_ERROR_V2 = _tlspool.PIOC_ERROR_V2
 669 PIOC_LIDENTRY_CALLBACK_V2 = _tlspool.PIOC_LIDENTRY_CALLBACK_V2
 670 PIOC_LIDENTRY_REGISTER_V2 = _tlspool.PIOC_LIDENTRY_REGISTER_V2
 671 PIOC_LOCAL = _tlspool.PIOC_LOCAL
 672 PIOC_PINENTRY_V2 = _tlspool.PIOC_PINENTRY_V2
 673 PIOC_PING_V2 = _tlspool.PIOC_PING_V2
 674 PIOC_PLAINTEXT_CONNECT_V2 = _tlspool.PIOC_PLAINTEXT_CONNECT_V2
 675 PIOC_PRNG_V2 = _tlspool.PIOC_PRNG_V2
 676 PIOC_STARTTLS_LOCALID_V2 = _tlspool.PIOC_STARTTLS_LOCALID_V2
 677 PIOC_STARTTLS_V2 = _tlspool.PIOC_STARTTLS_V2
 678 PIOC_SUCCESS_V2 = _tlspool.PIOC_SUCCESS_V2
 679 PIOF_FACILITY_ALL_CURRENT = _tlspool.PIOF_FACILITY_ALL_CURRENT
 680 PIOF_FACILITY_STARTGSS = _tlspool.PIOF_FACILITY_STARTGSS
 681 PIOF_FACILITY_STARTSSH = _tlspool.PIOF_FACILITY_STARTSSH
 682 PIOF_FACILITY_STARTTLS = _tlspool.PIOF_FACILITY_STARTTLS
 683 PIOF_LIDENTRY_DBAPPEND = _tlspool.PIOF_LIDENTRY_DBAPPEND
 684 PIOF_LIDENTRY_DBENTRY = _tlspool.PIOF_LIDENTRY_DBENTRY
 685 PIOF_LIDENTRY_DBINSERT = _tlspool.PIOF_LIDENTRY_DBINSERT
 686 PIOF_LIDENTRY_DBREORDER = _tlspool.PIOF_LIDENTRY_DBREORDER
 687 PIOF_LIDENTRY_NEW = _tlspool.PIOF_LIDENTRY_NEW
 688 PIOF_LIDENTRY_ONTHEFLY = _tlspool.PIOF_LIDENTRY_ONTHEFLY
 689 PIOF_LIDENTRY_REGFLAGS = _tlspool.PIOF_LIDENTRY_REGFLAGS
 690 PIOF_LIDENTRY_SKIP_DBENTRY = _tlspool.PIOF_LIDENTRY_SKIP_DBENTRY
 691 PIOF_LIDENTRY_SKIP_DOMAIN_ONEUP = _tlspool.PIOF_LIDENTRY_SKIP_DOMAIN_ONEUP
 692 PIOF_LIDENTRY_SKIP_DOMAIN_SAME = _tlspool.PIOF_LIDENTRY_SKIP_DOMAIN_SAME
 693 PIOF_LIDENTRY_SKIP_DOMAIN_SUB = _tlspool.PIOF_LIDENTRY_SKIP_DOMAIN_SUB
 694 PIOF_LIDENTRY_SKIP_NOTROOT = _tlspool.PIOF_LIDENTRY_SKIP_NOTROOT
 695 PIOF_LIDENTRY_SKIP_USER = _tlspool.PIOF_LIDENTRY_SKIP_USER
 696 PIOF_LIDENTRY_WANT_DBENTRY = _tlspool.PIOF_LIDENTRY_WANT_DBENTRY
 697 PIOF_STARTTLS_DETACH = _tlspool.PIOF_STARTTLS_DETACH
 698 PIOF_STARTTLS_DOMAIN_REPRESENTS_USER = _tlspool.PIOF_STARTTLS_DOMAIN_REPRESENTS_USER
 699 PIOF_STARTTLS_DTLS = _tlspool.PIOF_STARTTLS_DTLS
 700 PIOF_STARTTLS_FORK = _tlspool.PIOF_STARTTLS_FORK
 701 PIOF_STARTTLS_IGNORE_CACHES = _tlspool.PIOF_STARTTLS_IGNORE_CACHES
 702 PIOF_STARTTLS_IGNORE_REMOTEID = _tlspool.PIOF_STARTTLS_IGNORE_REMOTEID
 703 PIOF_STARTTLS_LOCALID_CHECK = _tlspool.PIOF_STARTTLS_LOCALID_CHECK
 704 PIOF_STARTTLS_LOCALID_ONTHEFLY = _tlspool.PIOF_STARTTLS_LOCALID_ONTHEFLY
 705 PIOF_STARTTLS_LOCALROLE_CLIENT = _tlspool.PIOF_STARTTLS_LOCALROLE_CLIENT
 706 PIOF_STARTTLS_LOCALROLE_PEER = _tlspool.PIOF_STARTTLS_LOCALROLE_PEER
 707 PIOF_STARTTLS_LOCALROLE_SERVER = _tlspool.PIOF_STARTTLS_LOCALROLE_SERVER
 708 PIOF_STARTTLS_REMOTEROLE_CLIENT = _tlspool.PIOF_STARTTLS_REMOTEROLE_CLIENT
 709 PIOF_STARTTLS_REMOTEROLE_PEER = _tlspool.PIOF_STARTTLS_REMOTEROLE_PEER
 710 PIOF_STARTTLS_REMOTEROLE_SERVER = _tlspool.PIOF_STARTTLS_REMOTEROLE_SERVER
 711 PIOF_STARTTLS_RENEGOTIATE = _tlspool.PIOF_STARTTLS_RENEGOTIATE
 712 PIOF_STARTTLS_REQUEST_REMOTEID = _tlspool.PIOF_STARTTLS_REQUEST_REMOTEID
 713 PIOF_STARTTLS_WITHOUT_SNI = _tlspool.PIOF_STARTTLS_WITHOUT_SNI
 714 TLSPOOL_CTLKEYLEN = _tlspool.TLSPOOL_CTLKEYLEN
 715 TLSPOOL_DEFAULT_PIDFILE_PATH = _tlspool.TLSPOOL_DEFAULT_PIDFILE_PATH
 716 TLSPOOL_DEFAULT_SOCKET_PATH = _tlspool.TLSPOOL_DEFAULT_SOCKET_PATH
 717 TLSPOOL_IDENTITY_V2 = _tlspool.TLSPOOL_IDENTITY_V2
 718 TLSPOOL_PRNGBUFLEN = _tlspool.TLSPOOL_PRNGBUFLEN
 719 TLSPOOL_SERVICELEN = _tlspool.TLSPOOL_SERVICELEN
 720 TLSPOOL_TIMEOUT_DEFAULT = _tlspool.TLSPOOL_TIMEOUT_DEFAULT
 721 # This file is compatible with both classic and new-style classes.
 722
 723