From cb81b2c4c81dd4b5ee606569b5109358c3b49d26 Mon Sep 17 00:00:00 2001 From: EAimTY Date: Mon, 22 May 2023 03:14:02 +0900 Subject: [PATCH] README.md on server & client --- README.md | 6 +- tuic-client/README.md | 133 ++++++++++++++++++++++++++++++++++++++++++ tuic-quinn/src/lib.rs | 2 +- tuic-server/README.md | 100 +++++++++++++++++++++++++++++++ 4 files changed, 237 insertions(+), 4 deletions(-) create mode 100644 tuic-client/README.md create mode 100644 tuic-server/README.md diff --git a/README.md b/README.md index 75aa5bb..23290a9 100644 --- a/README.md +++ b/README.md @@ -29,9 +29,9 @@ When paired with QUIC, TUIC can achieve: There are 4 crates provided in this repository: - **[tuic](https://github.com/EAimTY/tuic/tree/dev/tuic)** - Library. The protocol itself, protocol & model abstraction, synchronous / asynchronous marshalling -- **[tuic-quinn](https://github.com/EAimTY/tuic/tree/dev/tuic-quinn)** - Library. A thin layer on top of [quinn](https://github.com/quinn-rs/quinn) to provide functions for TUIC -- **[tuic-server](https://github.com/EAimTY/tuic/tree/dev/tuic-server)** - Binary. Minimalistic TUIC server implementation as a reference, focusing on the simplicity -- **[tuic-client](https://github.com/EAimTY/tuic/tree/dev/tuic-client)** - Binary. Minimalistic TUIC client implementation as a reference, focusing on the simplicity +- **[tuic-quinn](https://github.com/EAimTY/tuic/tree/dev/tuic-quinn)** - Library. A thin layer on top of [quinn](https://github.com/quinn-rs/quinn) to provide functions of TUIC +- **[tuic-server](https://github.com/EAimTY/tuic/tree/dev/tuic-server)** - Binary. Minimalistic TUIC server implementation as a reference +- **[tuic-client](https://github.com/EAimTY/tuic/tree/dev/tuic-client)** - Binary. Minimalistic TUIC client implementation as a reference ## License diff --git a/tuic-client/README.md b/tuic-client/README.md new file mode 100644 index 0000000..49345a2 --- /dev/null +++ b/tuic-client/README.md @@ -0,0 +1,133 @@ +# tuic-client + +Minimalistic TUIC client implementation as a reference + +[![Version](https://img.shields.io/crates/v/tuic-client.svg?style=flat)](https://crates.io/crates/tuic-client) +[![License](https://img.shields.io/crates/l/tuic-client.svg?style=flat)](https://github.com/EAimTY/tuic/blob/dev/LICENSE) + +## Usage + +Download the latest binary from [releases](https://github.com/EAimTY/tuic/releases). + +Or install from [crates.io](https://crates.io/crates/tuic-client): + +```bash +cargo install tuic-client +``` + +Run the TUIC client with configuration file: + +```bash +tuic-client -c PATH/TO/CONFIG +``` + +## Configuration + +```json +{ + // Settings for the outbound TUIC proxy + "relay": { + // Set the TUIC proxy server address + // Format: "HOST:PORT" + // The HOST must be a common name in the certificate + // If the "ip" field in the "relay" section is not set, the HOST is also used for DNS resolving + "server": "example.com:443", + + // Set the user UUID + "uuid": "00000000-0000-0000-0000-000000000000", + + // Set the user password + "password": "PASSWORD", + + // Optional. The IP address of the TUIC proxy server, for overriding DNS resolving + // If not set, the HOST in the "server" field is used for DNS resolving + "ip": "127.0.0.1", + + // Optional. A list of certificates for TLS handshake + // System native certificates are also loaded by default + // When using self-signed certificates, the full certificate chain must be provided + "certificates": ["PATH/TO/CERTIFICATE_1", "PATH/TO/CERTIFICATE_2"], + + // Optional. Set the UDP packet relay mode + // Can be: + // - "native": native UDP characteristics + // - "quic": lossless UDP relay using QUIC streams, additional overhead is introduced + // Default: "native" + "udp_relay_mode": "native", + + // Optional. Congestion control algorithm, available options: + // "cubic", "new_reno", "bbr" + // Default: "cubic" + "congestion_control": "cubic", + + // Optional. Application layer protocol negotiation + // Default being empty (no ALPN) + "alpn": ["h3", "spdy/3.1"], + + // Optional. Enable 0-RTT QUIC connection handshake on the client side + // This is not impacting much on the performance, as the protocol is fully multiplexed + // WARNING: Disabling this is highly recommended, as it is vulnerable to replay attacks. See https://blog.cloudflare.com/even-faster-connection-establishment-with-quic-0-rtt-resumption/#attack-of-the-clones + // Default: false + "zero_rtt_handshake": false, + + // Optional. Disable SNI (Server Name Indication) in TLS handshake + // The server name used in SNI is the same as the HOST in the "server" field + // Default: false + "disable_sni": false, + + // Optional. Set the timeout for establishing a connection to the TUIC proxy server + // Default: "8s" + "timeout": "8s", + + // Optional. Set the interval for sending heartbeat packets for keeping the connection alive + // Default: "3s" + "heartbeat": "3s", + + // Optional. Disable loading system native certificates + // Default: false + "disable_native_certs": false, + + // Optional. Interval between UDP packet fragment garbage collection + // Default: 3s + "gc_interval": "3s", + + // Optional. How long the server should keep a UDP packet fragment. Outdated fragments will be dropped + // Default: 15s + "gc_lifetime": "15s" + }, + + // Settings for the local inbound socks5 server + "local": { + // Local socks5 server address + "server": "[::]:1080", + + // Optional. Set the username for socks5 authentication + "username": "USERNAME", + + // Optional. Set the password for socks5 authentication + "password": "PASSWORD", + + // Optional. Set if the listening socket should be dual-stack + // If this option is not set, the socket behavior is platform dependent + "dual_stack": true, + + // Optional. Maximum packet size the socks5 server can receive from external, in bytes + // Default: 1500 + "max_packet_size": 1500 + }, + + // Optional. Set the log level + // Default: "warn" + "log_level": "warn" +} +``` + +## Opinions on Advanced Features + +This TUIC client implementation is intended to be minimalistic. It is mainly used as a reference and verification of the TUIC protocol specification. + +This implementation only contains the most basic requirements of a functional TUIC protocol client. It does not includes any advanced features, such as outbound control, obfuscation, etc. If you want them, try other implementations, or implement them yourself. + +## License + +GNU General Public License v3.0 diff --git a/tuic-quinn/src/lib.rs b/tuic-quinn/src/lib.rs index 15f8c86..e482eca 100644 --- a/tuic-quinn/src/lib.rs +++ b/tuic-quinn/src/lib.rs @@ -133,7 +133,7 @@ impl Connection { let mut send = self.conn.open_uni().await?; model.header().async_marshal(&mut send).await?; - send.close().await?; // stuck here + send.close().await?; Ok(()) } diff --git a/tuic-server/README.md b/tuic-server/README.md new file mode 100644 index 0000000..5e6a1e3 --- /dev/null +++ b/tuic-server/README.md @@ -0,0 +1,100 @@ +# tuic-server + +Minimalistic TUIC server implementation as a reference + +[![Version](https://img.shields.io/crates/v/tuic-server.svg?style=flat)](https://crates.io/crates/tuic-server) +[![License](https://img.shields.io/crates/l/tuic-server.svg?style=flat)](https://github.com/EAimTY/tuic/blob/dev/LICENSE) + +## Usage + +Download the latest binary from [releases](https://github.com/EAimTY/tuic/releases). + +Or install from [crates.io](https://crates.io/crates/tuic-server): + +```bash +cargo install tuic-server +``` + +Run the TUIC server with configuration file: + +```bash +tuic-server -c PATH/TO/CONFIG +``` + +## Configuration + +```json +{ + // The socket address to listen on + "server": "[::]:443", + + // User list, contains user UUID and password + "users": { + "00000000-0000-0000-0000-000000000000": "PASSWORD_0", + "00000000-0000-0000-0000-000000000001": "PASSWORD_1" + }, + + // The path to the certificate file + "certificate": "PATH/TO/CERTIFICATE", + + // The path to the private key file + "private_key": "PATH/TO/PRIVATE_KEY", + + // Optional. Congestion control algorithm, available options: + // "cubic", "new_reno", "bbr" + // Default: "cubic" + "congestion_control": "cubic", + + // Optional. Application layer protocol negotiation + // Default being empty (no ALPN) + "alpn": ["h3", "spdy/3.1"], + + // Optional. If the server should create separate UDP sockets for relaying IPv6 UDP packets + // Default: true + "udp_relay_ipv6": true, + + // Optional. Enable 0-RTT QUIC connection handshake on the server side + // This is not impacting much on the performance, as the protocol is fully multiplexed + // WARNING: Disabling this is highly recommended, as it is vulnerable to replay attacks. See https://blog.cloudflare.com/even-faster-connection-establishment-with-quic-0-rtt-resumption/#attack-of-the-clones + // Default: false + "zero_rtt_handshake": false, + + // Optional. Set if the listening socket should be dual-stack + // If this option is not set, the socket behavior is platform dependent + "dual_stack": true, + + // Optional. How long the server should wait for the client to send the authentication command + // Default: 3s + "auth_timeout": "3s", + + // Optional. How long the server should wait before closing an idle connection + // Default: 10s + "max_idle_time": "10s", + + // Optional. Maximum packet size the server can receive from outbound UDP sockets, in bytes + // Default: 1500 + "max_external_packet_size": 1500, + + // Optional. Interval between UDP packet fragment garbage collection + // Default: 3s + "gc_interval": "3s", + + // Optional. How long the server should keep a UDP packet fragment. Outdated fragments will be dropped + // Default: 15s + "gc_lifetime": "15s", + + // Optional. Set the log level + // Default: "warn" + "log_level": "warn" +} +``` + +## Opinions on Advanced Features + +This TUIC server implementation is intended to be minimalistic. It is mainly used as a reference and verification of the TUIC protocol specification. + +This implementation only contains the most basic requirements of a functional TUIC protocol server. It does not includes any advanced features, such as outbound control, obfuscation, etc. If you want them, try other implementations, or implement them yourself. + +## License + +GNU General Public License v3.0