Merge branch 'main' into JobDeclarator

4ss0 · web-flow · commit 418762a8b89e · 2023-06-22T20:34:45.000+02:00
diff --git a/03-Protocol-Overview.md b/03-Protocol-Overview.md
@@ -103,6 +103,7 @@ The message framing is outlined below:
 | msg_length     | U24         | Length of the protocol message, not including this header                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | payload        | BYTES       | Message-specific payload of length msg_length. If the MSB in extension_type (the channel_msg bit) is set the first four bytes are defined as a U32 "channel_id", though this definition is repeated in the message definitions below and these 4 bytes are included in msg_length.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
+
 ## 3.3 Reconnecting Downstream Nodes
 
 An upstream stratum node may occasionally request reconnection of its downstream peers to a different host (e.g. due to maintenance reasons, etc.).
@@ -162,7 +163,7 @@ Clients that are not configured to provide telemetry data to the upstream node S
 However, they MUST always set vendor to a string describing the manufacturer/developer and firmware version and SHOULD always set `hardware_version` to a string describing, at least, the particular hardware/software package in use.
 
 | Field Name         | Data Type | Description                                                                                                                 |
-| ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------- |
+|--------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------|
 | protocol           | U8        | 0 = Mining Protocol <br>1 = Job Negotiaion <br>2 = Template Distribution Protocol <br> 3 = Job Distribution Protocol        |
 | min_version        | U16       | The minimum protocol version the client supports (currently must be 3)                                                      |
 | max_version        | U16       | The maximum protocol version the client supports (currently must be 3)                                                      |
@@ -182,7 +183,7 @@ Response to `SetupConnection` message if the server accepts the connection.
 The client is required to verify the set of feature flags that the server supports and act accordingly.
 
 | Field Name   | Data Type | Description                                                                                                                                             |
-| ------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|--------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
 | used_version | U16       | Selected version proposed by the connecting node that the upstream node supports. This version will be used on the connection for the rest of its life. |
 | flags        | U32       | Flags indicating optional protocol features the server supports. Each protocol from protocol field has its own values/flags.                            |
 
