Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found
Select Git revision
  • dewif
  • dubp-mnemonic
  • dubp_v12
  • dubp_v13
  • hd_wallet
  • master
  • rfc17
  • rfc18_multilang_mnemonic
  • tx-out-hash
  • tx_comment_encrypt
  • ws2p_v2
11 results

Target

Select target project
  • documents/rfcs
  • matograine/rfcs
  • 1000i100/rfcs
  • LukeMarlin/rfcs
  • tuxmain/rfcs
  • pokapow/rfcs
6 results
Select Git revision
  • 0016_checksum
  • dubp-mnemonic
  • dubp_v12
  • dubp_v13
  • feature/protocol-v2s
  • hd_wallet
  • master
  • tx-out-hash
  • tx_comment_encrypt
  • ws2p_v2
10 results
Show changes
Commits on Source (34)
Expand all Show whitespace changes
Inline Side-by-side
rfc/0004_ws2p_v1.md
View file @ 154adda5
......@@ -203,8 +203,9 @@ When the timeout is reached, if the request has not been fully processed, it is
In cases where the request is fully processed before the timeout, the response is determined according to the following algorithm :
If the public key of the remote node is the same as yourself
If the public key of the remote node is the same as yourself {
If the uuid is not the same, accept the connection. Otherwise, refuse connection. (do not accept oneself connetion).
}
If the pubkey is banned, refuse connection.
If priorityKeysOnly is enable and the pubkey isn't privileged, refuse connection.
If there is already an active ws2p connection with this key (whether incoming or outcoming), refuse connection.
......@@ -479,6 +480,66 @@ JSON error response :
err: String(error message)
}
BLOCK_IN_JSON_FORMAT Exemple :
Object({
"actives": Array(
[]
),
"certifications": Array(
[]
),
"currency": String(
"g1"
),
"dividend": Null,
"excluded": Array(
[]
),
"fork": Bool(
false
),
"hash": String(
"000002EFB4B9524708F751497A30811422824D14C3C710D99FBFA93F23E5BC0B"
),
"identities": Array(
[]
),
"inner_hash": String(
"00FD7CCE07B97A13F7B98B6506A9D3EE90A407E003285C664274A2B43E2778B9"
),
"issuer": String(
"FVUFRrk1K5TQGsY7PRLwqHgdHRoHrwb1hcucp4C2N5tD"
),
"issuersCount": Number(
37
),
"issuersFrame": Number(
183
),
"issuersFrameVar": Number(
3
),
"joiners": Array([]),
"leavers": Array([]),
"medianTime": Number(1528981976),
"membersCount": Number(1135),
"monetaryMass": Number(215441409),
"nonce": Number(10400000005428),
"number": Number(128238),
"parameters": String(""),
"powMin": Number(90),
"previousHash": String("000003C8220C8F2AA297AC43CF74943ADEE3EBE9715136CF5AA2CBD952AF04F3"),
"previousIssuer": String("GEWmVzmiKM6RGJsNaE7VcdNdf2T31xSnu6nHXdxuoSmd"),
"revoked": Array([]),
"signature": String("I64oQrF9bDPILLGHjw0tclgHgI75I2yIZSCS5quiXaOUd8ho2QyKrgcDNC6FhhSpyirCfLcyPCXFGDxBy/LKDw=="),
"time": Number(1528986264),
"transactions": Array([]),
"unitbase": Number(0),
"version": Number(10),
"wrong": Bool(false)
})
### getBlock
JSON Message :
......
rfc/0006_annex/bincode.md 0 → 100644
View file @ 154adda5
# Bincode serialization format for ws2pv2
Bincode is an alternative serialization format supported by nodes having "RBC" in their api features. The tables given here correspond to the successive fields in the bincode version of the messages.
## Primitive types
u8 : Unsigned 8-bit integer.
u16 : Unsigned 16-bit integer.
u32 : Unsigned 32-bit integer.
u64 : Unsigned 64-bit integer.
i8 : Signed 8-bit integer.
i16 : Signed 16-bit integer.
i32 : Signed 32-bit integer.
i64 : Signed 64-bit integer.
bool : boolean stored on 8 bits (0x00 = false, 0x01 = true, any other value must generate an error).
0 : Corresponds to data that must be filled with bits to zero (for example padding).
## Useful non-primitive types
### (T, U)
(T, U) = Tuples of 2 elements. the 1st type T and the second type U.
A tuple is simply a concatenation of types written one after the other.
A tuple can be of any size (no maximum limit), but its size is necessarily fixed.
The different elements may be of different types, but the order cannot change.
### [T; n]
Array of n elements of type T.
If the size of the array is variable, its size (in number of cells) is stored on 8 bytes.
| data | size in bytes | data type |
| :---------: | ------------: | ------------: |
| cells_count | 8 | u64 |
| content* | ?*cells_count | (T1, T2, ...) |
All cells in the table are written one after the other without a separator, _like_ a tuple of `cells_count` elements of the same type.
**/*\ CAUTION: If the size of the array is static (=a literal constant) then the array is serialized without a size field. **
For example, the content of a public key ed25519 is a 32-byte array, (a [u8; 32] therefore), it is serialized directly without a size field.
### Opt(T)
Indicates that a field is optional. The optional fields are preceded by a 1-byte boolean that indicates whether or not the field is present.
| data | size in bytes | data type |
| :-----: | ------------: | --------: |
| is_some | 1 | u8 |
| content | ? | T |
If `is_some` is equal to `1`, field `content` is present.
If `is_some` is equal to `0`, field `content` is missing.
Any other value of `is_some` is prohibited and will invalidate the entire message.
### String
String formatted in utf8 and [NFKC normalized](https://fr.wikipedia.org/wiki/Normalisation_Unicode#NFKC).
**/!\ 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 |
| :------: | ------------: | -------------: |
| str_size | 8 | u64 |
| content | str_size | [u8; str_size] |
content := String in binary utf8 with [NFKC normalization](https://fr.wikipedia.org/wiki/Normalisation_Unicode#NFKC).
If the string is empty, field `content` is missing and `str_size` is equal to zero.
### Blockstamp
| data | size in bytes | data type |
| :--------: | ------------: | --------: |
| block_id | 4 | u32 |
| block_hash | 32 | [u8; 32] |
### KeysAlgorithm
| algorithm | u32 |
| :-------: | ---: |
| Ed25519 | 0 |
| Schnorr | 1 |
### PubkeyBox
Contains the signatory's public key.
| data | size in bytes | data type |
| :-------: | ------------: | ------------: |
| algorithm | 4 | KeysAlgorithm |
| content | ? | ?* |
_*The type of field `content` depends on the algorithm. In the case of Ed25519, `content` is a 32-byte array containing the public key._
### SigBox
Contains the cryptographic signature of a document.
| data name | size in bytes | data type |
| :-------: | ------------: | ------------: |
| algorithm | 4 | KeysAlgorithm |
| content | ? | ?* |
_*The type of field `content` depends on the algorithm. In the case of Ed25519, `content` is a 64-byte array containing the signature._
## Endianness
All numbers (integers and floats) are encoded in little endian.
## Endpoint v2
| data name | size in bytes | data type |
| :--------------: | ------------: | ------------: |
| api_name | ? | String |
| api_version | 2 | u16 |
| network_features | 1 | u8 |
| api_features | 1 | u8 |
| endpoint_version | 4 | u32 |
| host | ? | Opt(String) |
| ip_v4 | 4 | Opt([u8; 4]) |
| ip_v6 | 16 | Opt([u16; 8]) |
| port | 2 | u16 |
| path | ? | Opt(String) |
## Peer card
Signed document declaring all the endpoints of a peer.
| data name | size in bytes | data type |
| :---------------: | ------------- | --------------------------- |
| version | 4 | u32 |
| currency_code | 2 | u16 |
| issuer_public_key | ? | PubkeyBox |
| node_id | 4 | u32 |
| blockstamp | 36 | Blockstamp |
| endpoints_count | 8 | u64 |
| endpoints_datas | ? | [Endpoint; endpoints_count] |
| signature | ? | SigBox |
## Messages
All messages are encapsulated in the following format :
| data name | size in bytes | data type |
| :------------: | ------------: | --------: |
| ws2p_version | 4 | u32 |
| currency_name | ? | String |
| issuer_node_id | 4 | u32 |
| issuer_pubkey | ? | PubkeyBox |
| message_type | 4 | u32 |
| payload | ? | ?* |
| signature | ? | SigBox |
### message_type
| `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 |
### CONNECT message
| data name | size in bytes | data type |
| :-----------: | ------------- | --------------- |
| challenge | 32 | [u8; 32] |
| af_size | 1 | u8 |
| api_features | af_size | WS2PFeatures |
| flags_size | 1 | u8 |
| flags_queries | flags_size | WS2PFlags |
| peer_card | ? | Peer card |
| chunkstamp | 37 | Opt(Blockstamp) |
### ACK message
| data name | size in bytes | data type |
| :-------: | ------------- | --------- |
| challenge | 32 | [u8;32] |
### SECRET FLAGS message
| data name | size in bytes | data type |
| :----------: | ------------- | ---------------- |
| flags_size | 1 | u8 |
| flags | flags_size | WS2PSecretFlags |
| member_proof | ? | Opt(MembreProof) |
MembreProof type :
| data name | size in bytes | data type |
| :-------: | ------------- | --------- |
| pubkey | ? | PubkeyBox |
| sig | ? | SigBox |
#### WS2PSecretFlags type definition
| bit | flag |
| :-------: | --------------- |
| 0000_0001 | LOW_FLOW_DEMAND |
### OK message
| data name | size in bytes | data type |
| :-------: | ------------- | --------- |
| prefix/- | 2 | u16/0 |
#### SYNC_INFO message
| data name | size in bytes | data type |
| :---------------: | --------------------- | ----------------------------- |
| chunk_size | 32 | u32 |
| target_blockstamp | 36 | Blockstamp |
| milestones_count | 8 | u64 |
| milestones | 32 × milestones_count | [Hash; milestones_count ] |
| peer_cards_count | 8 | u64 |
| peer_cards | ? × peer_cards_count | [PeerCard; peer_cards_count ] |
### KO message
| data name | size in bytes | data type |
| :-------: | ------------- | --------- |
| reason | 2 | u16 |
\ No newline at end of file
rfc/0006_ws2p_v2.md 0 → 100644
View file @ 154adda5
This diff is collapsed.
rfc/0011_pkstl_v1.md 0 → 100644
View file @ 154adda5
# Public Key Secure Transport Layer v1
This document details the specifications of PKSTL v1 (Public Key Secure Transport Layer v1).
## Contents
* [Contents](#contents)
* [FAQ](#faq)
* [What is PKSTL ?](#what-is-pkstl)
* [Why ?](#why)
* [How it works ?](#how-it-works)
* [Conventions](#conventions)
* [Endianness](#endianness)
* [Types definition](#types-definition)
* [Negotiation stage](#negotiation-stage)
* [Messages format](#messages-format)
* [CONNECT message](#connect-message)
* [ACK message](#ack-message)
* [USER message](#user-message)
## FAQ
### What is PKSTL
PKSTL (Public Key Secure Transport Layer) is a security layer that ensures the authenticity and confidentiality of communication between 2 programs over any network (Internet or local network or other).
PKSTL is agnostic to the underlying network protocol, as long as it allows the exchange of binary messages.
For example, PKSTL works with the websocket protocol but has no dependence on it.
### Prerequisites
Each of the 2 programs must have an Ed25519 key-pair. The program that initiates the connection (the client in the case of client/server communication) must first know the ed25519 public key of the server that the user wishes to contact.
### Why
The most common secure communication protocols require the generation of certificates signed by a certification authority.
It does not really work in a decentralized way, because you have to be accredited by a "certification authority". However, who decides who can be a certification authority?
In addition, the generation of certificates is either costly or requires complex and regular technical manipulations on the part of the end user of a blockchain server.
In the Duniter/G1 ecosystem, all blockchain servers have their own Ed25519 key-pair. We can use this as a basis so that we do not need certificates and therefore allow end users to have a secure server automatically (zero conf).
### How it works
The communication is symmetrically encrypted via a shared secret generated by Diffie–Hellman exchange.
The first 2 messages exchanged by the 2 programs are in clear but signed, they constitute the negotiation stage. This negotiation stage is used to generate the shared secret and verify that the other program owns the private key corresponding to its public key.
Once this negotiation stage is finalized, all exchanged messages are hashed and encrypted (the signature is no longer necessary at this stage because the hash of the message is also encrypted, so it cannot be altered undetectably by a middle man).
## Conventions
### Endianness
All numbers (integers and floats) are encoded in big endian.
### Types definition
u8 : Unsigned 8-bit integer.
u16 : Unsigned 16-bit integer.
u32 : Unsigned 32-bit integer.
u64 : Unsigned 64-bit integer.
## Negotiation stage
The negotiation stage is perfectly symmetrical, so that an observer cannot distinguish the "client" from the "server".
This allows PKSTL to be used in both peer-to-peer and client/server contexts.
Each program sends a CONNECT message and an ACK message. The ACK message is a response to the CONNECT message of the other program.
The progress of the negotiation stage can be described by 2 threads each having 3 steps.
Local thread:
1. Preparation of the CONNECT message
2. CONNECT message sent
3. A valid ACK message has been received
Remote thread:
1. Waiting for the CONNECT message from the other program
2. Receiving a valid CONNECT message
3. A valid ACK message has been sent
When the two threads reach step 3, then the negotiation stage is considered successfully completed.
### Shared secret
The shared secret is generated by Diffie-helman exchange. For security reasons, the key_pair used by each program for the DH exchange is an ephemeral key-pair, randomly generated for one-time use.
The seed for the encryption algorithm is obtained by derivation HMAC_SHA384, the salt of the HMAC function is the largest of the two ephemeral public keys.
### Encryption algorithm
The symmetric encryption algorithm is Chacha20/Poly1305.
The encryption key corresponds to the first 32 bytes of the seed.
The nonce corresponds to the next 12 bytes, and the `aad` to the last 4 bytes.
## Messages format
All messages are formatted as follows:
| Field | Size | Type | Value |
|:------------------:|:-------:|:-------:|:----------:|
| MAGIC_VALUE | 4 | - | 0xE2C2E2D2 |
| VERSION | 4 | u32 | 1 |
| ENCAPSULED_MSG_LEN | 8 | u64 | |
| MSG_TYPE | 2 | u16 | {0,1,2} |
| MSG_CONTENT | *X | [u8;X] | |
| SIGNATURE | 0 or 64 | [u8;64] | |
| HASH | 0 or 32 | [u8;32] | |
*`X = ENCAPSULED_MSG_LEN - 2`
MAGIC_VALUE := Special value to recognize that this is a message of the PKSTL protocol.
VERSION := This field allows the versioning of the PKSTL protocol and therefore future evolution.
ENCAPSULED_MSG_LEN := encapsuled message length (MSG_TYPE + MSG_CONTENT)
MSG_TYPE:
Value | Message type
:-:|:-:
0 | USER
1 | CONNECT
2 | ACK
If `MSG_TYPE == 2`, them all message is encrypted. Else, all message is in clear.
MSG_CONTENT := see details by message type
SIGNATURE := Only provided for CONNECT and ACK messages. Ed25519 signature of all previous bytes.
HASH := Only provided for USER messages. Sha256 hash of all previous bytes.
### CONNECT Message
MSG_CONTENT:
| Field | Size | Type | Value |
|:------------------:|:----:|:-------:|:----------:|
| EPK | 32 | [u8;32] | |
| SIG_ALGO | 4 | u32 | 1 |
| SIG_PUBKEY | 32 | [u8;32] | |
| CUSTOM_DATAS | *Y | [u8;Y] | |
*`Y = X - 68`
APK := Ephemeral public key.
SIG_ALGO := `1` refers to `Ed25519` algorithm. This field is present to anticipate the use of different algorithms in the future.
SIG_PUBKEY := Signature public key of remote program.
CUSTOM_DATAS := optional free user application datas (in clear).
### ACK Message
MSG_CONTENT:
| Field | Size | Type | Value |
|:------------------:|:----:|:-------:|:--------------------:|
| CHALLENGE | 32 | [u8;32] | Sha256 of remote EPK |
| CUSTOM_DATAS | *Z | [u8;Z] | |
*`Z = X - 32`
CHALLENGE := Sha256 hash of remote ephemeral public key.
CUSTOM_DATAS := optional free user application datas (in clear).
### USER Message
| Field | Size | Type | Value |
|:------------------:|:----:|:-------:|:--------------------:|
| CUSTOM_DATAS | *X | [u8;X] | |
CUSTOM_DATAS := user application datas (encrypted).
drafting in progress...