path

PathConstraints

PathConstraints represent constraints on a path through the Tor network. They are constructed by passing a dict of {‘keyword’: ‘value’} as an argument for each node. A list of filters is built for each node. Then, using the satisfy() method, a PathConstraints object can select only the RelayDescriptors that satisfy the proper constraints.

Path constraint objects can be used as follows (suppose relays is a list of RelayDescriptors):

>>> p = PathConstraints(entry={'ntor': True, 'flags': ['Fast', 'Guard']},
>>>                     middle={'ntor': True, 'flags': ['Stable'],
>>>                     exit={'ntor': True, 'flags': ['Exit'],
>>>                           'exit_to_port': 443})
>>> entry_candidates = p.satisfy(node='entry', relays)

entry_candidates would now be a list of all relays that satisfy the entry node constraints.

PathSelector

PathSelector objects simplify choosing a full path. PathSelectors take a PathConstraints object as an argument to the constructor. When getPath() is called, PathSelectors use these PathConstraints to build a path through the Tor network, taking care of some additional concerns including:

• not selecting two relays in the same family
• not selecting two relays in the same /16
• not selecting the same relay in a path twice

getPath() returns a deferred that will fire with the chosen Path object.

class path.path.Path

Bases: tuple

Path(entry, middle, exit)

entry

Alias for field number 0

exit

Alias for field number 2

middle

Alias for field number 1

class path.path.PathConstraints(entry, middle, exit)

Bases: object

Represent a set of path constraints.

keywords = set(['ntor', 'exit_to_IP', 'fingerprint', 'exit_to_port', 'flags', 'exit_to_IP_and_port', 'exit_IPv6'])

satisfy(relays, node, family_fprints=None, subnets=None)

Return the subset of relays that satisfies the path constraints for chosen node.

Parameters:

• relays (list) – a list (of stem.descriptor.server_descriptor.RelayDescriptor) of relays to filter
• node (str) – the node for which we’re filtering (‘entry’, ‘middle’, or ‘exit’). determines which filters to use
• family_fprints (set) – a set (of str) of fingerprints in use by “family members” of relays on the current path. do not choose any relays with a fingerprint in family_fprints
• subnets (set) – set (of ipaddress.ip_network) of the current /16’s in use for the path in question. do not choose any relays that share the same /16 as a relay that’s already been chosen.

Returns:

list, stem.descriptor.server_descriptor.RelayDescriptor all RelayDescriptors from relays that satisfy the path constraints for the chosen node position

class path.path.PathSelector

Bases: object

Select a path based on some path constraints.

getPath(*args, **kwargs)

Filter the current set of RelayDescriptors and randomly choose an entry, middle, and exit node that satisfy the desired path constraints.

We currently just use the absolutely bare minimum path constraints, namely:

• no two relays in the same family
• no two relays in the same /16
• each relay has the required default flags

Parameters:constraints (oppy.path.path.PathConstraints) – path constraints to satisfy Returns:twisted.internet.defer.Deferred that fires with an oppy.path.Path