From 7100fa5f76cbb6d01b6e274f697f643948dc22e2 Mon Sep 17 00:00:00 2001 From: sergeych Date: Sat, 10 Aug 2024 11:26:24 +0200 Subject: [PATCH] more docs --- README.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e653958..d9f67dd 100644 --- a/README.md +++ b/README.md @@ -153,10 +153,10 @@ val ns: NettyApplicationEngine = embeddedServer(Netty, port = 8080, host = "0.0. ~~~ -### TCP/IP client and server +## Create TCP/IP client and server Using plain TCP/IP is even simpler, and it works way faster than websocket one, and is _the same -protected as `wss://` variant abovve due to same kiloparsec encryption in both cases. Still, a TCP/IP +protected as `wss://` (and `ws://`) variant above due to same kiloparsec encryption in both cases. Still, a TCP/IP client is not available in Javascript browser targets and custom TCP ports could often be blocked by firewalls. Documentation is available in samples here: @@ -171,12 +171,23 @@ In short, there are two functions that implements aysnchronous TCP/IP transport - [connectTcpDevice](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec.adapter/connect-tcp-device.html) to connect to the server -### Reusing code between servers +## Reusing code between servers The same instance of the [KiloInterface](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-kilo-interface/index.html?query=open%20class%20KiloInterface%3CS%3E%20:%20LocalInterface%3CKiloScope%3CS%3E%3E) could easily be reused with all instances of servers with different protocols. This is a common proactive to create a business logic in a `KiloInterface`, then create a TCP/IP and Websocket servers passing the same instance of the logic to both. +## Note on the server identification + +We do not recommend to rely on TLS (HTTPS://, WSS://) host identification solely, in the modern world there is +a high probability of attacks on unfriendly (in respect to at least some of your users) states to the SSL certificates +chain, in which case the MITM and spoofing will be undetected. Check the [remoteId](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-kilo-client/remote-id.html?query=suspend%20fun%20remoteId():%20VerifyingPublicKey?) in your client on each connection and provide the safe [serverSecretKey](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-kilo-server/index.html?query=class%20KiloServer%3CS%3E(clientInterface:%20KiloInterface%3CS%3E,%20connections:%20Flow%3CInetTransportDevice%3E,%20serverSecretKey:%20SigningKey?%20=%20null,%20sessionBuilder:%20()%20-%3E%20S) when creating a server. + +This will effectively protetcs against certificate chain spoofing in the case of the application installed from the trusted source. + +__Important note__. The web application could not be completely secured this way unless is loaded from the IP-address, as the DNS could be spoofed the same, especially when used with `Cloudflare` or other CDN that can +transparently substitute the whole site. In the case of we applications we strongly recommend not to use CDN except your own where you can control actual traffic rules. + ## See also: - [Source documentation](https://code.sergeych.net/docs/kiloparsec/)