Struct Context

pub struct Context { /* private fields */ }

The gosling protocol implementation.

The Context object provides various methods for starting and progressing identity and endpoint handshakes. The general usage pattern developers will follow is to construct a Context object, connect to the Tor Network using Context::bootstrap(), optionally start an identity or endpoint servers, and listen for and handle incoming identity and endpoint clients using Context::update() and the various associated methods. Depending on the application’s requirements, the developer can also initiate identity and endpoint handshakes as necessary.

The Gosling Protocol specification can be found here:

• https://gosling.technology/gosling-spec.xhtml

Implementations

impl Context

pub fn new( tor_provider: Box<dyn TorProvider>, identity_port: u16, endpoint_port: u16, identity_timeout: Duration, identity_max_message_size: i32, endpoint_timeout: Option<Duration>, identity_private_key: Ed25519PrivateKey, ) -> Result<Self, Error>

Construct a new Context object.

Parameters

• tor_provider: an implementation of the TorProvider trait which provides our Tor Network connectivity
• identity_port: the virt-port this Context’s identity server’s onion-service will listen on for new identity handshakes.
• endpoint_port: the virt-port this Context‘s endpoint servers’ onion-services will listen on for new endpoint handshakes.
• identity_timeout: the maximum amount of time this Context’ will allow an identity handshake to delay between steps before rejecting the request.
• identity_max_message_size: the maximum size of the underlying Honk-RPC BSON message this Context’s identity handshake will send and accept.
• endpoint_timeout: the maximum amount of time this Context’ will allow an endpoint handshake to delay between steps before rejecting the request.
• identity_private_key: the ed25519 private key used to start this Context’s identity server’s onion-service

Returns

A newly constructed Context.

pub fn bootstrap(&mut self) -> Result<(), Error>

Initiate bootstrap of the Context’s owned TorProvider. Bootstrap status is communicated through ContextEvents returned from the Context::update() method.

pub fn identity_client_begin_handshake( &mut self, identity_server_id: V3OnionServiceId, endpoint: String, ) -> Result<HandshakeHandle, Error>

Initiate an identity handshake with an identity server. Handshake progression is communicated through ContextEvents returned from the Context::update() method.

Parameters

• identitity_server_id: the long term identity onion-service service-id of a remote peer
• endpoint: the ASCII-encoded requested endpoint

Returns

A HandshakeHandle used to refer to this particular identity handshake.

pub fn identity_client_abort_handshake( &mut self, handle: HandshakeHandle, ) -> Result<(), Error>

Abort an in-process outgoing identity handshake.

Parameters

• handle: the handle of the in-progress outoing identity handshake to abort

pub fn identity_client_handle_challenge_received( &mut self, handle: HandshakeHandle, challenge_response: Document, ) -> Result<(), Error>

Handle an identity server’s endpoint challenge. Callers must construct an identity client’s endpoint challenge-response. The particulars of creating and verifying the challenge-response BSON documents are undefined and application-specific.

Parameters

• handle: the handle of the in-progress outgoing identity handshake
• challenge_response: an application-specific BSON document which somehow responds to an identity server’s challenge.

pub fn identity_server_start(&mut self) -> Result<(), Error>

Start this Context’s identity server. Publish status is communicated through ContextEvents returned from the Context::update() method.

pub fn identity_server_stop(&mut self) -> Result<(), Error>

Stops this Context’s identity server and ends any in-progress incoming identity handshakes.

pub fn identity_server_handle_endpoint_request_received( &mut self, handle: HandshakeHandle, client_allowed: bool, endpoint_supported: bool, endpoint_challenge: Document, ) -> Result<(), Error>

Handle an identity client’s incoming endpoint request. Callers must determine whether the connected identity client is allowed to access the requested endpoint, decide whether the requested endpoint is supported by this Context, and build an endpoint challenge for the identity client. The particulars of creating the endpoint challenge is undefined and application-specific.

Parameters

• handle: the handle of the in-progress incoming identity handshake
• client_allowed: whether the connected identity client is allowed to access the requested endpoint
• endpoint_supported: whether the requested endpoint is supported
• endpoint_challenge: an application-specific BSON document which the connected identity client must respond to

pub fn identity_server_handle_challenge_response_received( &mut self, handle: HandshakeHandle, challenge_response_valid: bool, ) -> Result<(), Error>

Handle an identity client’s incoming endpoint challenge-response. Callers must determine whether the connected identity client’s challenge-response is valid. The particulars of verifying the challenge-response is undefined and application-specific.

Parameters

• handle: the handle of the in-progress incoming identity handshake
• challenge_response_valid: whether the received challenge-response is valid

pub fn endpoint_client_begin_handshake( &mut self, endpoint_server_id: V3OnionServiceId, client_auth_key: X25519PrivateKey, channel: String, ) -> Result<HandshakeHandle, Error>

Initiate an endpoint handshake with an identity server. An endpoint client acquires the endpoint_server_id and client_auth_key by completing an identity handshake or through some other side-channnel. Handshake progression is communicated through ContextEvents returned from the Context::update() method.

Parameters

• endpoint_server_id: the endpoint onion-service service-id of a remote peer
• client_uath_key: the x25519 private-key required to decrypt the endpoint server’s onion-service descriptor
• channel: the ASCII-encoded requested channel

pub fn endpoint_client_abort_handshake( &mut self, handle: HandshakeHandle, ) -> Result<(), Error>

Abort an in-process outgoing endpoint handshake

Parameters

• handle: the handle of the in-progress outoing identity handshake to abort

pub fn endpoint_server_start( &mut self, endpoint_private_key: Ed25519PrivateKey, endpoint_name: String, client_identity: V3OnionServiceId, client_auth: X25519PublicKey, ) -> Result<(), Error>

Start one of this Context’s endpoint servers. Publish status is communicated through ContextEvents returned from the Context::update() method.

Parameters

• endpoint_private_key: the ed25519 private key used to start this endpoint server’s onion-service
• endpoint_name: the ASCII-encoded endpoint name
• client_identity: the onion-service service-id of the client which will be connecting to this endpoint server
• client_auth: the x25519 public-key used to encrypt the endpoint server’s onion-service descriptor

pub fn endpoint_server_handle_channel_request_received( &mut self, handle: HandshakeHandle, channel_supported: bool, ) -> Result<(), Error>

Handle an endpoint client’s incoming channel request. Callers must determine whether the requested channel is supported by this Context. The particulars of making this determination is undefined and application-specific.

Parameters

• handle: the handle of the in-progress incoming endpoint handshake
• channel_supported: whether the requested channel is supported

pub fn endpoint_server_stop( &mut self, endpoint_identity: V3OnionServiceId, ) -> Result<(), Error>

Stop one of this Context’s endpoint servers and ends any of its in-progress incoming endpoint handshakes.

Parameters

• endpoint_identity: the onion-service service-id of the enpdoint server to stop

pub fn connect( &mut self, target_addr: TargetAddr, circuit_token: Option<CircuitToken>, ) -> Result<OnionStream, Error>

A direct pass-through to the underlying TorProvider’s TorProvider::connect() method.

pub fn generate_circuit_token(&mut self) -> CircuitToken

A direct pass-through to the underlying TorProvider’s TorProvider::generate_token() method.

pub fn release_circuit_token(&mut self, circuit_token: CircuitToken)

A direct pass-through to the underlying TorProvider’s TorProvider::release_token() method.

pub fn update(&mut self) -> Result<VecDeque<ContextEvent>, Error>

This function updates the Context’s underlying TorProvider, handles new handshakes requests, and updates in-progress handshakes. This function needs to be regularly called to process the returned ContextEvents.