# SNOCAT
_Streaming Network Overlay Connection Arbitration Tunnel_
[](https://crates.io/crates/snocat)
[](https://docs.rs/snocat)
[](LICENSE-MIT)
[](LICENSE-APACHE)
[`snocat`](https://crates.io/crates/snocat) is a framework for forwarding
streams across authenticated, encrypted [QUIC](https://quicwg.org/) tunnels,
from a tunnel aggregator to a dynamic set of clients.
Unlike VPNs, which scale vertically with the number of users
connected to one network, `snocat` is intended to scale horizontally
on the number of networks, allowing dynamic provisioning and selection
of target networks, with a small number of concurrent users per target.
## Usage
> :warning: _This library is under active development, and its API and protocol are extremely unstable_
`libsnocat` allows creation of custom [server](#Custom-Server) and
[client](#Custom-Client) applications atop the `snocat` protocol.
This allows for greater configurability and extensibility
than is possible through `snocat-cli`.
### Custom Server
To create a server:
- Create a `quinn` listen endpoint, referred to as its `driver`
- Implement a `TunnelManager`
- It doesn't have to be TCP, you can forward whatever you'd like!
- Implement an [AuthenticationHandler](#Authentication-Layer)
- Implement a [Router](#Routing-Layer)
- Instantiate a `TunnelServer` atop your manager
- Due to the complexity in writing a `TunnelServer` without lifetime or parallelism issues,
we include a fully asynchronous, stream-oriented implementation,
[`ConcurrentDeferredTunnelServer`](src/server/deferred.rs),
but you can build your own if needed.
- Forward connections to your server, and await graceful shutdown
Server lifecycle is stream oriented, using a monadic flow from
incoming connections to connection event outputs.
`Sync` trait-objects act as dispatchers to various functionality,
relying on interior mutability for any state updates within the dispatch handlers.
### Custom Client
To create a client:
- Create a `quinn` connection to your server's `driver`
- Implement an [`AuthenticationClient`](#Authentication-Layer)
- Implement a [`RoutingClient`](#Routing-Layer)
- Forward connections from the connection to your `RoutingClient`,
and await graceful shutdown or `quinn::endpoint::Endpoint::wait_idle`.
### Authentication Layer
Authentication is handled by implementing the client and server portions of an Authenticator.
The `AuthenticationHandler` trait performs server-side authentication,
while a matching `AuthenticationClient` trait is invoked by the client.
There are plans to allow "by name" dispatch to authenticators in the future,
allowing multiple to be registered with a server or client, so clients and
servers can negotiate a compatible authentication method.
Authentication provides a single, reliable-ordered bidirectional stream,
and either side may close the channel at any time to abort authentication.
### Routing Layer
`Routing` is a term used to describe client handling of a server-provided stream,
or server handling of a client-provided stream.
A Router receives a stream header and a routing identifier.
If a router does not recognize the type identity of the stream header,
it can refuse the stream, which leaves the providing side responsible
for stream closure.
Streams are bidirectional, and a canonical example is `snocat-cli`'s TCP streaming,
which takes a target port and forwards the stream to `localhost` at that port via TCP.
### Protocol
Details of the protocol will be published in [docs/Protocol.md] when it is stabilized.
---
## Development
For debug usage, `SSLKEYLOGFILE` and `RUST_LOG` parameters are supported.
`SSLKEYLOGFILE` allows interception with [Wireshark](https://www.wireshark.org/)
TLS Decryption and QUIC dissection.
For example usage, `snocat-cli` debugging is often performed with a command-line such as the following:
```sh
SSLKEYLOGFILE=~/keylog.ssl.txt RUST_LOG="trace,quinn=warn,quinn_proto=warn" \
cargo run -- client --authority $SERVER_CERT \
--driver localhost:9090 \
--target $TARGET \
--san localhost
```
See [CONTRIBUTING.md](../CONTRIBUTING.md) in the official project
repository for further development and contribution guidance.
---
## Third-Party Dependencies
Primary crates used include the [Tokio stack](https://tokio.rs/) and
[futures-rs](https://rust-lang.github.io/futures-rs/) for async-await capabilities,
[Quinn](https://github.com/quinn-rs/quinn) for its [QUIC](https://quicwg.org/)
implementation.
Various other dependencies are included under their respective licenses,
and may be found in [Cargo.toml](Cargo.toml).
Notable exceptions from _MIT_ or _MIT OR Apache 2.0_ licensing in dependencies are the following crates:
- `ring` for TLS, distributed under a BoringSSL-variant, _ISC-style_ permissive license
- `untrusted` required by `ring` for parsing of TLS, distributed under an _ISC-style_ permissive license
- `webpki` for TLS WebPKI certificate handling, distributed under an _ISC-style_ permissive license
- `memchr`, `byteorder`, `regex-automata` are licensed under _Unlicense OR MIT_
- `prost`, `prost-types`, `prost-derive`, and `prost-build`, licensed solely under the _Apache-2.0_ license
- `ryu` required by `serde_json` for floating point parsing from json, licensed under _Apache-2.0_ OR _BSL-1.0_
See [NOTICE.md](NOTICE.md) for license details of individual crates,
and links to their project webpages.
## Trademarks
This project may contain trademarks or logos for projects, products, or services.
Authorized use of Microsoft trademarks or logos is subject to and must follow
[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
Use of Microsoft trademarks or logos in modified versions of this project must not
cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks
or logos are subject to those third-party's policies.
## Code of Conduct
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
## License
Copyright (c) Microsoft Corporation. All rights reserved.
Licensed under either of
- Apache License, Version 2.0
([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license
([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
## Contribution
Under the Contributor License Agreement, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.