readme errors fix
This commit is contained in:
parent
bc5b5b3b3a
commit
6dc246e68c
117
README.md
117
README.md
@ -8,22 +8,26 @@ The new generation of __PARanoid SECurity__ protocol, advanced, faster, more sec
|
||||
block device" transport to the same local interface. Out if the box it
|
||||
provides the following transports:
|
||||
|
||||
| name | JVM | JS | native |
|
||||
|-------------------|--------|----|--------|
|
||||
| TCP/IP server | ✓ | | 0.2.6+ |
|
||||
| TCP/IP client | ✓ | | 0.2.6+ |
|
||||
| UDP server | 0.3.2+ | | 0.3.2+ |
|
||||
| UDP client | 0.3.2+ | | 0.3.2+ |
|
||||
| Websockets server | ✓ | | |
|
||||
| Websockets client | ✓ | ✓ | ✓ |
|
||||
| name | JVM | JS | wasmJS | native |
|
||||
|-------------------|--------|----|--------|--------|
|
||||
| TCP/IP server | ✓ | | | 0.2.6+ |
|
||||
| TCP/IP client | ✓ | | | 0.2.6+ |
|
||||
| UDP server | 0.3.2+ | | | 0.3.2+ |
|
||||
| UDP client | 0.3.2+ | | | 0.3.2+ |
|
||||
| Websockets server | ✓ | | | |
|
||||
| Websockets client | ✓ | ✓ | ✓ | ✓ |
|
||||
|
||||
### Note on version compatibility
|
||||
|
||||
Since version 0.6.9 websocket protocol supports both text and binary frames; old clients are backward compatible with mew servers, but new clients only can work with older servers only in default binary frame mode. Upgrade also your servers to get better websocket compatibility[^1].
|
||||
We recommend using `0.6.12`
|
||||
|
||||
Version 0.5.1 could be backward incompatible due to upgrade of the crypto2.
|
||||
Since version 0.6.9 websocket protocol supports both text and binary frames; old clients are backward compatible with
|
||||
mew servers, but new clients only can work with older servers only in default binary frame mode. Upgrade also your
|
||||
servers to get better websocket compatibility[^1].
|
||||
|
||||
Protocols >= 0.3.0 are not binary compatible with previous version due to more compact binary
|
||||
Version 0.5.1 could be backward incompatible due to the upgrade of the crypto2.
|
||||
|
||||
Protocols >= 0.3.0 are not binary compatible with the previous version due to a more compact binary
|
||||
format. The format from 0.3.0 onwards is supposed to keep compatible.
|
||||
|
||||
#### ID calculation algorithm is changed since 0.4.1
|
||||
@ -43,10 +47,13 @@ We recommend to upgrade to 0.4+ ASAP as public/shared key id derivation method w
|
||||
|
||||
## TCP/IP and UDP transports
|
||||
|
||||
These are the fastest based on async socket implementation of ktor client. They works everywhere but JS target as
|
||||
there is currently no widely adopted sockets for browser javascript.
|
||||
These are the fastest based on async socket implementation of a ktor client. They work everywhere but JS target as
|
||||
there are currently no widely adopted sockets for browser JavaScript.
|
||||
|
||||
While UDP is faster than TCP/IP, it is less reliable, especially with commands and return values that serializes to more than 240 bytes approx, and has no retransmission facilities (use TCP!). UDP though shines when all you need is to [push](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-remote-interface/push.html) with little or no data in it.
|
||||
While UDP is faster than TCP/IP, it is less reliable, especially with commands and return values that serialize to more
|
||||
than 240 bytes approx, and has no retransmission facilities (use TCP!). UDP, though, shines when all you need is
|
||||
to [push](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-remote-interface/push.html) with
|
||||
little or no data in it.
|
||||
|
||||
## Websockets server
|
||||
|
||||
@ -63,7 +70,7 @@ It is slower than TCP or UDP, but it works on literally all platforms. See the s
|
||||
|
||||
# Usage
|
||||
|
||||
The library should be used as maven dependency, not as source.
|
||||
The library should be used as a maven dependency, not as source.
|
||||
|
||||
## Adding dependency
|
||||
|
||||
@ -89,7 +96,7 @@ val commonMain by getting {
|
||||
}
|
||||
```
|
||||
|
||||
## Create shared interface for your server and the client
|
||||
## Create a shared interface for your server and the client
|
||||
|
||||
It could be a multiplatform library that exports it or just a shared or copied source file declaring structures
|
||||
and functions available, like:
|
||||
@ -140,10 +147,10 @@ assertEquals(FooArgs("bar", 117), client.call(cmdGetFoo))
|
||||
|
||||
```
|
||||
|
||||
## Create ktor-based server
|
||||
## Create a ktor-based server
|
||||
|
||||
Normally server side needs some session. It is convenient and avoid sending repeating data on each request speeding up
|
||||
the protocol. With KILOPARSEC, it is rather basic operation:
|
||||
Normally the server side needs some session. It is convenient and avoids sending repeating data on each request speeding up
|
||||
the protocol. With KILOPARSEC, it is a rather basic operation:
|
||||
|
||||
~~~kotlin
|
||||
// Our session just keeps Foo for cmd{Get|Set}Foo:
|
||||
@ -170,11 +177,11 @@ val ns: NettyApplicationEngine = embeddedServer(Netty, port = 8080, host = "0.0.
|
||||
|
||||
~~~
|
||||
|
||||
## Create TCP/IP client and server
|
||||
## Create a 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://` (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.
|
||||
protected as `wss://` (and `ws://`) the 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:
|
||||
|
||||
@ -182,11 +189,13 @@ Documentation is available in samples here:
|
||||
|
||||
- [TCP/IP client](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-kilo-client/index.html)
|
||||
|
||||
In short, there are two functions that implements asynchronous TCP/IP transport on all platforms buy JS:
|
||||
In short, there are two functions that implement asynchronous TCP/IP transport on all platforms buy JS:
|
||||
|
||||
- [acceptTcpDevice](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec.adapter/accept-tcp-device.html?query=fun%20acceptTcpDevice(port:%20Int):%20Flow%3CInetTransportDevice%3E) to create a server
|
||||
- [acceptTcpDevice](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec.adapter/accept-tcp-device.html?query=fun%20acceptTcpDevice(port:%20Int):%20Flow%3CInetTransportDevice%3E)
|
||||
to create a server
|
||||
|
||||
- [connectTcpDevice](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec.adapter/connect-tcp-device.html) to connect to the server
|
||||
- [connectTcpDevice](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec.adapter/connect-tcp-device.html)
|
||||
to connect to the server
|
||||
|
||||
## UDP client and server
|
||||
|
||||
@ -199,36 +208,50 @@ Is very much straightforward, same as with TCP/IP:
|
||||
|
||||
#### Command size
|
||||
|
||||
Each command invocation and result are packed in a separate UDP diagram using effective binary packing.
|
||||
Thus, for the best results commands and results should be relatively short, best to fit into 240 bytes. While bigger datagrams are often transmitted successfully, the probability of the effective transmission drops with the size.
|
||||
Each command invocation and result are packed in a separate UDP diagram using effective binary packing.
|
||||
Thus, for the best results commands and results should be relatively short, best to fit into 240 bytes. While bigger
|
||||
datagrams are often transmitted successfully, the probability of the effective transmission drops with the size.
|
||||
|
||||
Kiloparsec UDP transport does not retransmit not delivered packets. Use TCP/IP or websocket if it is a concern.
|
||||
|
||||
For the best results we recommend using [push](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-remote-interface/index.html#1558240250%2FFunctions%2F788909594) for remote interfaces with UDP.
|
||||
For the best results, we recommend
|
||||
using [push](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-remote-interface/index.html#1558240250%2FFunctions%2F788909594)
|
||||
for remote interfaces with UDP.
|
||||
|
||||
#### Timeouts
|
||||
|
||||
As Datagrams do not form protocol itself, kiloparsec issues pings when no data is circulated between parties.
|
||||
When no pings are received long enough, kiloparsec connection is closed. There are `maxInactivityTimeout` in all
|
||||
When no pings are received long enough, the kiloparsec connection is closed. There are `maxInactivityTimeout` in all
|
||||
relevant functions and constructors.
|
||||
|
||||
Client should not issue pings manually.
|
||||
|
||||
## 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.
|
||||
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.
|
||||
This is a common practice 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
|
||||
We do not recommend relying 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 attack] 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) when creating a server.
|
||||
chain, in which case the [MITM attack] 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)
|
||||
when creating a server.
|
||||
|
||||
This will effectively protect against certificate chain spoofing in the case of the application installed from the trusted source.
|
||||
This will effectively protect 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. For applications, we strongly recommend not to use CDN except your own, controlled ones. You generally can't neither detect nor repel [MITM attack] performed from _any single cloudflare 'ray'_.
|
||||
__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. For applications, we strongly recommend not using CDN except your own, controlled ones. You
|
||||
generally can't neither detect nor repel [MITM attack] performed from _any single cloudflare 'ray'_.
|
||||
|
||||
## See also:
|
||||
|
||||
@ -237,25 +260,25 @@ __Important note__. The web application could not be completely secured this way
|
||||
|
||||
# Details
|
||||
|
||||
It is not compatible with parsec family and no more based on an Universa crypto library. To better fit
|
||||
It is not compatible with Parsec family and no more based on the Universa crypto library. To better fit
|
||||
the modern state of threats and rate of cyber crimes, KiloParsec uses more encryption and random key exchange on each
|
||||
and every connection (while parsec caches session keys to avoid time-consuming keys exchange). For the same reason,
|
||||
keys cryptography for session is shifted to use ed25519 curves which are supposed to provide agreeable strength with
|
||||
enough speed to protect every connection with a unique new keys. Also, we completely get rid of SHA2.
|
||||
keys cryptography for session is shifted to use ed25519 curves, which are supposed to provide agreeable strength with
|
||||
enough speed to protect every connection with unique new keys. Also, we completely get rid of SHA2.
|
||||
|
||||
Kiloparsec also uses a denser binary format [bipack](https://gitea.sergeych.net/SergeychWorks/mp_bintools), no more
|
||||
key-values,
|
||||
which reveals much less on the inner data structure, providing advanced
|
||||
typed RPC interfaces with kotlinx.serialization. There is also Rust
|
||||
implementation [bipack_ru](https://gitea.sergeych.net/DiWAN/bipack_ru).
|
||||
The architecture allows connecting same functional interfaces to several various type channels at once.
|
||||
The architecture allows connecting the same functional interfaces to several various type channels at once.
|
||||
|
||||
Also, the difference from parsecs is that there are no more unencrypted layer commands available to users.
|
||||
All RPC is performed over the encrypted connection.
|
||||
|
||||
# Technical description
|
||||
|
||||
Kiloparsec is a full-duplex fully async (coroutine based) Remote Procedure Call protocol with typed parameters
|
||||
Kiloparsec is a full-duplex fully async (coroutine-based) Remote Procedure Call protocol with typed parameters
|
||||
and support for serializing exceptions (e.g. exception thrown while executing remote command will be caught and
|
||||
rethrown at the caller context).
|
||||
|
||||
@ -264,17 +287,21 @@ Integrated tools to prevent MITM attacks include also non-transferred independen
|
||||
independently on the ends and is never transferred with the network. Comparing it somehow (visually, with QR code, etc.)
|
||||
could add a very robust guarantee of the connection safety and ingenuity.
|
||||
|
||||
Kiloparsec has built-in completely asynchronous (coroutine based top-down) transport layer based on TCP (JVM only as for
|
||||
Kiloparsec has a built-in completely asynchronous (coroutine-based top-down) transport layer based on TCP (JVM only as for
|
||||
now) and the same async Websocket-based transport based on KTOR. Websocket client is multiplatform, though the server is
|
||||
JVM only insofar.
|
||||
|
||||
# Licensing
|
||||
|
||||
This is work in progress, not yet moved to public domain;
|
||||
you need to obtain a license from https://8-rays.dev or [Sergey Chernov]. For open source projects it will most be free on some special terms.
|
||||
This is a work in progress, not yet moved to the public domain;
|
||||
you need to obtain a license from https://8-rays.dev or [Sergey Chernov]. For open source projects it will most be free
|
||||
on some special terms.
|
||||
|
||||
It will be moved to open source; we also guarantee that it will be moved to open source immediately if the software export restrictions will be lifted. We do not support such practices here at 8-rays.dev.
|
||||
It will be moved to open source; we also guarantee that it will be moved to open source immediately if the software
|
||||
export restrictions are lifted. We do not support such practices here at 8-rays.dev.
|
||||
|
||||
[MITM]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
|
||||
|
||||
[Sergey Chernov]: https://t.me/real_sergeych
|
||||
[^1]: On some new Xiaomi phones we found problems with websocket binary frames, probably in ktor; use text frames otherwise.
|
||||
[^1]: On some new Xiaomi phones we found problems with websocket binary frames, probably in ktor; use text frames
|
||||
otherwise.
|
||||
Loading…
x
Reference in New Issue
Block a user