Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

websocket address type: allow transport over RFC6455 #891

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

websocket address type: allow transport over RFC6455 #891

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c35f10f
option_websocket: allow transport over RFC6455
rustyrussell Jul 27, 2021
729d0ed
websocket: make it an address type, not an option.
rustyrussell Aug 30, 2021
a174e0d
fixup! websocket: make it an address type, not an option.
rustyrussell Oct 25, 2021
5f94492
fixup! fixup! websocket: make it an address type, not an option.
rustyrussell Oct 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .aspell.en.pws
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -387,3 +387,5 @@ CHECKSIGVERIFY
IFDUP
sats
anysegwit
WebSocket
websocket
47 changes: 45 additions & 2 deletions 08-transport.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ of a node.
* [Handshake State](#handshake-state)
* [Handshake State Initialization](#handshake-state-initialization)
* [Handshake Exchange](#handshake-exchange)
* [Alternate Transport Layers: WebSocket](#websocket)
* [Lightning Message Specification](#lightning-message-specification)
* [Encrypting and Sending Messages](#encrypting-and-sending-messages)
* [Receiving and Decrypting Messages](#receiving-and-decrypting-messages)
Expand Down Expand Up @@ -100,7 +101,9 @@ indicates that no change is necessary, while a non-zero version indicate that th
client has deviated from the protocol originally specified within this
document.

Clients MUST reject handshake attempts initiated with an unknown version.
Clients MAY attempt to switch to an alternate interpretation if they
receive and invalid version on receipt of Act One, but otherwise
MUST reject handshake attempts initiated with an unknown version.

### Noise Protocol Instantiation

Expand Down Expand Up @@ -253,7 +256,9 @@ and 16 bytes for the `poly1305` tag.
* The raw bytes of the remote party's ephemeral public key (`re`) are to be
deserialized into a point on the curve using affine coordinates as encoded
by the key's serialized composed format.
3. If `v` is an unrecognized handshake version, then the responder MUST
3. If `v` is an unrecognized handshake version, and the responder supports
rustyrussell marked this conversation as resolved.
Show resolved Hide resolved
`option_websocket`, it MAY interpret the message as the initiation of
a [WebSocket connection](#websocket). Otherwise the responder MUST
abort the connection attempt.
4. `h = SHA-256(h || re.serializeCompressed())`
* The responder accumulates the initiator's ephemeral key into the authenticating
Expand Down Expand Up @@ -402,6 +407,43 @@ construction, and 16 bytes for a final authenticating tag.
10. `rn = 0, sn = 0`
* The sending and receiving nonces are initialized to 0.

## Alternate Transport Layers: WebSocket

Normally the transport protocol defined here is performed over TCP/IP,
but it can also be performed over other underlying transports, such as
the WebSocket protocol as specified in
RFC6455<sup>[4](#reference-4)</sup>.

A client may connect to a node and initiate a WebSocket; this will
normally fail as the WebSocket protocol begins with a "GET" request,
which is trivially distinguishable from a valid handshake. However,
the node may also allow it and operate the protocol over binary
WebSocket frames. The `option_websocket` feature allows nodes to
advertise this, but not all nodes send node_announcements, so it is
not required before attempting a WebSocket connection.


### Requirements

The initiator:
- MAY attempt to initiate an unencrypted WebSocket as specified in RFC6455<sup>[4](#reference-4)</sup>:
- MUST send at least 50 bytes before awaiting a response.
- MUST abort the connection attempt if WebSocket upgrade fails.
- MUST begin the [Handshake Exchange](#handshake-exchange) as initiator
as soon as upgrade succeeds.

The responder:
- if it supports `option_websocket`:
- SHOULD set `option_websocket` in its node announcements
- MUST attempt WebSocket upgrade if the Act 1 handshake it receives
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See comment above re separation of the layers. When nodes connect over Tor today, brontide implementations don't need to do anything different, and we can inherit that behavior here by defining the web sockets feature as a new address type.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also by having it as a new address type, nodes can advertise another addr here, which might actually just be a bridge they're using.

is not valid.
- MUST abort the connection attempt if WebSocket upgrade fails.

Both nodes, after upgrade:
- MUST use binary frames to send and receive messages.
- MUST NOT rely on WebSocket framing for message semantics.


## Lightning Message Specification

At the conclusion of Act Three, both sides have derived the encryption keys, which
Expand Down Expand Up @@ -779,6 +821,7 @@ TODO(roasbeef); fin
1. <a id="reference-1">https://tools.ietf.org/html/rfc8439</a>
2. <a id="reference-2">http://noiseprotocol.org/noise.html</a>
3. <a id="reference-3">https://tools.ietf.org/html/rfc5869</a>
4. <a id="reference-4">https://tools.ietf.org/html/rfc6455</a>

# Authors

Expand Down
2 changes: 2 additions & 0 deletions 09-features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ The Context column decodes as follows:
| 20/21 | `option_anchor_outputs` | Anchor outputs | IN | `option_static_remotekey` | [BOLT #3](03-transactions.md) |
| 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions | IN | | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful]|
| 26/27 | `option_shutdown_anysegwit` | Future segwit versions allowed in `shutdown` | IN | | [BOLT #2][bolt02-shutdown] |
| 42/43 | `option_websocket` | Can tunnel over WebSocket protocol | N | | [BOLT #8][bolt08-websocket] |

## Requirements

Expand Down Expand Up @@ -88,4 +89,5 @@ This work is licensed under a [Creative Commons Attribution 4.0 International Li
[bolt07-sync]: 07-routing-gossip.md#initial-sync
[bolt07-query]: 07-routing-gossip.md#query-messages
[bolt04-mpp]: 04-onion-routing.md#basic-multi-part-payments
[bolt08-websocket]: 08-transport.md#websocket
[ml-sighash-single-harmful]: https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-September/002796.html