diff --git a/04-Protocol-Security.md b/04-Protocol-Security.md
@@ -331,29 +331,67 @@ If the server provides a non-empty `CIPHER_CHOICE`:
 2. New keys `key_new` are derived from the original CipherState keys `key_orig` by taking the first 32 bytes from `ENCRYPT(key_orig, maxnonce, zero_len, zeros)` using the negotiated cipher function where `maxnonce` is 2<sup>64</sup> - 1, `zerolen` is a zero-length byte sequence, and `zeros` is a sequence of 32 bytes filled with zeros. (see `Rekey(k)` function<sup>[8](#reference-8)</sup>)
 3. New CipherState objects are reinitialized: `InitializeKey(key_new)`.
 
-### 4.5.6 Transport message encryption and format
-
-After handshake process is finished, both initiator and responder have CipherState objects for encryption and decryption and after initiator validated server's identity, any subsequent traffic is encrypted and decrypted with `EncryptWithAd()` and `DecryptWithAd()` methods of the respectrive CipherState objects with zero-length associated data.
-
-Ciphertext is sent in `NOISE_FRAME` over the wire.
-
-##### NOISE_FRAME
-| Field Name | Data Type | Description |
-| ---------- | --------- | ----------- |
-| ciphertext | B0_64K | AEAD ciphertext including 16 bytes MAC |
-
-Message length: `<Plaintext length> + 18 bytes = <Plaintext length> + <MAC length> + <Type length prefix>`
-
-Maximum message length = 65537 bytes
-Maximum ciphertext length = 65535 bytes
-Maximum plaintext length 65519 bytes
+## 4.6 Encrypted stratum message framing
+
+After handshake process is finished, both initiator and responder have CipherState objects for encryption and decryption and after initiator validated server's identity, any subsequent traffic is encrypted and decrypted with `EncryptWithAd()` and `DecryptWithAd()` methods of the respective CipherState objects with zero-length associated data.
+
+Maximum transport message length (ciphertext) is for noise protocol message 65535 bytes.
+
+Since Stratum Message Frame consists of
+- fixed length message header: 6 bytes
+- variable length serialized stratum message
+
+Stratum Message header and stratum message payload are processed separately.
+
+#### Encrypting stratum message
+1. serialize stratum message into a plaintext binary string (payload)
+2. prepare frame header for the stratum message with `message_length` being length of payload ciphertext*
+3. Encrypt and concatenate serialized header and payload:
+   4. `EncryptWithAd([], header)` - 22 bytes
+   5. `EncryptWithAd([], payload)` - variable length encrypted message
+4. concatenate resulting header and payload ciphertext
+
+*converting plaintext length to ciphertext length:
+```c
+#define MAX_CT_LEN 65535
+#define MAC_LEN 16
+#define MAX_PT_LEN (MAX_CT_LEN - MAC_LEN)
+
+uint pt_len_to_ct_len(uint pt_len) {
+        uint remainder;
+        remainder = pt_len % MAX_PT_LEN;
+        if (remainder > 0) {
+                remainder += MAC_LEN;
+        }
+        return pt_len / MAX_PT_LEN * MAX_CT_LEN + remainder;
+}
+```
 
-Note that in regard to Stratum V2 message, `NOISE_FRAME` doesn't necessarily need to contain to exactly one encrypted Stratum message. Ciphertext payload may contain multiple subsequent messages or even only partial message. Examples:
+#### Decrypting stratum message
+1. read exactly 22 bytes and decrypt into stratum frame or fail
+2. read `frame.message_length` number of bytes and decrypt into plaintext payload or fail
+3. deserialize plaintext payload into stratum message given by `frame.extension_type` and `frame.message_type` or fail
 
-- `OpenStandardMiningChannelSuccess` followed immediately with `NewMiningJob`
-- Arbitrary message containing `B0_16M` type, since the noise ciphertext can be at most `2**16 - 1 == 65535` bytes long
+#### Encrypted stratum message frame layout
+```
++--------------------------------------------------+-------------------------------------------------------------------+
+| Extended noise header                            | Encrypted stratum-message payload                                 |
++--------------------------------------------------+-------------------+-------------------+---------------------------+
+| Header AEAD ciphertext                           | Noise block 1     | Noise block 2     | Last Noise block          |
+| 22 Bytes                                         | 65535 Bytes       | 65535 Bytes       | 17 - 65535 Bytes          |
++----------------------------------------+---------+-----------+-------+-----------+-------+---------------+-----------+
+| Encrypted Stratum message Header       | MAC     | ct_pld_1  | MAC_1 | ct_pld_2  | MAC_2 | ct_pld_rest   | MAC_rest  |
+| 6 Bytes                                | 16 B    | 65519 B   | 16 B  | 65519 B   | 16 B  | 1 - 65519 B   | 16 Bytes  |
++================+==========+============+=========+===========+=======+===========+=======+===============+===========+
+| extension_type | msg_type | pld_length | <padd   | pt_pld_1  | <padd | pt_pld_2  | <padd | pt_pld_rest   | <padding> |
+| U16            | U8       | U24        |   ing>  | 65519 B   |  ing> | 65519 B   |  ing> | 1 - 65519 B   |           |
++----------------+----------+------------+---------+-------------------------------------------------------------------+
+
+Serialized stratum-v2 body (payload) is split into 65519-byte chunks and encrypted to form 65535-bytes AEAD ciphertexts,
+where `ct_pld_N` is the N-th ciphertext block of payload and `pt_pld_N` is the N-th plaintext block of payload.
+```
 
-## 4.6 URL Scheme and Pool Authority Key
+## 4.7 URL Scheme and Pool Authority Key
 
 Downstream nodes that want to use the above outlined security scheme need to have configured the **Pool Authority Public Key** of the pool that they intend to connect to. It is provided by the target pool and communicated to its users via a trusted channel.
 At least, it can be published on the pool's public website.
@@ -374,7 +412,7 @@ stratum2+tcp://thepool.com/9bXiEd8boQVhq7WddEcERUL5tyyJVFYdU8th3HfbNXK3Yw6GRXh
 
 ```
 
-### 4.6.1 Test vector:
+### 4.7.1 Test vector:
 
 ```
 
@@ -383,7 +421,7 @@ prefixed_base58check = "9bXiEd8boQVhq7WddEcERUL5tyyJVFYdU8th3HfbNXK3Yw6GRXh"
 
 ```
 
-## 4.7 References
+## 4.8 References
 
 1. <a id="reference-1"> https://web.cs.ucdavis.edu/~rogaway/papers/ad.pdf</a>
 2. <a id="reference-2"> https://www.secg.org/sec2-v2.pdf</a>
diff --git a/07-Template-Distribution-Protocol.md b/07-Template-Distribution-Protocol.md
@@ -17,7 +17,7 @@ Thus, this message is used to indicate that some additional space in the block/c
 
 The Job Declarator MUST discover the maximum serialized size of the additional outputs which will be added by the pool(s) it intends to use this work.
 It then MUST communicate the maximum such size to the Template Provider via this message.
-The Template Provider MUST NOT provide `NewWork` messages which would represent consensus-invalid blocks once this additional size — along with a maximally-sized (100 byte) coinbase field — is added.
+The Template Provider MUST NOT provide `NewMiningJob` messages which would represent consensus-invalid blocks once this additional size — along with a maximally-sized (100 byte) coinbase field — is added.
 Further, the Template Provider MUST consider the maximum additional bytes required in the output count variable-length integer in the coinbase transaction when complying with the size limits.
 
 | Field Name                          | Data Type | Description                                                                                     |
@@ -45,7 +45,7 @@ The primary template-providing function. Note that the `coinbase_tx_outputs` byt
 ## 7.3 `SetNewPrevHash` (Server -> Client)
 
 Upon successful validation of a new best block, the server MUST immediately provide a `SetNewPrevHash` message.
-If a `NewWork` message has previously been sent with an empty `min_ntime`, which is valid work based on the `prev_hash` contained in this message, the `template_id` field SHOULD be set to the `job_id` present in that `NewTemplate` message indicating the client MUST begin mining on that template as soon as possible.
+If a `NewMiningJob` message has previously been sent with an empty `min_ntime`, which is valid work based on the `prev_hash` contained in this message, the `template_id` field SHOULD be set to the `job_id` present in that `NewTemplate` message indicating the client MUST begin mining on that template as soon as possible.
 
 TODO: Define how many previous works the client has to track (2? 3?), and require that the server reference one of those in `SetNewPrevHash`.
 
@@ -105,7 +105,7 @@ Upon finding a coinbase transaction/nonce pair which double-SHA256 hashes at or
 | Field Name       | Data Type | Description                                                                                                                                                                                                                                    |
 | ---------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | template_id      | U64       | The template_id field as it appeared in NewTemplate                                                                                                                                                                                            |
-| version          | U32       | The version field in the block header. Bits not defined by BIP320 as additional nonce MUST be the same as they appear in the NewWork message, other bits may be set to any value.                                                              |
+| version          | U32       | The version field in the block header. Bits not defined by BIP320 as additional nonce MUST be the same as they appear in the NewMiningJob message, other bits may be set to any value.                                                              |
 | header_timestamp | U32       | The nTime field in the block header. This MUST be greater than or equal to the header_timestamp field in the latest SetNewPrevHash message and lower than or equal to that value plus the number of seconds since the receipt of that message. |
 | header_nonce     | U32       | The nonce field in the header                                                                                                                                                                                                                  |
-| coinbase_tx      | B0_64K    | The full serialized coinbase transaction, meeting all the requirements of the NewWork message, above                                                                                                                                           |
+| coinbase_tx      | B0_64K    | The full serialized coinbase transaction, meeting all the requirements of the NewMiningJob message, above                                                                                                                                           |
diff --git a/img/4.3.a-Mining-Protocol-Messages-Initialization.png b/img/4.3.a-Mining-Protocol-Messages-Initialization.png
