diff --git a/common/cryptomsg.c b/common/cryptomsg.c index 100f9eb12..5016fc85c 100644 --- a/common/cryptomsg.c +++ b/common/cryptomsg.c @@ -20,11 +20,12 @@ static void hkdf_two_keys(struct secret *out1, struct secret *out2, { /* BOLT #8: * - * * `HKDF(salt,ikm)`: a function is defined in [3](#reference-3), - * evaluated with a zero-length `info` field. - * * All invocations of the `HKDF` implicitly return `64-bytes` - * of cryptographic randomness using the extract-and-expand - * component of the `HKDF`. + * * `HKDF(salt,ikm)`: a function defined in + * `RFC 5869`[3](#reference-3), evaluated with a + * zero-length `info` field + * * All invocations of `HKDF` implicitly return 64 bytes of + * cryptographic randomness using the extract-and-expand component + * of the `HKDF`. */ struct secret okm[2]; @@ -42,9 +43,9 @@ static void maybe_rotate_key(u64 *n, struct secret *k, struct secret *ck) /* BOLT #8: * * A key is to be rotated after a party sends or decrypts - * `1000` messages with it. This can be properly accounted + * 1000 messages with it. This can be properly accounted * for by rotating the key once the nonce dedicated to it - * exceeds `1000`. + * exceeds 1000. */ if (*n != 1000) return; @@ -53,11 +54,11 @@ static void maybe_rotate_key(u64 *n, struct secret *k, struct secret *ck) * * Key rotation for a key `k` is performed according to the following: * - * * Let `ck` be the chaining key obtained at the end of `Act Three`. - * * `ck', k' = HKDF(ck, k)` - * * Reset the nonce for the key to `n = 0`. - * * `k = k'` - * * `ck = ck'` + * 1. Let `ck` be the chaining key obtained at the end of Act Three. + * 2. `ck', k' = HKDF(ck, k)` + * 3. Reset the nonce for the key to `n = 0`. + * 4. `k = k'` + * 5. `ck = ck'` */ hkdf_two_keys(&new_ck, &new_k, ck, k); #ifdef SUPERVERBOSE @@ -76,7 +77,7 @@ static void le64_nonce(unsigned char *npub, u64 nonce) { /* BOLT #8: * - * ...with nonce `n` encoded as 32 zero bits followed by a + * ...with nonce `n` encoded as 32 zero bits, followed by a * *little-endian* 64-bit value (this follows the Noise Protocol * convention, rather than our normal endian). */ @@ -105,10 +106,9 @@ u8 *cryptomsg_decrypt_body(const tal_t *ctx, /* BOLT #8: * - * * Decrypt `c` using `ChaCha20-Poly1305`, `rn`, and `rk` to - * obtain decrypted plaintext packet `p`. - * - * * The nonce `rn` MUST be incremented after this step. + * 5. Decrypt `c` (using `ChaCha20-Poly1305`, `rn`, and `rk`), to + * obtain decrypted plaintext packet `p`. + * * The nonce `rn` MUST be incremented after this step. */ if (crypto_aead_chacha20poly1305_ietf_decrypt(decrypted, &mlen, NULL, @@ -141,8 +141,9 @@ static struct io_plan *peer_decrypt_body(struct io_conn *conn, /* BOLT #1: * - * A node MUST ignore a received message of unknown type, if that type - * is odd. + * A receiving node: + * - upon receiving a message of _odd_, unknown type: + * - MUST ignore the received message. */ if (unlikely(is_unknown_msg_discardable(decrypted))) { pcs->in = tal_free(pcs->in); @@ -170,10 +171,9 @@ bool cryptomsg_decrypt_header(struct crypto_state *cs, u8 hdr[18], u16 *lenp) /* BOLT #8: * - * * Let the encrypted length prefix be known as `lc` - * - * * Decrypt `lc` using `ChaCha20-Poly1305`, `rn`, and `rk` to - * obtain size of the encrypted packet `l`. + * 2. Let the encrypted length prefix be known as `lc` + * 3. Decrypt `lc` (using `ChaCha20-Poly1305`, `rn`, and `rk`), to + * obtain the size of the encrypted packet `l`. * * A zero-length byte slice is to be passed as the AD * (associated data). * * The nonce `rn` MUST be incremented after this step. @@ -205,8 +205,8 @@ static struct io_plan *peer_decrypt_header(struct io_conn *conn, /* BOLT #8: * - * * Read _exactly_ `l+16` bytes from the network buffer, let - * the bytes be known as `c`. + * 4. Read _exactly_ `l+16` bytes from the network buffer, let + * the bytes be known as `c`. */ pcs->in = tal_arr(conn, u8, (u32)len + 16); return io_read(conn, pcs->in, tal_count(pcs->in), peer_decrypt_body, @@ -222,12 +222,12 @@ struct io_plan *peer_read_message(struct io_conn *conn, assert(!pcs->in); /* BOLT #8: * - * ### Decrypting Messages + * ### Receiving and Decrypting Messages * * In order to decrypt the _next_ message in the network * stream, the following is done: * - * * Read _exactly_ `18-bytes` from the network buffer. + * 1. Read _exactly_ 18 bytes from the network buffer. */ pcs->reading_body = false; pcs->in = tal_arr(conn, u8, 18); @@ -256,26 +256,28 @@ u8 *cryptomsg_encrypt_msg(const tal_t *ctx, /* BOLT #8: * - * In order to encrypt a lightning message (`m`), given a - * sending key (`sk`), and a nonce (`sn`), the following is done: + * In order to encrypt and send a Lightning message (`m`) to the + * network stream, given a sending key (`sk`) and a nonce (`sn`), the + * following is done: * + * 1. let `l = len(m)` + * * where `len` obtains the length in bytes of the Lightning + * message * - * * let `l = len(m)`, - * where `len` obtains the length in bytes of the lightning message. - * - * * Serialize `l` into `2-bytes` encoded as a big-endian integer. + * 2. Serialize `l` into 2 bytes encoded as a big-endian integer. */ l = cpu_to_be16(mlen); /* BOLT #8: * - * * Encrypt `l` using `ChaChaPoly-1305`, `sn`, and `sk` to obtain `lc` - * (`18-bytes`) - * * The nonce `sn` is encoded as a 96-bit little-endian number. - * As our decoded nonces a 64-bit, we encode the 96-bit nonce as - * follows: 32-bits of leading zeroes followed by a 64-bit value. - * * The nonce `sn` MUST be incremented after this step. - * * A zero-length byte slice is to be passed as the AD + * 3. Encrypt `l` (using `ChaChaPoly-1305`, `sn`, and `sk`), to obtain + * `lc` (18 bytes) + * * The nonce `sn` is encoded as a 96-bit little-endian number. As + * the decoded nonce is 64 bits, the 96-bit nonce is encoded as: + * 32 bits of leading zeroes followed by a 64-bit value. + * * The nonce `sn` MUST be incremented after this step. + * * A zero-length byte slice is to be passed as the AD (associated + data). */ le64_nonce(npub, cs->sn++); ret = crypto_aead_chacha20poly1305_ietf_encrypt(out, &clen, @@ -297,9 +299,9 @@ u8 *cryptomsg_encrypt_msg(const tal_t *ctx, /* BOLT #8: * - * * Finally encrypt the message itself (`m`) using the same - * procedure used to encrypt the length prefix. Let - * encrypted ciphertext be known as `c`. + * 4. Finally, encrypt the message itself (`m`) using the same + * procedure used to encrypt the length prefix. Let + * encrypted ciphertext be known as `c`. * * * The nonce `sn` MUST be incremented after this step. */ @@ -376,7 +378,7 @@ struct io_plan *peer_write_message(struct io_conn *conn, #endif /* DEVELOPER */ /* BOLT #8: - * * Send `lc || c` over the network buffer. + * 5. Send `lc || c` over the network buffer. */ return io_write(conn, pcs->out, tal_count(pcs->out), post, pcs); }