From df4e932851a49663c9b1e82861f8e58c6d6ab955 Mon Sep 17 00:00:00 2001
From: protolambda <proto@protolambda.com>
Date: Mon, 14 Sep 2020 22:59:07 +0200
Subject: [PATCH] gossipsub: introduce message signing policy, see
 libp2p/go-libp2p-pubsub#359

---
 pubsub/README.md                   |  5 +++++
 pubsub/gossipsub/gossipsub-v1.1.md | 24 ++++++++++++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/pubsub/README.md b/pubsub/README.md
index 687851e..eadd8c5 100644
--- a/pubsub/README.md
+++ b/pubsub/README.md
@@ -153,6 +153,10 @@ and
 
 Messages can be optionally signed, and it is up to the peer whether to accept and forward
 unsigned messages.
+When the receiver expects unsigned content-based messages, and thus does not expect
+the `from`, `seqno`, `signature`, or `key` fields, it may reject the messages (`StrictNoSign`).
+And if not, the receiver may choose to enforce signatures strictly (`StrictSign`).
+This optionality is configurable with the signing policy options starting from `v1.1`. 
 
 For signing purposes, the `signature` and `key` fields are used:
 - The `signature` field contains the signature.
@@ -160,6 +164,7 @@ For signing purposes, the `signature` and `key` fields are used:
   When present, it must match the peer ID.
 
 The signature is computed over the marshalled message protobuf _excluding_ the key field.
+This includes any fields that are not recognized, but still included in the marshalled data.
 The protobuf blob is prefixed by the string `libp2p-pubsub:` before signing.
 
 When signature validation fails for a signed message, the implementation must
diff --git a/pubsub/gossipsub/gossipsub-v1.1.md b/pubsub/gossipsub/gossipsub-v1.1.md
index 6b75460..b56e6d6 100644
--- a/pubsub/gossipsub/gossipsub-v1.1.md
+++ b/pubsub/gossipsub/gossipsub-v1.1.md
@@ -37,6 +37,7 @@ See the [lifecycle document][lifecycle-spec] for context about maturity level an
   - [Explicit Peering Agreements](#explicit-peering-agreements)
   - [PRUNE Backoff and Peer Exchange](#prune-backoff-and-peer-exchange)
     - [Protobuf](#protobuf)
+  - [Signature policy](#signature-policy)
   - [Flood Publishing](#flood-publishing)
   - [Adaptive Gossip Dissemination](#adaptive-gossip-dissemination)
   - [Outbound Mesh Quotas](#outbound-mesh-quotas)
@@ -134,6 +135,29 @@ message PeerInfo {
 }
 ```
 
+### Signature policy
+
+The usage of the `signature`, `key`, `from`, and `seqno` fields in `Message` is now configurable.
+These fields may negatively affect privacy in content-addressed messaging,
+and may need to be strictly enforced in author-addressed messaging.
+
+In gossipsub v1.0, a "lax" signing policy is effective: verify signatures, and if not, only when present.
+In gossipsub v1.1, these fields are strictly present and verified, or completely omitted altogether.
+An implementation may choose to support the legacy v1.0 "lax" signing policy,
+ along with an explicit message authoring option. 
+
+Gossipsub v1.1 has two policies to choose from:
+- `StrictSign`:
+  - Produces the `signature`, `key` (`from` may be enough), `from` and `seqno` fields.
+  - Enforce the fields to be present, reject otherwise.
+  - Verify the signature, reject otherwise.
+  - Propagate the fields if valid.
+- `StrictNoSign`:
+  - Produces messages without the `signature`, `key`, `from` and `seqno` fields.
+    The corresponding protobuf key-value pairs are absent from the marshalled message, not just empty.
+  - Enforce the fields to be absent, reject otherwise.
+  - Propagate only if the fields are absent.
+
 ### Flood Publishing
 
 In gossipsub v1.0, peers publish new messages to the members of their mesh if they are subscribed to