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: attempt 2 #1068

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Websocket address type: attempt 2 #1068

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 3 additions & 1 deletion .aspell.en.pws
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -392,4 +392,6 @@ unspendable
pkh
kB
unblind
unblinded
unblinded
WebSocket
websocket
10 changes: 9 additions & 1 deletion 07-routing-gossip.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -294,6 +294,10 @@ The following `address descriptor` types are defined:
* `hostname` bytes MUST be ASCII characters.
* Non-ASCII characters MUST be encoded using Punycode:
https://en.wikipedia.org/wiki/Punycode
* `6`: WebSocket address; data = `[1:hostname_len][hostname_len:hostname][2:port]` (length up to 258)
* `hostname` bytes MUST be ASCII characters.
* Non-ASCII characters MUST be encoded using Punycode:
https://en.wikipedia.org/wiki/Punycode

### Requirements

Expand All @@ -315,14 +319,15 @@ The origin node:
- MUST place address descriptors in ascending order.
- SHOULD NOT place any zero-typed address descriptors anywhere.
- SHOULD use placement only for aligning fields that follow `addresses`.
- MUST NOT create a `type 1`, `type 2` or `type 5` address descriptor with
- MUST NOT create a `type 1`, `type 2`, `type 5` or `type 6` address descriptor with
`port` equal to 0.
- SHOULD ensure `ipv4_addr` AND `ipv6_addr` are routable addresses.
- MUST set `features` according to [BOLT #9](09-features.md#assigned-features-flags)
- SHOULD set `flen` to the minimum length required to hold the `features`
bits it sets.
- SHOULD not announce a Tor v2 onion service.
- MUST NOT announce more than one `type 5` DNS hostname.
- MUST NOT announce more than one `type 6` DNS hostname.

The receiving node:
- if `node_id` is NOT a valid compressed public key:
Expand Down Expand Up @@ -363,6 +368,9 @@ any future fields appended to the end):
- if more than one `type 5` address is announced:
- SHOULD ignore the additional data.
- MUST not forward the `node_announcement`.
- if more than one `type 6` address is announced:
- SHOULD ignore the additional data.
- MUST not forward the `node_announcement`.

### Rationale

Expand Down
30 changes: 30 additions & 0 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 @@ -402,6 +403,34 @@ 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> on ports so-advertized (in the
[node_announcement message](07-routing-gossip.md#the-node_announcement-message).

A client may connect to this port node and initiate a WebSocket; and
operate the protocol over binary WebSocket frames instead of raw TCP/IP.

### Requirements

The initiator:
- MAY attempt to initiate an unencrypted WebSocket as specified in RFC6455<sup>[4](#reference-4)</sup>:
- 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 WebSocket connections on an address:
- SHOULD advertise it using a type 6 address its node announcement.
- 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 +808,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