bridgedb.bridges¶

Classes for manipulating and storing Bridges and their attributes.

Inheritance diagram of PluggableTransportUnavailable, MalformedBridgeInfo, MalformedPluggableTransport, InvalidPluggableTransportIP, MissingServerDescriptorDigest, ServerDescriptorDigestMismatch, ServerDescriptorWithoutNetworkstatus, InvalidExtraInfoSignature, Flags, PluggableTransport, Bridge

Glossary Terms

Bridge Line: A “Bridge Line” is how BridgeDB refers to lines in a torrc file which should begin with the word "Bridge", and it is how a client tells their Tor process that they would like to use a particular bridge.

exception PluggableTransportUnavailable[source]¶

Bases: exceptions.Exception

Raised when a Bridge doesn’t have the requested PluggableTransport.

exception MalformedBridgeInfo[source]¶

Bases: exceptions.ValueError

Raised when some information about a bridge appears malformed.

exception MalformedPluggableTransport[source]¶

Bases: bridgedb.bridges.MalformedBridgeInfo

Raised when information used to initialise a PluggableTransport appears malformed.

exception InvalidPluggableTransportIP[source]¶

Bases: bridgedb.bridges.MalformedBridgeInfo

Raised when a PluggableTransport has an invalid address.

exception MissingServerDescriptorDigest[source]¶

Bases: bridgedb.bridges.MalformedBridgeInfo

Raised when the hash digest for an @type bridge-server-descriptor (which should be in the corresponding @type bridge-networkstatus document), was missing.

exception ServerDescriptorDigestMismatch[source]¶

Bases: bridgedb.bridges.MalformedBridgeInfo

Raised when the digest in an @type bridge-networkstatus document doesn’t match the hash digest of the @type bridge-server-descriptor‘s contents.

exception ServerDescriptorWithoutNetworkstatus[source]¶

Bases: bridgedb.bridges.MalformedBridgeInfo

Raised when we find a @type bridge-server-descriptor which was not mentioned in the latest @type bridge-networkstatus document.

exception InvalidExtraInfoSignature[source]¶

Bases: bridgedb.bridges.MalformedBridgeInfo

Raised if the signature on an @type bridge-extrainfo is invalid.

interface IBridge[source]¶

I am a (mostly) stub interface whose primary purpose is merely to allow other classes to signify whether or not they can be treated like a Bridge.

fingerprint¶: The lowercased, hexadecimal-encoded, hash digest of this Bridge’s public identity key.

address¶: This Bridge’s primary public IP address.

port¶: The port which this Bridge is listening on.

class Flags[source]¶

Bases: object

All the flags which a Bridge may have.

fast = False¶

guard = False¶

running = False¶

stable = False¶

valid = False¶

update(flags)[source]¶

Update with flags taken from an @type networkstatus-bridge ‘s’-line.

From dir-spec.txt:: “s” SP Flags NL

[Exactly once.]

A series of space-separated status flags, in lexical order (as ASCII

byte strings). Currently documented flags are:

[...]

“Fast” if the router is suitable for high-bandwidth circuits.

“Guard” if the router is suitable for use as an entry guard.

[...]

“Stable” if the router is suitable for long-lived circuits.

“Running” if the router is currently usable.

[...]

“Valid” if the router has been ‘validated’.

Parameters:	flags (list) – A list of strings containing each of the flags parsed from the ‘s’-line.

class BridgeAddressBase[source]¶

Bases: object

A base class for describing one of a Bridge‘s or a PluggableTransport‘s location, including its identity key fingerprint and IP address.

Variables:

Variables:	fingerprint – The uppercased, hexadecimal fingerprint of the identity key of the parent bridge running this pluggable transport instance, i.e. the main ORPort bridge whose `@type bridge-server-descriptor` contains a hash digest for a `@type bridge-extrainfo-document`, the latter of which contains the parameter of this pluggable transport in its `transport` line. address – The IP address of `Bridge` or one of its :class:`PluggableTransport`s. country – The two-letter GeoIP country code of the :ivar:`address`. port – A integer specifying the port which this `Bridge` (or `PluggableTransport`) is listening on.

fingerprint – The uppercased, hexadecimal fingerprint of the identity key of the parent bridge running this pluggable transport instance, i.e. the main ORPort bridge whose @type bridge-server-descriptor contains a hash digest for a @type bridge-extrainfo-document, the latter of which contains the parameter of this pluggable transport in its transport line.
address – The IP address of Bridge or one of its :class:`PluggableTransport`s.
country – The two-letter GeoIP country code of the :ivar:`address`.
port – A integer specifying the port which this Bridge (or PluggableTransport) is listening on.

fingerprint¶

Get this Bridge’s fingerprint.

Return type:	str
Returns:	A 40-character hexadecimal formatted string representation of the SHA-1 hash digest of the public half of this Bridge’s identity key.

