Features

Features

PTP is more than a wrapper around Tor. This page describes the features provided by PTP.

Asynchronous messaging and connection management

The API of PTP allows to hand messages to PTP, which get delivered as soon as a connection to the destination could be established. Application programmer don't have to deal with establishing connections to other hidden services themselves.

Authentication

When PTP connects to another instance it first has to authenticate itself. Otherwise PTP wouldn't know the hidden service identifier of the remote end of an incoming connection. PTP does this by sending an authentication message with the following format:

 class AuthenticationMessage {
    Identifier source;
    Identifier destination;
    byte[] publicKey;
    long timestamp;
    byte[] signature;
}

• source: hidden service identifier of the sender of the authentication message
• destination: hidden service identifier of the receiver
• publicKey: RSA public key of the sender's hidden service
• timestamp: current time in milliseconds since January 1, 1970 UTC
• signature: signature with the private key of the sender's hidden service. The signature includes source, destination, publicKey and timestamp. Uses an RSA signature with SHA256 and PKCS #1 v1.5 padding.

An authentication message is valid if the following requirements are met:

• The publicKey has to correspond to the source hidden service identifier. (See rend-spec.txt on how the hidden service identifier is calculated from the public key.)
• The timestamp doesn't deviate more than 3 minutes from the current time (as well in the past as in the future)
• The signature can be verified by using the publicKey.
• The destination identifier equals the receivers hidden service identifier.

If an authentication message is valid, the receiver of the message answers with a OK message to confirm the successful authentication and drops the connection otherwise.

Mobility

IsAlive messages

PTP provides a mechanism to detect a broken connection to another hidden service. A connection can break when the device at the other end changes it's ip address. Tor only realizes that the circuit is broken when the TCP connection to the old introduction point times out (which can take up to 20 minutes). The problem has been described at #16387. Because this is bad for the reachability of mobile devices, PTP implements the following mechanism:

Every message sent by PTP to another instance has to be answered with an arbitrary message at most 60 seconds later. If PTP has no regular message to send, it can send an IsAlive message which is empty. If the other instance doesn't answer in time, PTP instructs Tor to close the underlying circuit. This allows a mobile device which changes it's network frequently to be reachable again in a short amount of time.

Another approach is taken by Briar, which is described here #18620. They suggest to add a new HSFORGET command to the Tor control protocol, which allows to clear cached state of a specific hidden service. Until now the patch for Tor hasn't been approved. Our solution also works with an unpatched Tor binary.

Network connectivity

Another problem can occur when a device has no network connection at all for some time. It's possible that Tor concludes by mistake that the introduction points of the hidden service are down. The problem has been described in more detail at #19522. To avoid that, PTP checks for connectivity changes on Android and sets the Tor option DisableNetwork respectively. This prevents Tor from trying to connect to the introduction points when there is no connectivity.

Serialization

The PTP API allows to send and receive instances of Java classes. This is made possible by serializing and deserializing them with Kryo.