Commit 404ff964 authored by Éloïs's avatar Éloïs

[ref] ws2pv2: simplification of endpoint format & precise hash usage

parent 0e9efebd
......@@ -101,7 +101,6 @@ To summarize, each WS2P Public node will declare in its endpoint the list of fea
Developers of client software need to study the new format of peer and HEAD records.
They must be able to parse this new format such that BMA 1.7 will provide them.
And above all they must be able to binarise peer records to verify the integrity of their signature.
Finally, users associating external endpoints to their peer cards will have to redeclare their external endpoints in the new generic enpoint format.
......@@ -195,7 +194,7 @@ Any other value of `is_some` is prohibited and will invalidate the entire messag
String formatted in utf8 and [NFKC normalized](https://fr.wikipedia.org/wiki/Normalisation_Unicode#NFKC).
**/!\ CAUTION: All strings are systematically prefixed with their size, including for an empty string. The size is stored on 8 bytes as shown in the table below :**
**/!\ WARNING: All strings are systematically prefixed with their size, including for an empty string. The size is stored on 8 bytes as shown in the table below :**
| data | size in bytes | data type |
|:---------:|--------------:|----------------:|
......@@ -269,33 +268,32 @@ currency_name := Empty string is allowed, it allow the user to synchronize his n
_* The type of `payload` is determined by the content of `message_type`._
The signature is not always present, it's only present for connection negotiation messages.
The signature is generated from the hash sha 256 of the message.
This hash is always given to allow the receiving node to verify that it has not received corrupted datas.
The signature is generated from the byte vector of the entire message (signature field excluded).
### message_type interpretation
| message type | code | Signed |
|:--------------------:|--------|--------|
| CONNECT | 0 | yes |
| ACK | 1 | yes |
| SECRET_FLAGS | 2 | yes |
| OK | 3 | yes |
| KO | 4 | yes |
| REQUEST | 5 | no |
| REQUEST_RESPONSE | 6 | no |
| PEERS | 7 | no |
| HEADS_V2 | 8 | no |
| HEADS_V3 | 9 | no |
| BLOCKS | 10 | no |
| PENDING_IDENTITIES | 11 | no |
| PENDING_MEMBERSHIPS | 12 | no |
| PENDING_CERTS | 13 | no |
| PENDING_REVOCATIONS | 14 | no |
| PENDING_TXS | 15 | no |
| message type | code | Hashed | Signed |
|:--------------------:|--------|--------|--------|
| CONNECT | 0 | no | yes |
| ACK | 1 | no | yes |
| SECRET_FLAGS | 2 | no | yes |
| OK | 3 | no | yes |
| KO | 4 | no | yes |
| REQUEST | 5 | yes | no |
| REQUEST_RESPONSE | 6 | yes | no |
| PEERS | 7 | yes | no |
| HEADS_V2 | 8 | yes | no |
| HEADS_V3 | 9 | yes | no |
| BLOCKS | 10 | yes | no |
| PENDING_IDENTITIES | 11 | yes | no |
| PENDING_MEMBERSHIPS | 12 | yes | no |
| PENDING_CERTS | 13 | yes | no |
| PENDING_REVOCATIONS | 14 | yes | no |
| PENDING_TXS | 15 | yes | no |
## Endpoints v1
WS2pv1 used endpoints version v0. So, in WS2Pv2 we improve to endpoints version v1.
WS2Pv1 used endpoints version v0. So, in WS2Pv2 we improve to endpoints version v1.
### Endpoint binary format
......@@ -324,13 +322,23 @@ Network features :
| bit | feature |
|:---------:|----------|
| 0000_0001 | HTTP |
| 0000_0010 | WS |
| 0000_0100 | TLS |
| 0000_1000 | TOR |
TLS := This feature indicates that the endpoint should be contacted with an SSL/TLS overlay (HTTPS or WSS).
HTTP := This feature indicates that the endpoint should be contacted with http protocol.
WS := This feature indicates that the endpoint should be contacted with websocket protocol.
TLS := This feature indicates that the endpoint should be contacted with an SSL/TLS overlay (HTTPS or WSS or any other protocol that support TLS).
TOR := This feature indicates that the endpoint must be contacted via the tor network (hidden service).
Note about the network protocol to choose: Each API must define a default network protocol. If no network protocol is specified in the network features, the default API network protocol is chosen.
For example, the default network protocol for WS2P is `ws://`, it's the only one possible for this API, so there is no need to indicate it in the network features.
#### api_features
The interpretation of this field depends on the API because it represents API-specific features. Here is the interpretation for the WS2P API :
......@@ -357,14 +365,15 @@ The utf8 format is used to display the endpoint in a human-readable format. It i
General utf8 endpoint format :
API_NAME VERSION n NF1 .. NFn n2 AF1 .. AFn2 PORT HOST IP4 [IP6] PATH
API_NAME VERSION NF1 .. NFn AF PORT HOST IP4 [IP6] PATH
VERSION := version number prefixed by `V` (example : `V1`)
NF := NETWORK_FEATURE
AF := API_FEATURE
AF := API_FEATURES in hexadecimal
Example:
WS2P 2 1 TLS 3 DEF LOW ABF 443 g1.durs.info ws2p
WS2P V2 TLS 7 443 g1.durs.info ws2p
Same endpoint in binary format :
......@@ -427,61 +436,63 @@ Example :
Peer card v11 PEG grammar :
```
// Single character rules
nl = _{ "\n" }
no_zero_hexa_lower = @{ '1'..'9' | 'a'..'f' }
hexa_lower = @{ ASCII_DIGIT | 'a'..'f' }
hexa_upper = @{ ASCII_DIGIT | 'A'..'F' }
base58 = { !("O" | "I" | "l") ~ ASCII_ALPHANUMERIC }
base64 = { ASCII_ALPHANUMERIC | "+" | "/" }
// Numbers rules
tens = @{ '1'..'9' ~ ASCII_DIGIT }
u8_hundreds = @{ ("2" ~ ('0'..'4' ~ ASCII_DIGIT | ('0'..'5'){2})) | ("1" ~ ASCII_DIGIT{2}) }
u8 = @{ u8_hundreds | tens | ASCII_DIGIT }
no_zero_u_int = @{ '1'..'9' ~ ASCII_DIGIT* }
u_int = @{ "0" | no_zero_u_int }
// Usefull types rules
currency = @{ ASCII_ALPHA ~ (ASCII_ALPHANUMERIC | "-" | "_"){,255} }
block_id = @{ u_int }
hash = @{ hexa_upper{64} }
pubkey = @{ base58{43,44} }
blockstamp = ${ block_id ~ "-" ~ hash }
ed25519_sig = @{ base64{88} | (base64{87} ~ "=") | (base64{86} ~ "==") }
// IP v6 rules
ip6_seg = _{ hexa_lower{1,4} }
ip6_full = _{ (ip6_seg ~ ":"){7} ~ ip6_seg }
ip6_no_full = @{
ip6_seg? ~
(":" ~ ip6_seg){0,6} ~
"::" ~
(ip6_seg ~ ":"){0,6} ~
ip6_seg?
}
ip6_inner = @{ ip6_full | ip6_no_full }
ip6 = _{ "[" ~ ip6_inner ~ "] " }
// Endpoint v2 rules
api_version_inner = @{ no_zero_u_int }
api_version = _{ "V" ~ api_version_inner ~ " " }
tls = @{ "S " }
tor = @{ "TOR " }
network_features = _{ tls? ~ tor? }
api_features_inner = @{ (hexa_lower{2})+ | no_zero_hexa_lower }
api_features = _{ api_features_inner ~ " " }
host_v2_inner = @{ ASCII_ALPHA_LOWER ~ (ASCII_ALPHA_LOWER | ASCII_DIGIT | "-" | "_" | ".")* }
host_v2 = _{ host_v2_inner ~ " " }
ip4_inner = { u8 ~ "." ~ u8 ~ "." ~ u8 ~ "." ~ u8 }
ip4 = _{ ip4_inner ~ " " }
path = _{ " " ~ path_inner }
endpoint_v2 = ${ api_name ~ " " ~ (api_version)? ~ (network_features)? ~ (api_features)? ~ host_v2? ~ ip4? ~ ip6? ~ port ~ path? }
// Peer v11 rules
peer_v11 = ${ "11:" ~ currency ~ ":" ~ node_id ~ ":" ~ pubkey ~ ":" ~ blockstamp ~ nl ~ (endpoint_v2 ~ nl)+ ~ ed25519_sig? }
```
```
// Single character rules
nl = _{ "\n" }
no_zero_hexa_lower = @{ '1'..'9' | 'a'..'f' }
hexa_lower = @{ ASCII_DIGIT | 'a'..'f' }
hexa_upper = @{ ASCII_DIGIT | 'A'..'F' }
base58 = { !("O" | "I" | "l") ~ ASCII_ALPHANUMERIC }
base64 = { ASCII_ALPHANUMERIC | "+" | "/" }
// Numbers rules
tens = @{ '1'..'9' ~ ASCII_DIGIT }
u8_hundreds = @{ ("2" ~ ('0'..'4' ~ ASCII_DIGIT | ('0'..'5'){2})) | ("1" ~ ASCII_DIGIT{2}) }
u8 = @{ u8_hundreds | tens | ASCII_DIGIT }
no_zero_u_int = @{ '1'..'9' ~ ASCII_DIGIT* }
u_int = @{ "0" | no_zero_u_int }
// Usefull types rules
currency = @{ ASCII_ALPHA ~ (ASCII_ALPHANUMERIC | "-" | "_"){,255} }
block_id = @{ u_int }
hash = @{ hexa_upper{64} }
pubkey = @{ base58{43,44} }
blockstamp = ${ block_id ~ "-" ~ hash }
ed25519_sig = @{ base64{88} | (base64{87} ~ "=") | (base64{86} ~ "==") }
// IP v6 rules
ip6_seg = _{ hexa_lower{1,4} }
ip6_full = _{ (ip6_seg ~ ":"){7} ~ ip6_seg }
ip6_no_full = @{
ip6_seg? ~
(":" ~ ip6_seg){0,6} ~
"::" ~
(ip6_seg ~ ":"){0,6} ~
ip6_seg?
}
ip6_inner = @{ ip6_full | ip6_no_full }
ip6 = _{ "[" ~ ip6_inner ~ "] " }
// Endpoint v2 rules
api_version_inner = @{ no_zero_u_int }
api_version = _{ "V" ~ api_version_inner ~ " " }
http = @{ "HTTP " }
ws = @{ "WS " }
tls = @{ "S " }
tor = @{ "TOR " }
network_features = _{ http? ~ ws? ~ tls? ~ tor? }
api_features_inner = @{ (hexa_lower{2})+ | no_zero_hexa_lower }
api_features = _{ api_features_inner ~ " " }
host_v2_inner = @{ ASCII_ALPHA_LOWER ~ (ASCII_ALPHA_LOWER | ASCII_DIGIT | "-" | "_" | ".")* }
host_v2 = _{ host_v2_inner ~ " " }
ip4_inner = { u8 ~ "." ~ u8 ~ "." ~ u8 ~ "." ~ u8 }
ip4 = _{ ip4_inner ~ " " }
path = _{ " " ~ path_inner }
endpoint_v2 = ${ api_name ~ " " ~ (api_version)? ~ (network_features)? ~ (api_features)? ~ host_v2? ~ ip4? ~ ip6? ~ port ~ path? }
// Peer v11 rules
peer_v11 = ${ "11:" ~ currency ~ ":" ~ node_id ~ ":" ~ pubkey ~ ":" ~ blockstamp ~ nl ~ (endpoint_v2 ~ nl)+ ~ ed25519_sig? }
```
### Peer card JSON format
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment