docs: add about the noise protocol

README.md

@@ -57,6 +57,8 @@ But the `[client]` and `[server]` block can also be put in one file. Then on the
 
 Some configuration examples are provided under [examples](./examples).
 
+The Noise Protocol can be easily used to secure the traffic, see [Security](./docs/security.md).
+
 Here is the full configuration specification:
 ```toml
 [client]
@@ -65,10 +67,16 @@ default_token = "default_token_if_not_specify" # Optional. The default token of
 
 [client.transport]
 type = "tcp" # Optional. Possible values: ["tcp", "tls"]. Default: "tcp"
+
 [client.transport.tls] # Necessary if `type` is "tls"
 trusted_root = "ca.pem" # Necessary. The certificate of CA that signed the server's certificate
 hostname = "example.com" # Optional. The hostname that the client uses to validate the certificate. If not set, fallback to `client.remote_addr`
 
+[client.transport.noise] # Noise protocol. See `docs/security.md` for further explanation
+pattern = "Noise_NK_25519_ChaChaPoly_BLAKE2s" # Optional. Default value as shown
+local_private_key = "key_encoded_in_base64" # Optional
+remote_public_key = "key_encoded_in_base64" # Optional
+
 [client.services.service1] # A service that needs forwarding. The name `service1` can change arbitrarily, as long as identical to the name in the server's configuration
 type = "tcp" # Optional. The protocol that needs forwarding. Possible values: ["tcp", "udp"]. Default: "tcp"
 token = "whatever" # Necessary if `client.default_token` not set
@@ -83,10 +91,16 @@ default_token = "default_token_if_not_specify" # Optional
 
 [server.transport]
 type = "tcp" # Same as `[client.transport]`
+
 [server.transport.tls] # Necessary if `type` is "tls"
 pkcs12 = "identify.pfx" # Necessary. pkcs12 file of server's certificate and private key
 pkcs12_password = "password" # Necessary. Password of the pkcs12 file
 
+[server.transport.noise] # Same as `[client.transport.noise]`
+pattern = "Noise_NK_25519_ChaChaPoly_BLAKE2s"
+local_private_key = "key_encoded_in_base64" 
+remote_public_key = "key_encoded_in_base64" 
+
 [server.services.service1] # The service name must be identical to the client side
 type = "tcp" # Optional. Same as the client `[client.services.X.type]
 token = "whatever" # Necesary if `server.default_token` not set

docs/security.md

@@ -1,8 +1,84 @@
 # Security
 
-## How to use the default noise transport
+## 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.
 
-The default noise protocol pattern is `Noise_NK_25519_ChaChaPoly_BLAKE2s`. So a Curve25519 keypair is required.
+`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.
 
-### Generate a Curve25519 keypair
-https://stackoverflow.com/questions/43546712/how-to-generate-a-curve25519-key-pair-in-terminal
+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:
+```
+$ rathole --genkey
+Private Key:
+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]
+type = "noise"
+[client.transport.noise]
+remote_public_key = "GQYTKSbWLBUSZiGfdWPSgek9yoOuaiwGD/GIX8Z1kkE="
+
+# Server Side Configuration
+[server.transport]
+type = "noise"
+[server.transport.noise]
+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
+# Server Side Configuration
+[server.transport.noise]
+pattern = "Noise_XX_25519_ChaChaPoly_BLAKE2s"
+
+# Client Side Configuration
+[client.transport.noise]
+pattern = "Noise_KK_25519_ChaChaPoly_BLAKE2s"
+```
+
+### Bidirectional Authentication
+
+```toml
+# Server Side Configuration
+[server.transport.noise]
+pattern = "Noise_KK_25519_ChaChaPoly_BLAKE2s"
+local_private_key = "server-priv-key-here"
+remote_public_key = "client-pub-key-here"
+
+# Client Side Configuration
+[client.transport.noise]
+pattern = "Noise_KK_25519_ChaChaPoly_BLAKE2s"
+local_private_key = "client-priv-key-here"
+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)
+
+Note that PSKs are not supported currently. Free to open an issue if you need it.