identity¶

Get this Bridge’s identity digest.

Return type:	bytes
Returns:	The binary-encoded SHA-1 hash digest of the public half of this Bridge’s identity key, if available; otherwise, returns `None`.

address¶

Get this bridge’s address.

Return type:	`IPv4Address` or `IPv6Address`
Returns:	The bridge’s address.

country¶

Get the two-letter GeoIP country code for the :ivar:`address`.

Return type:	str or `None`
Returns:	If :ivar:`address` is set, this returns a two-letter country code for the geolocated region that :ivar:`address` is within; otherwise, returns `None`.

port¶

Get the port number which this Bridge is listening for incoming client connections on.

Return type:	int or None
Returns:	The port (as an int), if it is known and valid; otherwise, returns `None`.

class PluggableTransport(fingerprint=None, methodname=None, address=None, port=None, arguments=None)[source]¶

Bases: bridgedb.bridges.BridgeAddressBase

A single instance of a Pluggable Transport (PT) offered by a Bridge.

Pluggable transports are described within a bridge’s @type bridge-extrainfo descriptor, see the Specifications: Client behavior section and the TOR_PT_SERVER_TRANSPORT_OPTIONS description in pt-spec.txt for additional specification.

Variables:

Variables:	fingerprint (str) – The uppercased, hexadecimal fingerprint of the identity key of the parent bridge running this pluggable transport instance, i.e. the main ORPort bridge whose `@type bridge-server-descriptor` contains a hash digest for a `@type bridge-extrainfo-document`, the latter of which contains the parameter of this pluggable transport in its `transport` line. methodname (str) – The canonical “name” for this pluggable transport, i.e. the one which would be specified in a torrc file. For example, `"obfs2"`, `"obfs3"`, `"scramblesuit"` would all be pluggable transport method names. address (`ipaddr.IPv4Address` or `ipaddr.IPv6Address`) – The IP address of the transport. Currently (as of 20 March 2014), there are no known, widely-deployed pluggable transports which support IPv6. Ergo, this is very likely going to be an IPv4 address. port (int) – A integer specifying the port which this pluggable transport is listening on. (This should likely be whatever port the bridge specified in its `ServerTransportPlugin` torrc line, unless the pluggable transport is running in “managed” mode.) arguments (dict) – Some PTs can take additional arguments, which must be distributed to the client out-of-band. These are present in the `@type bridge-extrainfo-document`, in the `transport` line like so: METHOD SP ADDR ":" PORT SP [K=V[,K=V[,K=V[…]]]] where K is the key in arguments, and V is the value. For example, in the case of `scramblesuit`, for which the client must supply a shared secret to the `scramblesuit` instance running on the bridge, the arguments would be something like: {'password': 'NEQGQYLUMUQGK5TFOJ4XI2DJNZTS4LRO'}

fingerprint (str) – The uppercased, hexadecimal fingerprint of the identity key of the parent bridge running this pluggable transport instance, i.e. the main ORPort bridge whose @type bridge-server-descriptor contains a hash digest for a @type bridge-extrainfo-document, the latter of which contains the parameter of this pluggable transport in its transport line.
methodname (str) – The canonical “name” for this pluggable transport, i.e. the one which would be specified in a torrc file. For example, "obfs2", "obfs3", "scramblesuit" would all be pluggable transport method names.
address (ipaddr.IPv4Address or ipaddr.IPv6Address) – The IP address of the transport. Currently (as of 20 March 2014), there are no known, widely-deployed pluggable transports which support IPv6. Ergo, this is very likely going to be an IPv4 address.
port (int) – A integer specifying the port which this pluggable transport is listening on. (This should likely be whatever port the bridge specified in its ServerTransportPlugin torrc line, unless the pluggable transport is running in “managed” mode.)
arguments (dict) –
Some PTs can take additional arguments, which must be distributed to the client out-of-band. These are present in the @type bridge-extrainfo-document, in the transport line like so:
```
METHOD SP ADDR ":" PORT SP [K=V[,K=V[,K=V[…]]]]
```
where K is the key in arguments, and V is the value. For example, in the case of scramblesuit, for which the client must supply a shared secret to the scramblesuit instance running on the bridge, the arguments would be something like:
```
{'password': 'NEQGQYLUMUQGK5TFOJ4XI2DJNZTS4LRO'}
```

Create a PluggableTransport describing a PT running on a bridge.

Parameters:

Parameters:	fingerprint (str) – The uppercased, hexadecimal fingerprint of the identity key of the parent bridge running this pluggable transport. methodname (str) – The canonical “name” for this pluggable transport. See `methodname`. address (str) – The IP address of the transport. See `address`. port (int) – A integer specifying the port which this pluggable transport is listening on. arguments (dict) – Any additional arguments which the PT takes, which must be distributed to the client out-of-band. See `arguments`.

