I2P bindings for Twisted


Keywords
i2p, plugin, python, twisted, twisted-library
License
ISC
Install
pip install txi2p==0.3.2

Documentation

txi2p

travis coveralls

txi2p is a set of I2P bindings for Twisted 10.1 or greater. It currently requires Python 2.

txi2p will run on Python 3.3+ (requiring Twisted 15.4 or greater).

txi2p supports both the SAM and BOB APIs for I2P. The default API is SAM.

Installation

You can install txi2p from PyPI:

$ pip2 install txi2p

or by downloading the source and running:

$ pip2 install .

inside the source directory.

Quickstart

If you are not familiar with using endpoints or endpoint strings, read the Twisted endpoints documentation.

Using endpoint classes

To connect to an I2P site:

from twisted.internet import reactor
from twisted.internet.endpoints import clientFromString
from txi2p.sam import SAMI2PStreamClientEndpoint

samEndpoint = clientFromString(reactor, 'tcp:127.0.0.1:7656')
endpoint = SAMI2PStreamClientEndpoint.new(samEndpoint, 'stats.i2p')
d = endpoint.connect(factory)

To have a server listen on an I2P Destination:

from twisted.internet import reactor
from twisted.internet.endpoints import clientFromString
from txi2p.sam import SAMI2PStreamServerEndpoint

samEndpoint = clientFromString(reactor, 'tcp:127.0.0.1:7656')
endpoint = SAMI2PStreamServerEndpoint.new(samEndpoint, '/path/to/keyfile')
d = endpoint.listen(factory)

Using endpoint strings

Requires Twisted 14.0 or greater.

To connect to an I2P site:

from twisted.internet import reactor
from twisted.internet.endpoints import clientFromString

endpoint = clientFromString(reactor, 'i2p:stats.i2p')
d = endpoint.connect(factory)

To have a server listen on an I2P Destination:

from twisted.internet import reactor
from twisted.internet.endpoints import serverFromString

endpoint = serverFromString(reactor, 'i2p:/path/to/keyfile')
d = endpoint.listen(factory)

To connect using a specific API:

from twisted.internet import reactor
from twisted.internet.endpoints import clientFromString

endpoint = clientFromString(reactor, 'i2p:stats.i2p:api=BOB')
d = endpoint.connect(factory)

To connect using a non-standard API host or port:

from twisted.internet import reactor
from twisted.internet.endpoints import clientFromString

endpoint = clientFromString(reactor, 'i2p:stats.i2p:api=SAM:apiEndpoint=tcp\:127.0.0.1\:31337')
d = endpoint.connect(factory)

Endpoint strings

The Twisted plugin for clientFromString() and serverFromString() will only work for Twisted 14.0 or greater.

Both client and server strings support the following keyword arguments:

  • api=<apiName> - Either SAM or BOB.
  • apiEndpoint=<endpointString> - An escaped client endpoint string pointing to the API, e.g. tcp\:127.0.0.1\:2827.
  • options=keyOne\:valueOne,keyTwo\:valueTwo - I2CP options as a comma-separated key:value list. See the I2CP specification for available options.

Clients

Client string format:

i2p:<host>[:port][:key=value]*

Supported arguments:

SAM

  • nickname
  • autoClose
  • keyfile
  • localPort
  • sigType

BOB

  • tunnelNick
  • inhost
  • inport

Servers

Server string format:

i2p:<keyfile>[:port][:key=value]*

Supported arguments:

SAM

  • nickname
  • autoClose
  • sigType

BOB

  • tunnelNick
  • outhost
  • outport

Important changes

0.3.2

  • The default signature type for new Destinations is Ed25519.
    • If the SAM server does not support that (Java I2P 0.9.16 and earlier), txi2p will fall back on ECDSA_SHA256_P256, followed by the old default DSA_SHA1.

0.3

  • Ports are now supported on the SAM API.
    • Previous port options are no longer ignored.
    • New localPort option for setting the client's local port.
  • The SAMI2PStreamServerEndpoint API has changed to no longer require a reactor.

Documentation

API documentation is available at https://txi2p.readthedocs.org