docs: update docs for rustls (#337)

* Fix typos and update docs for rustls

* update description

* Remove placeholders in doc

README.md

@@ -55,7 +55,7 @@ Create `server.toml` with the following content and accommodate it to your needs
 bind_addr = "0.0.0.0:2333" # `2333` specifies the port that rathole listens for clients
 
 [server.services.my_nas_ssh]
-token = "use_a_secret_that_only_you_know" # Token that is used to authenticate the client for the service. Change to a arbitrary value.
+token = "use_a_secret_that_only_you_know" # Token that is used to authenticate the client for the service. Change to an arbitrary value.
 bind_addr = "0.0.0.0:5202" # `5202` specifies the port that exposes `my_nas_ssh` to the Internet
 ```
 

docs/build-guide.md

@@ -1,31 +1,54 @@
 # Build Guide
+
 This is for those who want to build `rathole` themselves, possibly because the need of latest features or the minimal binary size.
 
 ## Build
+
 To use default build settings, run:
-```
+
+```sh
 cargo build --release
 ```
+
 You may need to pre-install [openssl](https://docs.rs/openssl/latest/openssl/index.html) dependencies in Unix-like systems.
 
-## Customize the build
+## Customize the Build
+
 `rathole` comes with lots of *crate features* that determine whether a certain feature will be compiled or not. Supported features can be checked out in `[features]` of [Cargo.toml](../Cargo.toml).
 
 For example, to build `rathole` with the `client` and `noise` feature:
-```
+
+```sh
 cargo build --release --no-default-features --features client,noise
 ```
 
+## Rustls Support
+
+`rathole` provides optional `rustls` support. It's an almost drop-in replacement of `native-tls` support. (See [Transport](transport.md) for more information.)
+
+To enable this, disable the default features and enable `rustls` feature. And for websocket feature, enable `websocket-rustls` feature as well.
+
+You can also use command line option for this. For example, to replace all default features with `rustls`:
+
+```sh
+cargo build --release --no-default-features --features server,client,rustls,noise,websocket-rustls,hot-reload
+```
+
+Feature `rustls` and `websocket-rustls` cannot be enabled with `native-tls` and `websocket-native-tls` at the same time, as they are mutually exclusive. Enabling both will result in a compile error.
+
+(Note that default features contains `native-tls` and `websocket-native-tls`.)
+
 ## Minimalize the binary
 
 1. Build with the `minimal` profile
 
-The `release` build profile optimize for the program running time, not the binary size. 
+The `release` build profile optimize for the program running time, not the binary size.
 
 However, the `minimal` profile enables lots of optimization for the binary size to produce a much smaller binary.
 
 For example, to build `rathole` with `client` feature with the `minimal` profile:
-```
+
+```sh
 cargo build --profile minimal --no-default-features --features client
 ```
 
@@ -34,7 +57,8 @@ cargo build --profile minimal --no-default-features --features client
 The binary that step 1 produces can be even smaller, by using `strip` and `upx` to remove the symbols and compress the binary.
 
 Like:
-```
+
+```sh
 strip rathole
 upx --best --lzma rathole
 ```

docs/transport.md

@@ -3,21 +3,27 @@
 By default, `rathole` forwards traffic as it is. Different options can be enabled to secure the traffic.
 
 ## TLS
+
 Checkout the [example](../examples/tls)
+
 ### Client
+
 Normally, a self-signed certificate is used. In this case, the client needs to trust the CA. `trusted_root` is the path to the root CA's certificate PEM file.
 `hostname` is the hostname that the client used to validate aginst the certificate that the server presents. Note that it does not have to be the same with the `remote_addr` in `[client]`.
-```
+
+```toml
 [client.transport.tls]
 trusted_root = "example/tls/rootCA.crt"
 hostname = "localhost"
 ```
 
 ### Server
+
 PKCS#12 archives are needed to run the server.
 
 It can be created using openssl like:
-```
+
+```sh
 openssl pkcs12 -export -out identity.pfx -inkey server.key -in server.crt -certfile ca_chain_certs.crt
 ```
 
@@ -29,8 +35,22 @@ Aruguments are:
 
 Creating self-signed certificate with one's own CA is a non-trival task. However, a script is provided under tls example folder for reference.
 
+### Rustls Support
+
+`rathole` provides optional `rustls` support. [Build Guide](build-guide.md) demostrated this.
+
+One difference is that, the crate we use for loading PKCS#12 archives can only handle limited types of PBE algorithms. We only support PKCS#12 archives that they (crate `p12`) support. So we need to specify the legacy format (openssl 1.x format) when creating the PKCS#12 archive.
+
+In short, the command used with openssl 3 to create the PKCS#12 archive with `rustls` support is:
+
+```sh
+openssl pkcs12 -export -out identity.pfx -inkey server.key -in server.crt -certfile ca_chain_certs.crt -legacy
+```
+
 ## Noise Protocol
+
 ### Quickstart for the Noise Protocl
+
 In one word, the [Noise Protocol](http://noiseprotocol.org/noise.html) is a lightweigt, easy to configure and drop-in replacement of TLS. No need to create a self-sign certificate to secure the connection.
 
 `rathole` comes with a reasonable default configuration for noise protocol. You can a glimpse of the minimal [example](../examples/noise_nk) for how it will look like.
@@ -38,12 +58,14 @@ In one word, the [Noise Protocol](http://noiseprotocol.org/noise.html) is a ligh
 The default noise protocol that `rathole` uses, which is `Noise_NK_25519_ChaChaPoly_BLAKE2s`, providing the authentication of the server, just like TLS with properly configured certificates. So MITM is no more a problem.
 
 To use it, a X25519 keypair is needed.
+
 #### Generate a Keypair
 
 1. Run `rathole --genkey`, which will generate a keypair using the default X25519 algorithm.
 
 It emits:
-```
+
+```sh
 $ rathole --genkey
 Private Key:
 cQ/vwIqNPJZmuM/OikglzBo/+jlYGrOt9i0k5h5vn1Q=
@@ -51,11 +73,13 @@ cQ/vwIqNPJZmuM/OikglzBo/+jlYGrOt9i0k5h5vn1Q=
 Public Key:
 GQYTKSbWLBUSZiGfdWPSgek9yoOuaiwGD/GIX8Z1kkE=
 ```
+
 (WARNING: Don't use the keypair from the Internet, including this one)
 
 2. The server should keep the private key to identify itself. And the client should keep the public key, which is used to verify whether the peer is the authentic server.
 
 So relevant snippets of configuration are:
+
 ```toml
 # Client Side Configuration
 [client.transport]
@@ -73,9 +97,11 @@ local_private_key = "cQ/vwIqNPJZmuM/OikglzBo/+jlYGrOt9i0k5h5vn1Q="
 Then `rathole` will run under the protection of the Noise Protocol.
 
 ## Specifying the Pattern of Noise Protocol
+
 The default configuration of Noise Protocol that comes with `rathole` satifies most use cases, which is described above. But there're other patterns that can be useful.
 
 ### No Authentication
+
 This configuration provides encryption of the traffic but provides no authentication, which means it's vulnerable to MITM attack, but is resistent to the sniffing and replay attack. If MITM attack is not one of the concerns, this is more convenient to use.
 
 ```toml
@@ -107,6 +133,7 @@ remote_public_key = "server-pub-key-here"
 ### Other Patterns
 
 To find out which pattern to use, refer to:
+
 - [7.5. Interactive handshake patterns (fundamental)](https://noiseprotocol.org/noise.html#interactive-handshake-patterns-fundamental)
 - [8. Protocol names and modifiers](https://noiseprotocol.org/noise.html#protocol-names-and-modifiers)