fingerprint (str) – The uppercased, hexadecimal fingerprint of the identity key of the parent bridge running this pluggable transport.
methodname (str) – The canonical “name” for this pluggable transport. See methodname.
address (str) – The IP address of the transport. See address.
port (int) – A integer specifying the port which this pluggable transport is listening on.
arguments (dict) – Any additional arguments which the PT takes, which must be distributed to the client out-of-band. See arguments.

_parseArgumentsIntoDict(argumentList)[source]¶

Convert a list of Pluggable Transport arguments into a dictionary suitable for arguments.

Parameters:	argumentList (list) – A list of Pluggable Transport arguments. There might be multiple, comma-separated `K=V` Pluggable Transport arguments in a single item in the argumentList, or each item might be its own `K=V`; we don’t care and we should be able to parse it either way.
Return type:	dict
Returns:	A dictionary of all the `K=V` Pluggable Transport arguments.

_runChecks()[source]¶

Validate that we were initialised with acceptable parameters.

We currently check that:

The port is an integer, and that it is between the values of 0 and 65535 (inclusive).
The arguments is a dictionary.
The arguments do not contain non-ASCII or control characters or double quotes or backslashes, in keys or in values.

Raises MalformedPluggableTransport:
	if any of the above checks fails.

_checkArguments()[source]¶: This method is a temporary fix for PTs with missing arguments (see ticket #13202).

methodname¶

Get this PluggableTransport‘s methodname.

Return type:	str
Returns:	The (lowercased) methodname of this `PluggableTransport`, i.e. `"obfs3"`, `"scramblesuit"`, etc.

getTransportLine(includeFingerprint=True, bridgePrefix=False)[source]¶

Get a Bridge Line for this PluggableTransport.

Note

If bridgePrefix is False, this method does not return lines which are prefixed with the word 'bridge', as they would be in a torrc file. Instead, lines returned look like:

obfs3 245.102.100.252:23619 59ca743e89b508e16b8c7c6d2290efdfd14eea98

This was made configurable to fix Vidalia being a brain-damaged piece of shit (ticket #5851). TorLaucher replaced Vidalia soon after, and TorLauncher is intelligent enough to understand :term:`Bridge Line`s regardless of whether or not they are prefixed with the word “Bridge”.

Parameters:	includeFingerprints (bool) – If `True`, include the digest of this bridges public identity key in the torrc line. bridgePrefix (bool) – If `True`, add `'Bridge '` to the beginning of each returned line (suitable for pasting directly into a `torrc` file).
Return type:	str
Returns:	A configuration line for adding this Pluggable Transport into a `torrc` file.

updateFromStemTransport(fingerprint, methodname, kitchenSink)[source]¶

Update this PluggableTransport from the data structure which Stem uses.

Stem’s stem.descriptor.extrainfo_descriptor.BridgeExtraInfoDescriptor parses extrainfo transport lines into a dictionary with the following structure:

{u'obfs2': (u'34.230.223.87', 37339, []),
 u'obfs3': (u'34.230.223.87', 37338, []),
 u'obfs4': (u'34.230.223.87', 37341, [
     (u'iat-mode=0,'
      u'node-id=2a79f14120945873482b7823caabe2fcde848722,'
      u'public-key=0a5b046d07f6f971b7776de682f57c5b9cdc8fa060db7ef59de82e721c8098f4')]),
 u'scramblesuit': (u'34.230.223.87', 37340, [
     u'password=ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'])}

This method will initialise this class from the dictionary key (methodname) and its tuple of values (kitchenSink).

Parameters:	fingerprint (str) – The uppercased, hexadecimal fingerprint of the identity key of the parent bridge running this pluggable transport. methodname (str) – The `methodname` of this Pluggable Transport. kitchenSink (tuple) – Everything else that was on the `transport` line in the bridge’s extrainfo descriptor, which Stem puts into the 3-tuples shown in the example above.

class BridgeBase[source]¶

Bases: bridgedb.bridges.BridgeAddressBase

The base class for all bridge implementations.

nickname¶

Get this Bridge’s nickname.

Return type:	str
Returns:	The Bridge’s nickname.

orPort¶

Get this bridge’s ORPort.

Return type:	int
Returns:	This Bridge’s default ORPort.

class BridgeBackwardsCompatibility(nickname=None, ip=None, orport=None, fingerprint=None, id_digest=None, or_addresses=None)[source]¶

Bases: bridgedb.bridges.BridgeBase

Backwards compatibility methods for the old Bridge class.

Create a Bridge which is backwards compatible with the legacy Bridge class implementation.

_backwardsCompatible(nickname=None, address=None, orPort=None, fingerprint=None, idDigest=None, orAddresses=None)[source]¶: Functionality for maintaining backwards compatibility with the older version of this class (see bridgedb.test.deprecated.Bridge).

getID()[source]¶

Get the binary encoded form of this Bridge‘s fingerprint.