option_scid_assign: privacy protection for private channels.

Private channels expose their funding transaction in routehints to
receive payments, but this is unnecesary.  Their funding tx can also
be probed via payment attempts.

1. A new feature, so you know when you can use these controls.
2. A channel_flags bit so you can ensure that new channels are
   protected probes from the start.
3. Messages to assign (and unassign) random short_channel_ids,
   with a side-effect of disabling the funding-tx-based one.

Fixes: lightning#675
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

.aspell.en.pws

@@ -371,3 +371,6 @@ tlvs
 snprintf
 GitHub
 IRC
+scid
+unassigning
+misrouting

02-peer-protocol.md

@@ -24,6 +24,7 @@ operation, and closing.
       * [Committing Updates So Far: `commitment_signed`](#committing-updates-so-far-commitment_signed)
       * [Completing the Transition to the Updated State: `revoke_and_ack`](#completing-the-transition-to-the-updated-state-revoke_and_ack)
       * [Updating Fees: `update_fee`](#updating-fees-update_fee)
+      * [Assigning Random `short_channel_id`](#assigning-random-short-channel-id)
     * [Message Retransmission: `channel_reestablish` message](#message-retransmission)
   * [Authors](#authors)
 
@@ -178,11 +179,22 @@ third parties.
 `first_per_commitment_point` is the per-commitment point to be used
 for the first commitment transaction,
 
-Only the least-significant bit of `channel_flags` is currently
-defined: `announce_channel`. This indicates whether the initiator of
+The following table specifies the meaning of individual `channel_flags` bits:
+
+| Bit Position  | Name               |
+| ------------- | ------------------ |
+| 0             | `announce_channel` |
+| 1             | `disable_incoming` |
+
+`announce_channel` indicates whether the initiator of
 the funding flow wishes to advertise this channel publicly to the
 network, as detailed within [BOLT #7](07-routing-gossip.md#bolt-7-p2p-node-and-channel-discovery).
 
+`disable_incoming` indicates that no payments are to be accepted for this
+channel: this is only effective if `announce_channel` is not set, and the
+recipient offers `option_scid_assign`.  See [Assigning Random
+`short_channel_id`](#assigning-random-short-channel-id).
+
 The `shutdown_scriptpubkey` allows the sending node to commit to where
 funds will go on mutual close, which the remote node should enforce
 even if a node is compromised later.
@@ -1106,6 +1118,75 @@ it's simplest to only allow it to set fee levels; however, as the same
 fee rate applies to HTLC transactions, the receiving node must also
 care about the reasonableness of the fee.
 
+### Assigning Random `short_channel_id`
+
+To facilitate privacy of unannounced channels, peers can request a random
+short_channel_id to use which does not have any relationship to the actual
+channel funding transaction.  Note that these messages are all even, so it
+is illegal to send them to peers which do not offer `option_scid_assign`.
+
+1. type: 260 (`assign_scid`) (`option_scid_assign`)
+2. data:
+   * [`channel_id`:`channel_id`]
+
+1. type: 268 (`assign_scid_reply`) (`option_scid_assign`)
+   * [`channel_id`:`channel_id`]
+   * [`short_channel_id`:`short_channel_id`]
+
+1. type: 270 (`unassign_scid`) (`option_scid_assign`)
+2. data:
+   * [`channel_id`:`channel_id`]
+
+1. type: 272 (`unassign_scid_reply`) (`option_scid_assign`)
+   * [`channel_id`:`channel_id`]
+
+#### Requirements
+
+A sending node:
+  - if it did not offer `option_scid_assign`:
+    - MUST NOT send `assign_scid` or `unassign_scid`
+  - SHOULD remember the last `assign_scid_reply` `short_channel_id` for use in
+    receiving payments.
+  - MAY send `unassign_scid` when no invoices are pending, and send `assign_scid` when
+    it wants to create a new invoice and none are pending.
+
+A receiving node:
+  - on receiving `assign_scid`:
+    - MUST assign an unpredictable unique 64-bit number to this channel
+      (see [Assigned `short_channel_id` Forwarding](04-onion-routing.md#assigned-short_channel_id-forwarding)).
+	  and return it in an ``assign_scid_reply` message.
+	  - SHOULD ensure this does not conflict with future `short_channel_id`s.
+    - MUST discard any previous assigned `short_channel_id` for this channel
+  - on receiving `unassign_scid`:
+    - MUST discard any previous assigned `short_channel_id` for this channel
+	  - Note: it's not an error if there are no previous assignments.
+	- MUST reply with `unassign_scid_reply`.
+
+#### Rationale
+
+There are two ways of hiding a private channel's funding-transaction-derived
+`short_channel_id`.  The most thorough is `disable_incoming` which ensures
+that the private `short_channel_id` is never used for forwarding.  However,
+since channels may have been opened before `option_scid_assign` was
+implemented, assigning or unassigning a random short_channel_id has the same
+effect of disabling the original `short_channel_id`.  See [Assigned
+`short_channel_id` Forwarding](04-onion-routing.md#assigned-short_channel_id-forwarding).
+
+The space of short_channel_id is only 64 bits, so it's possible for an
+adversary to probe for them over time, using payment attempts.  Thus it's
+recommended that they only be assigned when they're actually likely to be
+used, and unassigned afterwards.
+
+If it were to conflict with a future `short_channel_id` for a real
+channel, misrouting may occur.  The simplest way to minimize this is
+to use old block numbers, but that also reduces the search space.
+Simpler is to select a random value which isn't already used, and
+close (before funding_locked) any future channel unfortunate enough to
+clash.
+
+Assigning and unassigning are idempotent, so can be safely retransmitted in
+case of packet loss.
+
 ## Message Retransmission
 
 Because communication transports are unreliable, and may need to be

04-onion-routing.md

@@ -50,6 +50,7 @@ A node:
   * [Packet Structure](#packet-structure)
     * [Payload for the Last Node](#payload-for-the-last-node)
   * [Accepting and Forwarding a Payment](#accepting-and-forwarding-a-payment)
+    * [Assigned `short_channel_id` Forwarding](#assigned-short_channel_id-forwarding)
   * [Shared Secret](#shared-secret)
   * [Blinding Ephemeral Keys](#blinding-ephemeral-keys)
   * [Packet Construction](#packet-construction)
@@ -283,6 +284,27 @@ compare its values against those of the HTLC. See the
 If not for the above, since it need not forward payments, the final node could
 simply discard its payload.
 
+## Payload for the Last Node
+
+When building the route, the origin node MUST use a payload for
+the final node with the following values:
+
+* `outgoing_cltv_value`: set to the final expiry specified by the recipient (e.g.
+  `min_final_cltv_expiry` from a [BOLT #11](11-payment-encoding.md) payment invoice)
+* `amt_to_forward`: set to the final amount specified by the recipient (e.g. `amount`
+  from a [BOLT #11](11-payment-encoding.md) payment invoice)
+
+This allows the final node to check these values and return errors if needed,
+but it also eliminates the possibility of probing attacks by the second-to-last
+node. Such attacks could, otherwise, attempt to discover if the receiving peer is the
+last one by re-sending HTLCs with different amounts/expiries.
+The final node will extract its onion payload from the HTLC it has received and
+compare its values against those of the HTLC. See the
+[Returning Errors](#returning-errors) section below for more details.
+
+If not for the above, since it need not forward payments, the final node could
+simply discard its payload.
+
 # Accepting and Forwarding a Payment
 
 Once a node has decoded the payload it either accepts the payment locally, or forwards it to the peer indicated as the next hop in the payload.
@@ -330,6 +352,23 @@ Alternatively, implementations may choose to apply non-strict forwarding only to
 like-policy channels to ensure their expected fee revenue does not deviate by
 using an alternate channel.
 
+## Assigned `short_channel_id` Forwarding
+
+A node SHOULD forward an HTLC to an outgoing channel if the
+`short_channel_id` matches the `short_channel_id` given in the latest
+`assign_scid_reply` message for that channel.
+
+### Rationale
+
+Private channels can hide their actual funding transaction information
+by having their peer assign a (random) short_channel_id for their use
+(i.e. in BOLT 11 invoices), if `option_scid_assign` is offered by the
+peer.
+
+Note the requirements in [Failure Messages](#failure-messages) which
+disable the use of the original `short_channel_id` once assigned
+`short_channel_id`s are used.
+
 # Shared Secret
 
 The origin node establishes a shared secret with each hop along the route using
@@ -783,7 +822,9 @@ the onion.
 1. type: PERM|10 (`unknown_next_peer`)
 
 The onion specified a `short_channel_id` which doesn't match any
-leading from the processing node.
+leading from the processing node, or it's the funding-transaction-based
+`short_channel_id` for a private channel which has
+`disable_incoming` set or has a random `short_channel_id` assigned.
 
 1. type: UPDATE|11 (`amount_below_minimum`)
 2. data:
@@ -927,6 +968,12 @@ A _forwarding node_ MAY, but a _final node_ MUST NOT:
     - return a `required_channel_feature_missing` error.
   - if the receiving peer specified by the onion is NOT known:
     - return an `unknown_next_peer` error.
+  - if it supports `option_scid_assign` and the `short_channel_id` is the
+    funding-transaction-based `short_channel_id` of a channel opened with
+    `announce_channel` `false`:
+	- if the peer opened or accepted the channel with `disable_incoming` `true` or
+      this node has ever sent the peer `assign_scid_reply` or `unassign_scid_reply`:
+      - MUST return an `unknown_next_peer` error.
   - if the HTLC amount is less than the currently specified minimum amount:
     - report the amount of the outgoing HTLC and the current channel setting for
     the outgoing channel.

09-features.md

@@ -28,6 +28,7 @@ These flags may only be used in the `init` message:
 | 6/7   | `gossip_queries`                 | More sophisticated gossip control                                         | [BOLT #7][bolt07-query]      |
 | 10/11 | `gossip_queries_ex`              | Gossip queries can include additional information                         | [BOLT #7][bolt07-query]      |
 | 12/13| `option_static_remotekey`     | Static key for remote output                                              | [BOLT #3](03-transactions.md)    |
+| 114/115| `option_scid_assign`              | Random short-channel-id assignment                                        | [BOLT #2](bolt03-assign-scid)|
 
 ## Assigned `globalfeatures` flags