A prototyping library for peer-to-peer apps using Tor and Tor hidden services for connectivity. PTP is a library for Java only. Interoperability with applications not using PTP is not planned.
Good starting points:
- The Wiki
- javadoc (see Javadoc)
- the examples, especially
- the JUnit tests, especially
How to build
PTP uses the gradle build system.
./gradlew assemble to compile the code.
If you want to use eclipse run
./gradlew eclipse to create proper
./gradlew javadoc to create the Javadoc in
Adding PTP to a Gradle (Maven) project
Releases of PTP can be found on Bintray. PTP is included in jcenter.
compile 'edu.kit.tm.ptp:ptp:v0.4.1' to your build.gradle file to use PTP in a gradle project.
Adding PTP to a Java Application
To use PTP in your Java application build PTP and add
build/libs/PTP-full.jar to your classpath.
javac -cp .:pathtojar/PTP-full.jar ... and
java -cp .:pathtojar/PTP-full.jar ...
where pathtojar is the path to the folder containing PTP-full.jar.
To be able to use PTP you also have to copy the
config folder to the folder from where you run your application.
First a new PTP object has to be constructed:
PTP ptp = new PTP();.
After that you should register all classes you want to be able to send and receive using
Notice that the order of registrations is important and has to be the same both at the sender and receiver.
Also note that classes referenced by a registered class (e.g. in instance variables) should also be registered themselves. Following classes are exceptions to this rule:
int, String, float, boolean, byte, char, short, long, double, byte.
PTP uses Kryo to serialize objects.
You can set listeners for sent and received messages.
Please notice that executing long-running operations in a listener impacts
the overall performance of PTP and should be avoided.
ptp.init() should be called which sets up PTP and starts Tor.
ptp.createHiddenService() to use an existing hidden service or create a new one.
You can now send and receive messages. Keep in mind that it can take some time for a hidden service to be reachable (about 1-2 minutes).
ptp.sendMessage() allows to send
byte messages and objects of previously registered classes.
It is safe to call the method from several threads in parallel.
It also allows to pass a timeout in milliseconds which defaults to infinity.
If the timeout expires before the message was sent successfully the send listener gets informed.
Keep in mind that the service PTP provides is not reliable.
A listener might be informed that a message was sent even though the receiver never gets the message.
To close PTP cleanly call
ptp.exit(). If you want to delete your hidden service you can call
./gradlew test to run the tests.
You can also set up your own tor network for testing purposes and run the tests there.
For this to work you need chutney (https://git.torproject.org/chutney.git).
Set the location of chutney in the variable
CHUTNEY_DIR in chutneyTests.sh.
./chutneyTests.sh to set up a local tor network and start the tests.
Find more information in our Wiki.
Projects using PTP
PTP is licensed under the GNU General Public License (GPL) v3. See LICENSE.txt.