This repository has been archived in favor of a newer iteration of the ptrs interface

Pluggable Transports in Rust (PTRS) ARCHIVED

PTRS is a library for writing pluggable transports in Rust.

Library Usage

This library (currently) revolves around the abstraction of connections as anything that implement the traits [tokio::io:AsyncRead] + [tokio::io::AsyncRead] + Unpin + Send + Sync. This allows us to define the expected shared behavior of pluggable transports as a transform of these [Stream]s.

use ptrs::Result;
use tokio::io::{AsyncRead,AsyncWrite};

pub trait StreamTransport<'a, A>
where
    A: AsyncRead + AsyncWrite + Unpin + Send + Sync + 'a,
{
    fn wrap(&self, a: A) -> Result<Box<dyn Stream + 'a>>;
}

Integrating ptrs Transports

Given this abstraction integrating transports into async rust applications becomes relatively straightforward, for example, integrating the identity transport (which performs a direct copy with no actual transform) could be done similar to:

use ptrs::{stream::Stream, StreamTransport, transports::identity};
use tokio::net::TcpListener;

async fn process_socket<'s,S: Stream+'s>(stream: S) {
    // ...
}

#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:8080").await?;
    let transport = identity::Identity::new();

    loop {
        let (tcp_socket, _) = listener.accept().await?;
        let socket = transport.wrap(socket)?;
        process_socket(socket).await;
    }
    Ok(())
}

Integration on the client side is similarly straightforward.

use ptrs::{StreamTransport, transports::identity};
use tokio::net::TcpStream;
use tokio::io::AsyncWriteExt;
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let transport = identity::new();
    let mut tcp_stream = TcpStream::connect("127.0.0.1:8080").await?;
    let mut stream = transport.wrap(tcp_stream)?;

    stream.write_all(b"hello world!").await?;
    stream.read(&mut [0; 128]).await?;
    Ok(())
} // the stream is closed here

Configuration & State

The trait [Configurable] provides a way that transports can be provided a configuration as an &str which they can parse and apply to the individual tunnels that are launched.

Composition

Because the ptrs interface wraps objects implementing connection oriented traits and and returns trait objects implementing the same abstraction is is possible to wrap multiple transports on top of one another. One reason to do this might be to have separate reliability, obfuscation and padding strategies that can be composed interchangeably.

todo!()

Implementing a Transport

There are several constructions that can be used to build up a pluggable transport, in part this is because no individual construction has proven demonstrably better than the others. However, this demonstrates the flexibility of the high level ptrs trait.

Buffer Transform

todo!()

Read / Wrap Oriented

todo!()

Copy Based

todo!()

Example CLI

An example client / server using the ptrs pluggable transport library implementing a transparent proxy can be found in the src/bin/proxy directory. More information about the proof-of-concept proxy binary can be found in the src/bin/proxy/README.md. To build the proxy specifically use:

cargo build --bin proxy [--release]

Notes / Resources

While this is related to and motivated by the Tor pluggable transport system, the primary concern of this repository is creating a consistent and useful abstraction for building pluggable transports. For more information about Tor related pluggable transports see the following resources.

Open Source License

Dual licensing under both MIT and Apache-2.0 is the currently accepted standard by the Rust language community and has been used for both the compiler and many public libraries since (see Why dual MIT/ASL2license?). In order to match the community standards, ptrs is using the dual MIT+Apache-2.0 license.

Contributing

Contributors, Issues, and Pull Requests are Welcome

jmwample / ptrs_orig

readme