mirror of
https://github.com/lightning/bolts.git
synced 2024-11-19 10:00:04 +01:00
7c884f2af4
Major changes: 1. Move crypto first, then cover contents 2. Use "lightning messages" explicitly to refer to upper layer, use "packet" in the one case where we refer to the whole thing. 3. Collapse "Transport Message Exchange" and "Protocol Message Encapsulation" into "Lightning Message Specification" which already contains much overlap. Minor changes: 1. Put the big-endian requirement in the general overview, since the crypto layer uses that too. 2. Say "is" instead of "should be" encrypted: it's not an option. 3. Note why we separate local and global features. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
812 lines
26 KiB
Markdown
812 lines
26 KiB
Markdown
# BOLT #1: Message Format, Encryption, Authentication and Initialization
|
|
|
|
All communications between Lightning nodes is encrypted in order to
|
|
provide confidentiality for all transcripts between nodes, and authenticated to
|
|
avoid malicious interference. Each node has a known long-term identifier which
|
|
is a public key on Bitcoin's `secp256k1` curve. This long-term public key is
|
|
used within the protocol to establish an encrypted+authenticated connection
|
|
with peers, and also to authenticate any information advertised on the behalf
|
|
of a node.
|
|
|
|
## Communication Protocols
|
|
|
|
This protocol is written with TCP in mind, but could use any ordered,
|
|
reliable transport.
|
|
|
|
The default TCP port is `9735`. This corresponds to hexadecimal `2607`,
|
|
the unicode code point for LIGHTNING.<sup>[2](#reference-2)</sup>
|
|
|
|
All data fields are big-endian unless otherwise specified.
|
|
|
|
## Cryptographic Messaging Overview
|
|
|
|
Prior to sending any lightning messages, nodes must first initiate the
|
|
cryptographic session state which is used to encrypt and authenticate all
|
|
messages sent between nodes. The initialization of this cryptographic session
|
|
state is completely distinct from any inner protocol message header or
|
|
conventions.
|
|
|
|
The transcript between two nodes is separated into two distinct segments:
|
|
|
|
1. First, before any actual data transfer, both nodes participate in an
|
|
authenticated key agreement protocol which is based off of the Noise
|
|
Protocol Framework<sup>[4](#reference-4)</sup>.
|
|
2. If the initial handshake is successful, then nodes enter the lightning
|
|
message exchange phase. In the lightning message exchange phase, all
|
|
messages are `AEAD` ciphertexts.
|
|
|
|
### Authenticated Key Agreement Handshake
|
|
|
|
The handshake chosen for the authenticated key exchange is `Noise_XK`. As a
|
|
"pre-message", we assume that the initiator knows the identity public key of
|
|
the responder. This handshake provides a degree of identity hiding for the
|
|
responder, its public key is _never_ transmitted during the handshake. Instead,
|
|
authentication is achieved implicitly via a series of `ECDH` (Elliptic-Curve
|
|
Diffie-Hellman) operations followed by a `MAC` check.
|
|
|
|
The authenticated key agreement (`Noise_XK`) is performed in three distinct
|
|
steps. During each "act" of the handshake, some (possibly encrypted) keying
|
|
material is sent to the other party, an `ECDH` is performed based on exactly
|
|
which act is being executed with the result mixed into the current sent of
|
|
encryption keys (`ck` the chainin gkey and `k` the encryption key), and finally
|
|
an `AEAD` payload with a zero length cipher text is sent. As this payload is
|
|
of length zero, only a `MAC` is sent across. The mixing of `ECDH` outputs into
|
|
a hash digest forms an incremental TripleDH handshake.
|
|
|
|
Using the language of the Noise Protocol, `e` and `s` (both public keys)
|
|
indicate possibly encrypted keying material, and `es, ee, se` each indicate an
|
|
`ECDH` operation between two keys. The handshake is laid out as follows:
|
|
|
|
Noise_XK(s, rs):
|
|
<- s
|
|
...
|
|
-> e, es
|
|
<- e, ee
|
|
-> s, se
|
|
|
|
All of the handshake data sent across the wire including the keying material is
|
|
incrementally hashed into a session-wide "handshake digest", `h`. Note that the
|
|
handshake state `h`, is never transmitted during the handshake, instead digest
|
|
is used as the Authenticated Data within the zero-length AEAD messages.
|
|
|
|
By authenticating each message sent, we can ensure that a MiTM hasn't modified
|
|
or replaced any of the data sent across as part of a handshake, as the MAC
|
|
check would fail on the other side if so.
|
|
|
|
A successful check of the `MAC` by the receiver indicates implicitly that all
|
|
authentication has been successful up to that point. If `MAC` check ever fails
|
|
during the handshake process, then the connection is to be immediately
|
|
terminated.
|
|
|
|
## Handshake Versioning
|
|
|
|
Each message sent during the initial handshake starts with a single leading
|
|
byte which indicates the version used for the current handshake. A version of 0
|
|
indicates that no change is necessary, while a non-zero version indicate the
|
|
client has deviated from the protocol originally specified within this
|
|
document. Clients MUST reject handshake attempts initiated with an unknown
|
|
version.
|
|
|
|
### Noise Protocol Instantiation
|
|
|
|
Concrete instantiations of the Noise Protocol require the definition of
|
|
three abstract cryptographic objects: the hash function, the elliptic curve,
|
|
and finally the `AEAD` cipher scheme. Within our instantiation `SHA-256` is
|
|
chosen as the hash function, `secp256k1` as the elliptic curve, and finally
|
|
`ChaChaPoly-1305` as the `AEAD` construction. The composition of `ChaCha20`
|
|
and `Poly1305` used MUST conform to `RFC 7539`<sup>[3](#reference-3)</sup>. With this laid out, the
|
|
official Noise protocol name for our variant is:
|
|
`Noise_XK_secp256k1_ChaChaPoly_SHA256`. The ascii string representation of
|
|
this value is hashed into a digest used to initialize the starting handshake
|
|
state. If the protocol names of two endpoints differs, then the handshake
|
|
process fails immediately.
|
|
|
|
|
|
## Authenticated Key Exchange Handshake Specification
|
|
|
|
The handshake proceeds in three acts, taking 1.5 round trips. Each handshake is
|
|
a _fixed_ sized payload without any header or additional meta-data attached.
|
|
The exact size of each Act is as follows:
|
|
|
|
* **Act One**: `50 bytes`
|
|
* **Act Two**: `50 bytes`
|
|
* **Act Three**: `66 bytes`
|
|
|
|
### Handshake State
|
|
|
|
Throughout the handshake process, each side maintains these three variables:
|
|
|
|
* `ck`: The **chaining key**. This value is the accumulated hash of all
|
|
previous ECDH outputs. At the end of the handshake, `ck` is used to derive
|
|
the encryption keys for lightning messages.
|
|
|
|
* `h`: The **handshake hash**. This value is the accumulated hash of _all_
|
|
handshake data that has been sent and received so far during the handshake
|
|
process.
|
|
|
|
* `temp_k`: An **intermediate key** key used to encrypt/decrypt the
|
|
zero-length AEAD payloads at the end of each handshake message.
|
|
|
|
* `n`: A **counter-based nonce** which is to be used with `temp_k` to encrypt
|
|
each message with a new nonce.
|
|
|
|
* `e`: A party's **ephemeral public key**. For each session a node MUST generate a
|
|
new ephemeral key with strong cryptographic randomness.
|
|
|
|
* `s`: A party's **static public key**.
|
|
|
|
The following functions will also be referenced:
|
|
|
|
* `ECDH(rk, k)`: Performs an Elliptic-Curve Diffie-Hellman operation using
|
|
`rk` which is a `secp256k1` public key and `k` which is a valid private key
|
|
within the finite field as defined by the curve paramters.
|
|
* The returned value is the raw big-endian byte serialization of
|
|
`x-coordinate` (using affine coordinates) of the generated point.
|
|
|
|
* `HKDF`: 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.
|
|
|
|
* `encryptWithAD(k, n, ad, plaintext)`: outputs `encrypt(k, n++, ad, plaintext)`
|
|
* where `encrypt` is an evaluation of `ChaCha20-Poly1305` with the passed
|
|
arguments.
|
|
|
|
* `decryptWithAD(k, n, ad, ciphertext)`: outputs `decrypt(k, n++, ad, ciphertext)`
|
|
* where `decrypt` is an evaluation of `ChaCha20-Poly1305` with the passed
|
|
arguments.
|
|
|
|
* `generateKey()`
|
|
* where generateKey generates and returns a fresh `secp256k1` keypair
|
|
* the object returned by `generateKey` has two attributes:
|
|
* `.pub`: which returns an abstract object representing the public key
|
|
* `.priv`: which represents the private key used to generate the
|
|
public key
|
|
* the object also has a single method:
|
|
* `.serializeCompressed()`
|
|
|
|
* `a || b` denotes the concatenation of two byte strings `a` and `b`
|
|
|
|
|
|
### Handshake State Initialization
|
|
|
|
Before the start of the first act, both sides initialize their per-sessions
|
|
state as follows:
|
|
|
|
1. `h = SHA-256(protocolName)`
|
|
* where `protocolName = "Noise_XK_secp256k1_ChaChaPoly_SHA256"` encoded as
|
|
an ascii string.
|
|
|
|
2. `ck = h`
|
|
|
|
|
|
3. `temp_k = empty`
|
|
* where `empty` is a byte string of length 32 fully zeroed out.
|
|
|
|
|
|
4. `n = 0`
|
|
|
|
|
|
5. `h = SHA-256(h || prologue)`
|
|
* where `prologue` is the ascii string: `lightning`.
|
|
|
|
|
|
As a concluding step, both sides mix the responder's public key into the
|
|
handshake digest:
|
|
|
|
|
|
* The initiating node mixes in the responding node's static public key
|
|
serialized in Bitcoin's DER compressed format:
|
|
* `h = SHA-256(h || rs.pub.serializeCompressed())`
|
|
|
|
|
|
* The responding node mixes in their local static public key serialized in
|
|
Bitcoin's DER compressed format:
|
|
* `h = SHA-256(h || ls.pub.serializeCompressed())`
|
|
|
|
|
|
### Handshake Exchange
|
|
|
|
|
|
#### Act One
|
|
|
|
|
|
```
|
|
-> e, es
|
|
```
|
|
|
|
|
|
Act One is sent from initiator to responder. During `Act One`, the initiator
|
|
attempts to satisfy an implicit challenge by the responder. To complete this
|
|
challenge, the initiator _must_ know the static public key of the responder.
|
|
|
|
|
|
The handshake message is _exactly_ `50 bytes`: `1 byte` for the handshake
|
|
version, `33 bytes` for the compressed ephemeral public key of the initiator,
|
|
and `16 bytes` for the `poly1305` tag.
|
|
|
|
|
|
**Sender Actions:**
|
|
|
|
|
|
* `e = generateKey()`
|
|
|
|
|
|
* `h = SHA-256(h || e.pub.serializeCompressed())`
|
|
* The newly generated ephemeral key is accumulated into our running
|
|
handshake digest.
|
|
|
|
|
|
* `s = ECDH(rs, e.priv)`
|
|
* The initiator performs a `ECDH` between its newly generated ephemeral
|
|
key with the remote node's static public key.
|
|
|
|
|
|
* `ck, temp_k = HKDF(ck, s)`
|
|
* This phase generates a new temporary encryption key (`temp_k`) which is
|
|
used to generate the authenticating MAC.
|
|
* The nonce `n` should be reset to zero: `n = 0`.
|
|
|
|
|
|
* `c = encryptWithAD(temp_k, n, h, zero)`
|
|
* where `zero` is a zero-length plaintext
|
|
|
|
|
|
* `h = SHA-256(h || c)`
|
|
* Finally, the generated ciphertext is accumulated into the authenticating
|
|
handshake digest.
|
|
|
|
|
|
* Send `m = 0 || e || c` to the responder over the network buffer.
|
|
|
|
|
|
**Receiver Actions:**
|
|
|
|
|
|
* Read _exactly_ `50-bytes` from the network buffer.
|
|
|
|
|
|
* Parse out the read message (`m`) into `v = m[0]`, `e = m[1:34]` and `c = m[43:]`
|
|
* where `m[0]` is the _first_ byte of `m`, `m[1:33]` are the next `33`
|
|
bytes of `m` and `m[34:]` is the last 16 bytes of `m`
|
|
* The raw bytes of the remote party's ephemeral public key (`e`) are to be
|
|
deserialized into a point on the curve using affine coordinates as encoded
|
|
by the key's serialized composed format.
|
|
|
|
|
|
* If `v` is an unrecognized handshake version, then the responder MUST
|
|
abort the connection attempt.
|
|
|
|
|
|
* `h = SHA-256(h || e.pub.serializeCompressed())`
|
|
* Accumulate the initiator's ephemeral key into the authenticating
|
|
handshake digest.
|
|
|
|
* `s = ECDH(e, s.priv)`
|
|
* The responder performs an `ECDH` between its static public key and the
|
|
initiator's ephemeral public key.
|
|
|
|
|
|
* `ck, temp_k = HKDF(ck, s)`
|
|
* This phase generates a new temporary encryption key (`temp_k`) which will
|
|
be used to shortly check the authenticating MAC.
|
|
* The nonce `n` should be reset to zero: `n = 0`.
|
|
|
|
* `p = decryptWithAD(temp_k, n, h, c)`
|
|
* If the MAC check in this operation fails, then the initiator does _not_
|
|
know our static public key. If so, then the responder MUST terminate the
|
|
connection without any further messages.
|
|
|
|
|
|
* `h = SHA-256(h || c)`
|
|
* Mix the received ciphertext into the handshake digest. This step serves
|
|
to ensure the payload wasn't modified by a MiTM.
|
|
|
|
|
|
|
|
|
|
#### Act Two
|
|
```
|
|
<- e, ee
|
|
```
|
|
|
|
`Act Two` is sent from the responder to the initiator. `Act Two` will _only_
|
|
take place if `Act One` was successful. `Act One` was successful if the
|
|
responder was able to properly decrypt and check the `MAC` of the tag sent at
|
|
the end of `Act One`.
|
|
|
|
The handshake is _exactly_ `50 bytes:` `1 byte` for the handshake version, `33
|
|
bytes` for the compressed ephemeral public key of the initiator, and `16 bytes`
|
|
for the `poly1305` tag.
|
|
|
|
**Sender Actions:**
|
|
|
|
|
|
* `e = generateKey()`
|
|
|
|
|
|
* `h = SHA-256(h || e.pub.serializeCompressed())`
|
|
* The newly generated ephemeral key is accumulated into our running
|
|
handshake digest.
|
|
|
|
|
|
* `s = ECDH(re, e.priv)`
|
|
* where `re` is the ephemeral key of the initiator which was received
|
|
during `ActOne`.
|
|
|
|
|
|
* `ck, temp_k = HKDF(ck, s)`
|
|
* This phase generates a new temporary encryption key (`temp_k`) which is
|
|
used to generate the authenticating MAC.
|
|
* The nonce `n` should be reset to zero: `n = 0`.
|
|
|
|
|
|
* `c = encryptWithAD(temp_k, n, h, zero)`
|
|
* where `zero` is a zero-length plaintext
|
|
|
|
|
|
* `h = SHA-256(h || c)`
|
|
* Finally, the generated ciphertext is accumulated into the authenticating
|
|
handshake digest.
|
|
|
|
* Send `m = 0 || e || c` to the initiator over the network buffer.
|
|
|
|
|
|
**Receiver Actions:**
|
|
|
|
|
|
* Read _exactly_ `50-bytes` from the network buffer.
|
|
|
|
|
|
* Parse out the read message (`m`) into `v = m[0]`, e = m[1:34]` and `c = m[43:]`
|
|
* where `m[0]` is the _first_ byte of `m`, `m[1:33]` are the next `33`
|
|
bytes of `m` and `m[34:]` is the last 16 bytes of `m`
|
|
|
|
|
|
* If `v` is an unrecognized handshake version, then the responder MUST
|
|
abort the connection attempt.
|
|
|
|
|
|
* `h = SHA-256(h || e.pub.serializeCompressed())`
|
|
|
|
|
|
* `s = ECDH(re, e.priv)`
|
|
* where `re` is the responder's ephemeral public key.
|
|
* The raw bytes of the remote party's ephemeral public key (`e`) are to be
|
|
deserialized into a point on the curve using affine coordinates as encoded
|
|
by the key's serialized composed format.
|
|
|
|
|
|
* `ck, temp_k = HKDF(ck, s)`
|
|
* This phase generates a new temporary encryption key (`temp_k`) which is
|
|
used to generate the authenticating MAC.
|
|
* The nonce `n` should be reset to zero: `n = 0`.
|
|
|
|
|
|
* `p = decryptWithAD(temp_k, n, h, c)`
|
|
* If the MAC check in this operation fails, then the initiator MUST
|
|
terminate the connection without any further messages.
|
|
* The nonce `n` should be reset to zero: `n = 0`.
|
|
|
|
|
|
* `h = SHA-256(h || c)`
|
|
* Mix the received ciphertext into the handshake digest. This step serves
|
|
to ensure the payload wasn't modified by a MiTM.
|
|
|
|
|
|
#### Act Three
|
|
```
|
|
-> s, se
|
|
```
|
|
|
|
|
|
`Act Three` is the final phase in the authenticated key agreement described in
|
|
this section. This act is sent from the initiator to the responder as a final
|
|
concluding step. `Act Three` is only executed `iff` `Act Two` was successful.
|
|
During `Act Three`, the initiator transports its static public key to the
|
|
responder encrypted with _strong_ forward secrecy using the accumulated `HKDF`
|
|
derived secret key at this point of the handshake.
|
|
|
|
|
|
The handshake is _exactly_ `66 bytes`: `1 byte` for the handshake version, `33
|
|
bytes` for the ephemeral public key encrypted with the `ChaCha20` stream
|
|
cipher, `16 bytes` for the encrypted public key's tag generated via the `AEAD`
|
|
construction, and `16 bytes` for a final authenticating tag.
|
|
|
|
|
|
**Sender Actions:**
|
|
|
|
|
|
* `c = encryptWithAD(temp_k, n, h, s.pub.serializeCompressed())`
|
|
* where `s` is the static public key of the initiator.
|
|
|
|
|
|
* `h = SHA-256(h || c)`
|
|
|
|
|
|
* `s = ECDH(re, s.priv)`
|
|
* where `re` is the ephemeral public key of the responder.
|
|
|
|
|
|
* `ck, temp_k = HKDF(ck, s)`
|
|
* Mix the final intermediate shared secret into the running chaining key.
|
|
* The nonce `n` should be reset to zero: `n = 0`.
|
|
|
|
|
|
* `t = encryptWithAD(temp_k, n, h, zero)`
|
|
* where `zero` is a zero-length plaintext
|
|
|
|
|
|
* `sk, rk = HKDF(ck, zero)`
|
|
* where `zero` is a zero-length plaintext,
|
|
|
|
|
|
`sk` is the key to be used by the initiator to encrypt messages to the
|
|
responder,
|
|
|
|
|
|
and `rk` is the key to be used by the initiator to decrypt messages sent by
|
|
the responder.
|
|
|
|
* This step generates the final encryption keys to be used for sending and
|
|
receiving messages for the duration of the session.
|
|
|
|
|
|
* Send `m = 0 || c || t` over the network buffer.
|
|
|
|
|
|
**Receiver Actions:**
|
|
|
|
|
|
* Read _exactly_ `66-bytes` from the network buffer.
|
|
|
|
|
|
* Parse out the read message (`m`) into `v = m[0]`, `c = m[1:50]` and `t = m[50:]`
|
|
|
|
|
|
* If `v` is an unrecognized handshake version, then the responder MUST
|
|
abort the connection attempt.
|
|
|
|
|
|
* `rs = decryptWithAD(temp_k, n, h, c)`
|
|
* At this point, the responder has recovered the static public key of the
|
|
initiator.
|
|
|
|
|
|
* `h = SHA-256(h || rs.pub.serializeCompressed())`
|
|
|
|
|
|
* `s = ECDH(rs, e.priv)`
|
|
* where `e` is the responder's original ephemeral key
|
|
|
|
* `ck, temp_k = HKDF(ck, s)`
|
|
* The underscore denots that the final `32-bytes` generated by the `HKDF`
|
|
invocation are discarded.
|
|
* The nonce `n` should be reset to zero: `n = 0`.
|
|
|
|
* `p = decryptWithAD(temp_k, n, h, t)`
|
|
* If the MAC check in this operation fails, then the responder MUST
|
|
terminate the connection without any further messages.
|
|
|
|
|
|
* `rk, sk = HKDF(ck, zero)`
|
|
* where `zero` is a zero-length plaintext,
|
|
|
|
|
|
`rk` is the key to be used by the responder to decrypt the messages sent
|
|
by the responder,
|
|
|
|
|
|
and `sk` is the key to be used by the initiator to encrypt messages to
|
|
the responder,
|
|
|
|
* This step generates the final encryption keys to be used for sending and
|
|
receiving messages for the duration of the session.
|
|
|
|
## Lightning Message Specification
|
|
|
|
At the conclusion of `Act Three` both sides have derived the encryption keys
|
|
which will be used to encrypt/decrypt messages for the remainder of the
|
|
session.
|
|
|
|
The actual lightning protocol messages are encapsulated within `AEAD` ciphertexts. Each message is prefixed with
|
|
another `AEAD` ciphertext which encodes the total length of the following lightning
|
|
message (not counting its MAC).
|
|
|
|
The *maximum* size of _any_ lightning message MUST NOT exceed `65535` bytes. A
|
|
maximum size of `65535` simplifies testing, makes memory management
|
|
easier and helps mitigate memory exhaustion attacks.
|
|
|
|
In order to make make traffic analysis more difficult, the length prefix for
|
|
all encrypted lightning messages is also encrypted. Additionally we add a
|
|
`16-byte` `Poly-1305` tag to the encrypted length prefix in order to ensure
|
|
that the packet length hasn't been modified with in-flight, and also to avoid
|
|
creating a decryption oracle.
|
|
|
|
The structure of packets on the wire resembles the following:
|
|
```
|
|
+-------------------------------
|
|
|2-byte encrypted message length|
|
|
+-------------------------------
|
|
| 16-byte MAC of the encrypted |
|
|
| message length |
|
|
+-------------------------------
|
|
| |
|
|
| |
|
|
| encrypted lightning |
|
|
| message |
|
|
| |
|
|
+-------------------------------
|
|
| 16-byte MAC of the |
|
|
| lightning message |
|
|
+-------------------------------
|
|
```
|
|
The prefixed message length is encoded as a `2-byte` big-endian integer,
|
|
for a total maximum packet length of `2 + 16 + 65535 + 16` = `65569` bytes.
|
|
|
|
### Encrypting Messages
|
|
|
|
|
|
In order to encrypt a lightning message (`m`), given a sending key (`sk`), and a nonce
|
|
(`n`), the following is done:
|
|
|
|
|
|
* 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.
|
|
|
|
|
|
* Encrypt `l` using `ChaChaPoly-1305`, `n`, and `sk` to obtain `lc`
|
|
(`18-bytes`)
|
|
* The nonce for `sk` MUST be incremented after this step.
|
|
* A zero-length byte slice is to be passed as the AD (associated data).
|
|
|
|
|
|
* 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 for `sk` MUST be incremented after this step.
|
|
|
|
* Send `lc || c` over the network buffer.
|
|
|
|
|
|
### 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.
|
|
|
|
|
|
* Let the encrypted length prefix be known as `lc`
|
|
|
|
|
|
* Decrypt `lc` using `ChaCha20-Poy1305`, `n`, and `rk` to obtain size of
|
|
the encrypted packet `l`.
|
|
* A zero-length byte slice is to be passed as the AD (associated data).
|
|
* The nonce for `rk` MUST be incremented after this step.
|
|
|
|
|
|
* Read _exactly_ `l+16` bytes from the network buffer, let the bytes be known as
|
|
`c`.
|
|
|
|
|
|
* Decrypt `c` using `ChaCha20-Poly1305`, `n`, and `rk` to obtain decrypted
|
|
plaintext packet `p`.
|
|
|
|
|
|
* The nonce for `rk` MUST be incremented after this step.
|
|
|
|
|
|
## Lightning Message Key Rotation
|
|
|
|
|
|
Changing keys regularly and forgetting the previous key is useful for
|
|
preventing decryption of old messages in the case of later key leakage (ie.
|
|
backwards secrecy).
|
|
|
|
|
|
Key rotation is performed for _each_ key (`sk` and `rk`) _individually _. A key
|
|
is to be rotated after a party sends of decrypts `1000` messages with it.
|
|
This can be properly accounted for by rotating the key once the nonce dedicated
|
|
to it exceeds `1000`.
|
|
|
|
|
|
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''
|
|
|
|
|
|
|
|
|
|
## Future Directions
|
|
|
|
"Ping" or "noop" messages could be appended to the same output
|
|
to max traffic analysis even more difficult.
|
|
|
|
In order to allow zero-RTT encrypted+authenticated communication, a Noise Pipes
|
|
protocol can be adopted which composes two handshakes, potentially falling back
|
|
to a full handshake if static public keys have changed.
|
|
|
|
## Lightning Message Format
|
|
|
|
After decryption, all lightning messages are of the form:
|
|
|
|
1. `2-byte` big-endian type.
|
|
3. Data bytes as specified by the total packet length.
|
|
|
|
The maximum size of these messages is `65535-bytes`, so the largest
|
|
message data possible is 65533 bytes. If larger messages are needed
|
|
in future, a fragmentation method will be defined.
|
|
|
|
### Requirements
|
|
|
|
A node MUST NOT send a message with more than `65533` data
|
|
bytes. A node MUST NOT send an evenly-typed message not listed here
|
|
without prior negotiation.
|
|
|
|
A node MUST ignore a received message of unknown type, if that type is
|
|
odd. A node MUST fail the channels if it receives a message of unknown
|
|
type, if that type is even.
|
|
|
|
A node MUST ignore any additional data within a message, beyond the
|
|
length it expects for that type.
|
|
|
|
A node MUST fail the channels if it receives a known message with
|
|
insufficient length for the contents.
|
|
|
|
### Rationale
|
|
|
|
The standard endian of `SHA2` and the encoding of bitcoin public keys
|
|
are big endian, thus it would be unusual to use a different endian for
|
|
other fields.
|
|
|
|
Length is limited to 65535 bytes by the cryptographic wrapping, and
|
|
messages in the protocol are never more than that length anyway.
|
|
|
|
The "it's OK to be odd" rule allows for future optional extensions
|
|
without negotiation or special coding in clients. The "ignore
|
|
additional data" rule similarly allows for future expansion.
|
|
|
|
Implementations may prefer have message data aligned on an 8-byte
|
|
boundary (the largest natural alignment requirement of any type here),
|
|
but adding a 6-byte padding after the type field was considered
|
|
wasteful: alignment may be achieved by decrypting the message into
|
|
a buffer with 6 bytes of pre-padding.
|
|
|
|
## Initialization Message
|
|
|
|
Once authentication is complete, the first message reveals the
|
|
features supported or required by this node. Odd features are
|
|
optional, even features are compulsory ("it's OK to be odd!"). The
|
|
meaning of these bits will be defined in future.
|
|
|
|
1. type: 16 (`init`)
|
|
2. data:
|
|
* [2:gflen]
|
|
* [gflen:globalfeatures]
|
|
* [2:lflen]
|
|
* [lflen:localfeatures]
|
|
|
|
The 2-byte len fields indicate the number of bytes in the immediately
|
|
following field.
|
|
|
|
|
|
### Requirements
|
|
|
|
|
|
The sending node SHOULD use the minimum lengths required to represent
|
|
the feature fields. The sending node MUST set feature bits
|
|
corresponding to features it requires the peer to support, and SHOULD
|
|
set feature bits corresponding to features it optionally supports.
|
|
|
|
|
|
The receiving node MUST fail the channels if it receives a
|
|
`globalfeatures` or `localfeatures` with an even bit set which it does
|
|
not understand.
|
|
|
|
|
|
Each node MUST wait to receive `init` before sending any other
|
|
messages.
|
|
|
|
|
|
### Rationale
|
|
|
|
|
|
The even/odd semantic allows future incompatible changes, or backward
|
|
compatible changes. Bits should generally be assigned in pairs, so
|
|
that optional features can later become compulsory.
|
|
|
|
Nodes wait for receipt of the other's features to simplify error
|
|
diagnosis where features are incompatible.
|
|
|
|
The feature masks are split into local features which only affect the
|
|
protocol between these two nodes, and global features which can affect
|
|
HTLCs and thus are also advertised to other nodes.
|
|
|
|
## Error Message
|
|
|
|
|
|
For simplicity of diagnosis, it is often useful to tell the peer that
|
|
something is incorrect.
|
|
|
|
|
|
1. type: 17 (`error`)
|
|
2. data:
|
|
* [8:channel-id]
|
|
* [2:len]
|
|
* [len:data]
|
|
|
|
The 2-byte `len` field indicates the number of bytes in the immediately
|
|
following field.
|
|
|
|
|
|
### Requirements
|
|
|
|
|
|
A node SHOULD send `error` for protocol violations or internal
|
|
errors which make channels unusable or further communication unusable.
|
|
A node MAY send an empty [data] field. A node sending `error` MUST
|
|
fail the channel referred to by the `channel-id`, or if `channel-id`
|
|
is 0xFFFFFFFFFFFFFFFF it MUST fail all channels and MUST close the connection.
|
|
A node MUST NOT set `len` to greater than the data length.
|
|
|
|
|
|
A node receiving `error` MUST fail the channel referred to by
|
|
`channel-id`, or if `channel-id` is 0xFFFFFFFFFFFFFFFF it MUST fail
|
|
all channels and MUST close the connection. A receiving node MUST truncate
|
|
`len` to the remainder of the packet if it is larger.
|
|
|
|
|
|
A receiving node SHOULD only print out `data` verbatim if it is a
|
|
valid string.
|
|
|
|
|
|
### Rationale
|
|
|
|
|
|
There are unrecoverable errors which require an abort of conversations;
|
|
if the connection is simply dropped then the peer may retry the
|
|
connection. It's also useful to describe protocol violations for
|
|
diagnosis, as it indicates that one peer has a bug.
|
|
|
|
|
|
It may be wise not to distinguish errors in production settings, lest
|
|
it leak information, thus the optional data field.
|
|
|
|
|
|
# Security Considerations #
|
|
|
|
|
|
It is strongly recommended that existing, commonly-used, validated
|
|
libraries be used for encryption and decryption, to avoid the many
|
|
implementation pitfalls possible.
|
|
|
|
## Acknowledgements
|
|
|
|
TODO(roasbeef); fin
|
|
|
|
|
|
# References
|
|
1. <a id="reference-1">https://en.bitcoin.it/wiki/Secp256k1</a>
|
|
2. <a id="reference-2">http://www.unicode.org/charts/PDF/U2600.pdf</a>
|
|
3. <a id="reference-3">https://tools.ietf.org/html/rfc7539</a>
|
|
4. <a id="reference-4">http://noiseprotocol.org/noise.html</a>
|
|
|
|
# Authors
|
|
|
|
FIXME
|
|
|
|
|
|
<br>
|
|
This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).
|