txi2p

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