SergeychWorks/kiloparsec
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 6 Wiki Activity

fixed/improved readme for publications

Browse Source
This commit is contained in:
Sergey Chernov 2025-02-20 11:58:13 +03:00
parent c0bc0e3dfe
commit a80820b9a8
1 changed files with 30 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
README.md
View File

@ -1,21 +1,21 @@
# Kiloparsec # Kiloparsec
__Recommended version is `0.4.1`: to keep the code compatible with current and further versions we __Recommended version is `0.4.1`: to keep the code compatible with current and further versions we
ask to upgrade to `0.4.2` at least.__ Starting from this version some pacakage names are changed for ask to upgrade to `0.4.2` at least.__ Starting from this version some package names are changed for
better clarity and fast UDP endpoints are added. better clarity and fast UDP endpoints are added.
The new generation of __PARanoid SECurity__ protocol, advanced, faster, more secure. It also allows connecting any " The new generation of __PARanoid SECurity__ protocol, advanced, faster, more secure. It also allows connecting any "
block device" transport to the same local interface. Out if the box it block device" transport to the same local interface. Out if the box it
provides the following transports: provides the following transports:
| name | JVM | JS | native | | name | JVM | JS | native |
|----------------|--------|----|--------| |-------------------|--------|----|--------|
| TCP/IP server | ✓ | | 0.2.6+ | | TCP/IP server | ✓ | | 0.2.6+ |
| TCP/IP client | ✓ | | 0.2.6+ | | TCP/IP client | ✓ | | 0.2.6+ |
| UDP server | 0.3.2+ | | 0.3.2+ | | UDP server | 0.3.2+ | | 0.3.2+ |
| UDP client | 0.3.2+ | | 0.3.2+ | | UDP client | 0.3.2+ | | 0.3.2+ |
| Websock server | ✓ | | | | Websockets server | ✓ | | |
| Websock client | ✓ | ✓ | ✓ | | Websockets client | ✓ | ✓ | ✓ |
### Note on version compatibility ### Note on version compatibility
@ -36,8 +36,8 @@ We recommend to upgrade to 0.4+ ASAP as public/shared key id derivation method w
### Non-native targets ### Non-native targets
- JS (browser and nodeJS) - JS (browser and Node.js)
- JVM (android, macos, windows, linx, everywhere where JRE is installed) - JVM (android, macOS, windows, linux, everywhere where JRE is installed)
## TCP/IP and UDP transports ## TCP/IP and UDP transports
@ -46,13 +46,13 @@ there is 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 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.
## Websock server ## Websockets server
While it is much slower than TCP or UDP, it is still faster than any http-based API; it uses binary frames based on While it is much slower than TCP or UDP, it is still faster than any http-based API; it uses binary frames based on
the Ktor server framework to easily integrate with web services. We recommend using it instead of a classic HTTP API as the Ktor server framework to easily integrate with web services. We recommend using it instead of a classic HTTP API as
it beats it in terms of speed and server load even with HTTP/2. it beats it in terms of speed and server load even with HTTP/2.
We recommend to create the `KiloInterface<S>` instance and connect it to the websock and tcp servers in real We recommend to create the `KiloInterface<S>` instance and connect it to the websockets and tcp servers in real
applications to get easy access from anywhere. applications to get easy access from anywhere.
## Websocket client ## Websocket client
@ -111,7 +111,7 @@ val cmdPushClient by command<String, Unit>()
## Call it from the client: ## Call it from the client:
Remember, we need to implement client interface `cmdPushClient` in our example, so we need to provide Remember, we need to implement client interface `cmdPushClient` in our example, so we need to provide
local interace too: local interface too:
```kotlin ```kotlin
// Unit: no session on the client: // Unit: no session on the client:
@ -141,7 +141,7 @@ assertEquals(FooArgs("bar", 117), client.call(cmdGetFoo))
## Create ktor-based server ## Create ktor-based server
Normally server side needs some session. It is convenient and avoid sending repeating data on each request speeding up 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: the protocol. With KILOPARSEC, it is rather basic operation:
~~~kotlin ~~~kotlin
// Our session just keeps Foo for cmd{Get|Set}Foo: // Our session just keeps Foo for cmd{Get|Set}Foo:
@ -198,9 +198,9 @@ Is very much straightforward, same as with TCP/IP:
#### Command size #### Command size
Each command invocation and result are packed in a separate UDP diagram using effective binary packing. 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. 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 retransmits not delivered packets. Use TCP/IP or websocket if it is a concern. 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.
@ -210,7 +210,7 @@ As Datagrams do not form protocol itself, kiloparsec issues pings when no data i
When no pings are received long enough, kiloparsec connection is closed. There are `maxInactivityTimeout` in all When no pings are received long enough, kiloparsec connection is closed. There are `maxInactivityTimeout` in all
relevant functions and constructors. relevant functions and constructors.
Client shoudl not issue pings manually. Client should not issue pings manually.
## Reusing code between servers ## Reusing code between servers
@ -222,12 +222,11 @@ This is a common proactive to create a business logic in a `KiloInterface`, then
We do not recommend to rely on TLS (HTTPS://, WSS://) host identification solely, in the modern world there is 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 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) 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 protetcs 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 __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'_.
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: ## See also:
@ -254,13 +253,13 @@ All RPC is performed over the encrypted connection.
# Technical description # Technical description
Kiloparsec is a dull-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 and support for serializing exceptions (e.g. exception thrown while executing remote command will be caught and
rethrown at the caller context). rethrown at the caller context).
Kiloparsec is not REST, it _has advanced session mechanisms_ and built-in authentication based on the same curve keys. Kiloparsec is not REST, it _has advanced session mechanisms_ and built-in authentication based on the same curve keys.
Integrated tools to prevent MITM attacks include also non-transferred independently generated token that is calculated Integrated tools to prevent MITM attacks include also non-transferred independently generated token that is calculated
independently on the ends and is never transferred with the network. Comparing it somehow (visually, with QR code, etc) 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. 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 built-in completely asynchronous (coroutine based top-down) transport layer based on TCP (JVM only as for
@ -269,4 +268,10 @@ JVM only insofar.
# Licensing # Licensing
Currently, you need to obtain a license from https://8-rays.dev or Sergey Chernov. 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.
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.
[MITM]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
[Sergey Chernov]: https://t.me/real_sergeych