logos-messaging/specs
1
0
Fork 0
mirror of https://github.com/logos-messaging/specs.git synced 2026-01-02 14:13:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1 from waku-org/waku-RFC

Browse Source 
New Waku Spec Repo
This commit is contained in:
Jimmy Debe 2024-02-21 14:33:16 -05:00 committed by GitHub
commit cc257bb1e7
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
21 changed files with 3164 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
.github/workflows/spelling.yml vendored Normal file
View File

@ -0,0 +1,22 @@
# This is workflow for spell checking using PySpelling lib (https://pypi.org/project/pyspelling/)
name: Spellcheck
on:
push:
branches:
- '**'
pull_request:
branches:
- '**'
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: igsekor/pyspelling-any@v1.0.4
name: Spellcheck
env:
MATRIX: ${{ toJson(matrix) }}
run: pyspelling --matrix "$MATRIX"

121
LICENSE Normal file
View File

@ -0,0 +1,121 @@
Creative Commons Legal Code
CC0 1.0 Universal
CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
HEREUNDER.
Statement of Purpose
The laws of most jurisdictions throughout the world automatically confer
exclusive Copyright and Related Rights (defined below) upon the creator
and subsequent owner(s) (each and all, an "owner") of an original work of
authorship and/or a database (each, a "Work").
Certain owners wish to permanently relinquish those rights to a Work for
the purpose of contributing to a commons of creative, cultural and
scientific works ("Commons") that the public can reliably and without fear
of later claims of infringement build upon, modify, incorporate in other
works, reuse and redistribute as freely as possible in any form whatsoever
and for any purposes, including without limitation commercial purposes.
These owners may contribute to the Commons to promote the ideal of a free
culture and the further production of creative, cultural and scientific
works, or to gain reputation or greater distribution for their Work in
part through the use and efforts of others.
For these and/or other purposes and motivations, and without any
expectation of additional consideration or compensation, the person
associating CC0 with a Work (the "Affirmer"), to the extent that he or she
is an owner of Copyright and Related Rights in the Work, voluntarily
elects to apply CC0 to the Work and publicly distribute the Work under its
terms, with knowledge of his or her Copyright and Related Rights in the
Work and the meaning and intended legal effect of CC0 on those rights.
1. Copyright and Related Rights. A Work made available under CC0 may be
protected by copyright and related or neighboring rights ("Copyright and
Related Rights"). Copyright and Related Rights include, but are not
limited to, the following:
i. the right to reproduce, adapt, distribute, perform, display,
communicate, and translate a Work;
ii. moral rights retained by the original author(s) and/or performer(s);
iii. publicity and privacy rights pertaining to a person's image or
likeness depicted in a Work;
iv. rights protecting against unfair competition in regards to a Work,
subject to the limitations in paragraph 4(a), below;
v. rights protecting the extraction, dissemination, use and reuse of data
in a Work;
vi. database rights (such as those arising under Directive 96/9/EC of the
European Parliament and of the Council of 11 March 1996 on the legal
protection of databases, and under any national implementation
thereof, including any amended or successor version of such
directive); and
vii. other similar, equivalent or corresponding rights throughout the
world based on applicable law or treaty, and any national
implementations thereof.
2. Waiver. To the greatest extent permitted by, but not in contravention
of, applicable law, Affirmer hereby overtly, fully, permanently,
irrevocably and unconditionally waives, abandons, and surrenders all of
Affirmer's Copyright and Related Rights and associated claims and causes
of action, whether now known or unknown (including existing as well as
future claims and causes of action), in the Work (i) in all territories
worldwide, (ii) for the maximum duration provided by applicable law or
treaty (including future time extensions), (iii) in any current or future
medium and for any number of copies, and (iv) for any purpose whatsoever,
including without limitation commercial, advertising or promotional
purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
member of the public at large and to the detriment of Affirmer's heirs and
successors, fully intending that such Waiver shall not be subject to
revocation, rescission, cancellation, termination, or any other legal or
equitable action to disrupt the quiet enjoyment of the Work by the public
as contemplated by Affirmer's express Statement of Purpose.
3. Public License Fallback. Should any part of the Waiver for any reason
be judged legally invalid or ineffective under applicable law, then the
Waiver shall be preserved to the maximum extent permitted taking into
account Affirmer's express Statement of Purpose. In addition, to the
extent the Waiver is so judged Affirmer hereby grants to each affected
person a royalty-free, non transferable, non sublicensable, non exclusive,
irrevocable and unconditional license to exercise Affirmer's Copyright and
Related Rights in the Work (i) in all territories worldwide, (ii) for the
maximum duration provided by applicable law or treaty (including future
time extensions), (iii) in any current or future medium and for any number
of copies, and (iv) for any purpose whatsoever, including without
limitation commercial, advertising or promotional purposes (the
"License"). The License shall be deemed effective as of the date CC0 was
applied by Affirmer to the Work. Should any part of the License for any
reason be judged legally invalid or ineffective under applicable law, such
partial invalidity or ineffectiveness shall not invalidate the remainder
of the License, and in such case Affirmer hereby affirms that he or she
will not (i) exercise any of his or her remaining Copyright and Related
Rights in the Work or (ii) assert any associated claims and causes of
action with respect to the Work, in either case contrary to Affirmer's
express Statement of Purpose.
4. Limitations and Disclaimers.
a. No trademark or patent rights held by Affirmer are waived, abandoned,
surrendered, licensed or otherwise affected by this document.
b. Affirmer offers the Work as-is and makes no representations or
warranties of any kind concerning the Work, express, implied,
statutory or otherwise, including without limitation warranties of
title, merchantability, fitness for a particular purpose, non
infringement, or the absence of latent or other defects, accuracy, or
the present or absence of errors, whether or not discoverable, all to
the greatest extent permissible under applicable law.
c. Affirmer disclaims responsibility for clearing rights of other persons
that may apply to the Work or any use thereof, including without
limitation any person's Copyright and Related Rights in the Work.
Further, Affirmer disclaims responsibility for obtaining any necessary
consents, permissions or other rights required for any use of the
Work.
d. Affirmer understands and acknowledges that Creative Commons is not a
party to this document and has no duty or obligation with respect to
this CC0 or use of the Work.

72
README.md Normal file
View File

@ -0,0 +1,72 @@
# Waku Specifications
Waku builds a family of privacy-preserving, censorship-resistant communication protocols for web3 applications.
This repository contains specifications for the Waku suite of protocols.
## List of Specifications:
- Informational: Waku design issues, general guidelines or background information that does not constitute a new feature.
- Standards
- Core: Standards and protocols for the core Waku p2p communications offering.
- Application: Standards and protocols that describe various applications or encryption use cases built on top of a Waku network.
| Waku Specifications | Description |
| ---- | -------------- |
|[10/WAKU2](https://rfc.vac.dev/spec/10/)| Core |
|[11/WAKU2-RELAY](https://rfc.vac.dev/spec/11)| Core |
|[12/WAKU2-FILTER](https://rfc.vac.dev/spec/12)| Core|
|[13/WAKU2-STORE](https://rfc.vac.dev/spec/13/)| Core |
|[14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/)| Core |
|[15/WAKU2-BRIDGE](https://rfc.vac.dev/spec/15)| Core |
|[16/WAKU2-RPC](https://rfc.vac.dev/spec/16)| Core |
|[17/WAKU2-RLN-RELAY](https://rfc.vac.dev/spec/17/)| Core |
|[18/WAKU2-SWAP](https://rfc.vac.dev/spec/18/)| Application |
|[19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/)| Core |
|[20/TOY-ETH-PM](https://rfc.vac.dev/spec/20/)| Application |
|[21/WAKU2-FAULT-TOLERANT-STORE](https://rfc.vac.dev/spec/21/)| Application |
|[22/TOY-CHAT](https://rfc.vac.dev/spec/22/)| Informational |
|[23/WAKU2-TOPICS](https://rfc.vac.dev/spec/23/)| Informational |
|[26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26/)| Application |
|[27/WAKU2-PEERS](https://rfc.vac.dev/spec/27/)| Informational |
|[29/WAKU2-CONFIG](https://rfc.vac.dev/spec/29/)| Informational |
|[30/ADAPTIVE-NODES](https://rfc.vac.dev/spec/30/)| Informational |
|[33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/)| Core |
|[36/WAKU2-BINDINGS-API](https://rfc.vac.dev/spec/36/)| Core |
|[53/WAKU2-X3DH](https://rfc.vac.dev/spec/53/)| Application |
|[54/WAKU2-X3DH-SESSIONS](https://rfc.vac.dev/spec/54/)| Application |
|[ADVERSARIAL-MODELS](informational/adversarial-models.md)| Informational |
|[RELAY-STATIC-SHARD-ALLOC](informational/relay-static-shard-alloc.md)| Informational |
|[DANDELION](standards/application/dandelion.md)| Application |
|[WAKU2-DEVICE-PAIRING](standards/application/device-pairing.md)| Application |
|[WAKU2-PEER-EXCHANGE](standards/core/peer-exchange.md)| Core |
|[WAKU2-ENR](standards/core/enr.md)| Core |
|[WAKU2-NOISE](standards/application/noise.md)| Application |
|[TOR-PUSH](standards/application/tor-push.md)| Application |
|[WAKU2-INCENTIVIZATION](standards/core/incentivization.md)| Core |
|[WAKU2-METADATA](standards/core/metadata.md)| Core |
|[WAKU2-NETWORK](standards/core/network.md)| Core |
|[RELAY-SHARDING](standards/core/relay-sharding.md)| Core |
| WAKU2-STOREV3 | Coming Soon |
## Resources
Relevant Waku resources related to the specifications located in this repository:
- [Waku.org](https://waku.org/)
- [nwaku: Waku Node](https://github.com/waku-org/nwaku)
## Contributions
Contributions are welcome from any party.
Contributors can create specifications relating to the Waku domain and
create a pull request to begin discussion.
The recommended [template](./template.md) may be used for new proposed specifications.
New specifications are considered a proof of concept.
Once a rough consensus is reached towards stabilization,
the specification may be considered to receive the draft status and
further discussion will continue on the [Vac RFC-Index](https://github.com/vacp2p/rfc-index) repository.
**NOTE:** Specifications located in this repository should be considered not production ready.
Discussion should be conducted with the intention of maturing each specification.
Head over to the [Vac RFC-Index](https://github.com/vacp2p/rfc-index) repository where other Waku specifications live.

BIN
images/N11M.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 97 KiB

BIN
images/NM.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 92 KiB

118
images/protocol.svg Normal file
View File

@ -0,0 +1,118 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="279pt" height="156pt" viewBox="0 0 279 156" version="1.1">
<defs>
<g>
<symbol overflow="visible" id="glyph0-0">
<path style="stroke:none;" d="M 0.640625 2.265625 L 0.640625 -9.015625 L 7.03125 -9.015625 L 7.03125 2.265625 Z M 1.359375 1.546875 L 6.328125 1.546875 L 6.328125 -8.296875 L 1.359375 -8.296875 Z M 1.359375 1.546875 "/>
</symbol>
<symbol overflow="visible" id="glyph0-1">
<path style="stroke:none;" d="M 5.265625 -5.921875 C 5.128906 -5.992188 4.984375 -6.046875 4.828125 -6.078125 C 4.679688 -6.117188 4.519531 -6.140625 4.34375 -6.140625 C 3.6875 -6.140625 3.179688 -5.925781 2.828125 -5.5 C 2.484375 -5.082031 2.3125 -4.476562 2.3125 -3.6875 L 2.3125 0 L 1.15625 0 L 1.15625 -7 L 2.3125 -7 L 2.3125 -5.90625 C 2.5625 -6.332031 2.878906 -6.648438 3.265625 -6.859375 C 3.648438 -7.066406 4.117188 -7.171875 4.671875 -7.171875 C 4.753906 -7.171875 4.84375 -7.164062 4.9375 -7.15625 C 5.03125 -7.144531 5.132812 -7.128906 5.25 -7.109375 Z M 5.265625 -5.921875 "/>
</symbol>
<symbol overflow="visible" id="glyph0-2">
<path style="stroke:none;" d="M 7.1875 -3.78125 L 7.1875 -3.21875 L 1.90625 -3.21875 C 1.957031 -2.425781 2.195312 -1.820312 2.625 -1.40625 C 3.050781 -1 3.644531 -0.796875 4.40625 -0.796875 C 4.84375 -0.796875 5.269531 -0.847656 5.6875 -0.953125 C 6.101562 -1.066406 6.515625 -1.226562 6.921875 -1.4375 L 6.921875 -0.359375 C 6.515625 -0.179688 6.09375 -0.046875 5.65625 0.046875 C 5.21875 0.140625 4.78125 0.1875 4.34375 0.1875 C 3.21875 0.1875 2.328125 -0.132812 1.671875 -0.78125 C 1.023438 -1.4375 0.703125 -2.320312 0.703125 -3.4375 C 0.703125 -4.582031 1.007812 -5.488281 1.625 -6.15625 C 2.25 -6.832031 3.085938 -7.171875 4.140625 -7.171875 C 5.078125 -7.171875 5.816406 -6.863281 6.359375 -6.25 C 6.910156 -5.644531 7.1875 -4.820312 7.1875 -3.78125 Z M 6.046875 -4.125 C 6.035156 -4.75 5.859375 -5.25 5.515625 -5.625 C 5.171875 -6 4.71875 -6.1875 4.15625 -6.1875 C 3.507812 -6.1875 2.992188 -6.003906 2.609375 -5.640625 C 2.222656 -5.285156 2 -4.78125 1.9375 -4.125 Z M 6.046875 -4.125 "/>
</symbol>
<symbol overflow="visible" id="glyph0-3">
<path style="stroke:none;" d="M 1.890625 -3.5 C 1.890625 -2.644531 2.0625 -1.976562 2.40625 -1.5 C 2.757812 -1.019531 3.238281 -0.78125 3.84375 -0.78125 C 4.457031 -0.78125 4.9375 -1.019531 5.28125 -1.5 C 5.632812 -1.976562 5.8125 -2.644531 5.8125 -3.5 C 5.8125 -4.34375 5.632812 -5.003906 5.28125 -5.484375 C 4.9375 -5.960938 4.457031 -6.203125 3.84375 -6.203125 C 3.238281 -6.203125 2.757812 -5.960938 2.40625 -5.484375 C 2.0625 -5.003906 1.890625 -4.34375 1.890625 -3.5 Z M 5.8125 -1.046875 C 5.570312 -0.628906 5.265625 -0.316406 4.890625 -0.109375 C 4.523438 0.0859375 4.082031 0.1875 3.5625 0.1875 C 2.71875 0.1875 2.03125 -0.148438 1.5 -0.828125 C 0.96875 -1.503906 0.703125 -2.394531 0.703125 -3.5 C 0.703125 -4.59375 0.96875 -5.476562 1.5 -6.15625 C 2.03125 -6.832031 2.71875 -7.171875 3.5625 -7.171875 C 4.082031 -7.171875 4.523438 -7.066406 4.890625 -6.859375 C 5.265625 -6.660156 5.570312 -6.351562 5.8125 -5.9375 L 5.8125 -7 L 6.953125 -7 L 6.953125 2.65625 L 5.8125 2.65625 Z M 5.8125 -1.046875 "/>
</symbol>
<symbol overflow="visible" id="glyph0-4">
<path style="stroke:none;" d="M 1.09375 -2.765625 L 1.09375 -7 L 2.234375 -7 L 2.234375 -2.8125 C 2.234375 -2.144531 2.363281 -1.644531 2.625 -1.3125 C 2.882812 -0.976562 3.269531 -0.8125 3.78125 -0.8125 C 4.40625 -0.8125 4.894531 -1.007812 5.25 -1.40625 C 5.613281 -1.800781 5.796875 -2.34375 5.796875 -3.03125 L 5.796875 -7 L 6.953125 -7 L 6.953125 0 L 5.796875 0 L 5.796875 -1.078125 C 5.515625 -0.648438 5.191406 -0.332031 4.828125 -0.125 C 4.460938 0.0820312 4.035156 0.1875 3.546875 0.1875 C 2.742188 0.1875 2.132812 -0.0625 1.71875 -0.5625 C 1.300781 -1.0625 1.09375 -1.796875 1.09375 -2.765625 Z M 3.984375 -7.171875 Z M 3.984375 -7.171875 "/>
</symbol>
<symbol overflow="visible" id="glyph0-5">
<path style="stroke:none;" d="M 5.671875 -6.796875 L 5.671875 -5.703125 C 5.347656 -5.867188 5.007812 -5.992188 4.65625 -6.078125 C 4.300781 -6.160156 3.9375 -6.203125 3.5625 -6.203125 C 3 -6.203125 2.570312 -6.113281 2.28125 -5.9375 C 2 -5.769531 1.859375 -5.507812 1.859375 -5.15625 C 1.859375 -4.882812 1.957031 -4.671875 2.15625 -4.515625 C 2.363281 -4.367188 2.773438 -4.226562 3.390625 -4.09375 L 3.78125 -4 C 4.601562 -3.832031 5.1875 -3.585938 5.53125 -3.265625 C 5.875 -2.941406 6.046875 -2.5 6.046875 -1.9375 C 6.046875 -1.28125 5.785156 -0.757812 5.265625 -0.375 C 4.753906 0 4.050781 0.1875 3.15625 0.1875 C 2.78125 0.1875 2.390625 0.148438 1.984375 0.078125 C 1.578125 0.00390625 1.144531 -0.101562 0.6875 -0.25 L 0.6875 -1.4375 C 1.113281 -1.21875 1.53125 -1.050781 1.9375 -0.9375 C 2.351562 -0.832031 2.765625 -0.78125 3.171875 -0.78125 C 3.710938 -0.78125 4.128906 -0.875 4.421875 -1.0625 C 4.710938 -1.25 4.859375 -1.507812 4.859375 -1.84375 C 4.859375 -2.15625 4.753906 -2.394531 4.546875 -2.5625 C 4.335938 -2.726562 3.875 -2.890625 3.15625 -3.046875 L 2.765625 -3.140625 C 2.046875 -3.285156 1.53125 -3.515625 1.21875 -3.828125 C 0.90625 -4.140625 0.75 -4.566406 0.75 -5.109375 C 0.75 -5.765625 0.976562 -6.269531 1.4375 -6.625 C 1.90625 -6.988281 2.570312 -7.171875 3.4375 -7.171875 C 3.851562 -7.171875 4.25 -7.140625 4.625 -7.078125 C 5 -7.015625 5.347656 -6.921875 5.671875 -6.796875 Z M 5.671875 -6.796875 "/>
</symbol>
<symbol overflow="visible" id="glyph0-6">
<path style="stroke:none;" d="M 2.34375 -8.984375 L 2.34375 -7 L 4.71875 -7 L 4.71875 -6.109375 L 2.34375 -6.109375 L 2.34375 -2.3125 C 2.34375 -1.738281 2.421875 -1.367188 2.578125 -1.203125 C 2.734375 -1.046875 3.050781 -0.96875 3.53125 -0.96875 L 4.71875 -0.96875 L 4.71875 0 L 3.53125 0 C 2.644531 0 2.03125 -0.164062 1.6875 -0.5 C 1.351562 -0.832031 1.1875 -1.4375 1.1875 -2.3125 L 1.1875 -6.109375 L 0.34375 -6.109375 L 0.34375 -7 L 1.1875 -7 L 1.1875 -8.984375 Z M 2.34375 -8.984375 "/>
</symbol>
<symbol overflow="visible" id="glyph0-7">
<path style="stroke:none;" d="M 2.3125 -1.046875 L 2.3125 2.65625 L 1.15625 2.65625 L 1.15625 -7 L 2.3125 -7 L 2.3125 -5.9375 C 2.5625 -6.351562 2.867188 -6.660156 3.234375 -6.859375 C 3.597656 -7.066406 4.039062 -7.171875 4.5625 -7.171875 C 5.40625 -7.171875 6.09375 -6.832031 6.625 -6.15625 C 7.15625 -5.476562 7.421875 -4.59375 7.421875 -3.5 C 7.421875 -2.394531 7.15625 -1.503906 6.625 -0.828125 C 6.09375 -0.148438 5.40625 0.1875 4.5625 0.1875 C 4.039062 0.1875 3.597656 0.0859375 3.234375 -0.109375 C 2.867188 -0.316406 2.5625 -0.628906 2.3125 -1.046875 Z M 6.234375 -3.5 C 6.234375 -4.34375 6.054688 -5.003906 5.703125 -5.484375 C 5.359375 -5.960938 4.882812 -6.203125 4.28125 -6.203125 C 3.664062 -6.203125 3.179688 -5.960938 2.828125 -5.484375 C 2.484375 -5.003906 2.3125 -4.34375 2.3125 -3.5 C 2.3125 -2.644531 2.484375 -1.976562 2.828125 -1.5 C 3.179688 -1.019531 3.664062 -0.78125 4.28125 -0.78125 C 4.882812 -0.78125 5.359375 -1.019531 5.703125 -1.5 C 6.054688 -1.976562 6.234375 -2.644531 6.234375 -3.5 Z M 6.234375 -3.5 "/>
</symbol>
<symbol overflow="visible" id="glyph0-8">
<path style="stroke:none;" d="M 3.921875 -6.1875 C 3.304688 -6.1875 2.816406 -5.945312 2.453125 -5.46875 C 2.097656 -4.988281 1.921875 -4.332031 1.921875 -3.5 C 1.921875 -2.65625 2.097656 -1.992188 2.453125 -1.515625 C 2.804688 -1.035156 3.296875 -0.796875 3.921875 -0.796875 C 4.535156 -0.796875 5.019531 -1.035156 5.375 -1.515625 C 5.726562 -2.003906 5.90625 -2.664062 5.90625 -3.5 C 5.90625 -4.320312 5.726562 -4.972656 5.375 -5.453125 C 5.019531 -5.941406 4.535156 -6.1875 3.921875 -6.1875 Z M 3.921875 -7.171875 C 4.921875 -7.171875 5.703125 -6.84375 6.265625 -6.1875 C 6.835938 -5.539062 7.125 -4.644531 7.125 -3.5 C 7.125 -2.351562 6.835938 -1.453125 6.265625 -0.796875 C 5.703125 -0.140625 4.921875 0.1875 3.921875 0.1875 C 2.910156 0.1875 2.117188 -0.140625 1.546875 -0.796875 C 0.984375 -1.453125 0.703125 -2.351562 0.703125 -3.5 C 0.703125 -4.644531 0.984375 -5.539062 1.546875 -6.1875 C 2.117188 -6.84375 2.910156 -7.171875 3.921875 -7.171875 Z M 3.921875 -7.171875 "/>
</symbol>
<symbol overflow="visible" id="glyph0-9">
<path style="stroke:none;" d="M 7.015625 -4.21875 L 7.015625 0 L 5.875 0 L 5.875 -4.1875 C 5.875 -4.851562 5.742188 -5.347656 5.484375 -5.671875 C 5.222656 -6.003906 4.835938 -6.171875 4.328125 -6.171875 C 3.703125 -6.171875 3.207031 -5.972656 2.84375 -5.578125 C 2.488281 -5.179688 2.3125 -4.640625 2.3125 -3.953125 L 2.3125 0 L 1.15625 0 L 1.15625 -7 L 2.3125 -7 L 2.3125 -5.90625 C 2.59375 -6.332031 2.914062 -6.648438 3.28125 -6.859375 C 3.65625 -7.066406 4.085938 -7.171875 4.578125 -7.171875 C 5.378906 -7.171875 5.984375 -6.921875 6.390625 -6.421875 C 6.804688 -5.921875 7.015625 -5.1875 7.015625 -4.21875 Z M 7.015625 -4.21875 "/>
</symbol>
<symbol overflow="visible" id="glyph0-10">
<path style="stroke:none;" d="M 5.8125 -5.9375 L 5.8125 -9.71875 L 6.953125 -9.71875 L 6.953125 0 L 5.8125 0 L 5.8125 -1.046875 C 5.570312 -0.628906 5.265625 -0.316406 4.890625 -0.109375 C 4.523438 0.0859375 4.082031 0.1875 3.5625 0.1875 C 2.71875 0.1875 2.03125 -0.148438 1.5 -0.828125 C 0.96875 -1.503906 0.703125 -2.394531 0.703125 -3.5 C 0.703125 -4.59375 0.96875 -5.476562 1.5 -6.15625 C 2.03125 -6.832031 2.71875 -7.171875 3.5625 -7.171875 C 4.082031 -7.171875 4.523438 -7.066406 4.890625 -6.859375 C 5.265625 -6.660156 5.570312 -6.351562 5.8125 -5.9375 Z M 1.890625 -3.5 C 1.890625 -2.644531 2.0625 -1.976562 2.40625 -1.5 C 2.757812 -1.019531 3.238281 -0.78125 3.84375 -0.78125 C 4.457031 -0.78125 4.9375 -1.019531 5.28125 -1.5 C 5.632812 -1.976562 5.8125 -2.644531 5.8125 -3.5 C 5.8125 -4.34375 5.632812 -5.003906 5.28125 -5.484375 C 4.9375 -5.960938 4.457031 -6.203125 3.84375 -6.203125 C 3.238281 -6.203125 2.757812 -5.960938 2.40625 -5.484375 C 2.0625 -5.003906 1.890625 -4.34375 1.890625 -3.5 Z M 1.890625 -3.5 "/>
</symbol>
<symbol overflow="visible" id="glyph0-11">
<path style="stroke:none;" d=""/>
</symbol>
<symbol overflow="visible" id="glyph0-12">
<path style="stroke:none;" d="M 1.25 -9.328125 L 2.515625 -9.328125 L 2.515625 -1.0625 L 7.0625 -1.0625 L 7.0625 0 L 1.25 0 Z M 1.25 -9.328125 "/>
</symbol>
<symbol overflow="visible" id="glyph0-13">
<path style="stroke:none;" d="M 1.203125 -7 L 2.359375 -7 L 2.359375 0 L 1.203125 0 Z M 1.203125 -9.71875 L 2.359375 -9.71875 L 2.359375 -8.265625 L 1.203125 -8.265625 Z M 1.203125 -9.71875 "/>
</symbol>
<symbol overflow="visible" id="glyph0-14">
<path style="stroke:none;" d="M 9.359375 -6.296875 L 2.921875 -4 L 9.359375 -1.71875 L 9.359375 -0.59375 L 1.359375 -3.5 L 1.359375 -4.53125 L 9.359375 -7.4375 Z M 9.359375 -6.296875 "/>
</symbol>
<symbol overflow="visible" id="glyph0-15">
<path style="stroke:none;" d="M 1.25 -9.328125 L 7.15625 -9.328125 L 7.15625 -8.265625 L 2.515625 -8.265625 L 2.515625 -5.5 L 6.953125 -5.5 L 6.953125 -4.4375 L 2.515625 -4.4375 L 2.515625 -1.0625 L 7.265625 -1.0625 L 7.265625 0 L 1.25 0 Z M 1.25 -9.328125 "/>
</symbol>
<symbol overflow="visible" id="glyph0-16">
<path style="stroke:none;" d="M 1.25 -9.328125 L 2.953125 -9.328125 L 7.09375 -1.53125 L 7.09375 -9.328125 L 8.3125 -9.328125 L 8.3125 0 L 6.609375 0 L 2.484375 -7.796875 L 2.484375 0 L 1.25 0 Z M 1.25 -9.328125 "/>
</symbol>
<symbol overflow="visible" id="glyph0-17">
<path style="stroke:none;" d="M 5.6875 -4.375 C 5.957031 -4.28125 6.21875 -4.082031 6.46875 -3.78125 C 6.726562 -3.488281 6.984375 -3.078125 7.234375 -2.546875 L 8.515625 0 L 7.171875 0 L 5.96875 -2.390625 C 5.664062 -3.015625 5.367188 -3.425781 5.078125 -3.625 C 4.785156 -3.832031 4.390625 -3.9375 3.890625 -3.9375 L 2.515625 -3.9375 L 2.515625 0 L 1.25 0 L 1.25 -9.328125 L 4.109375 -9.328125 C 5.171875 -9.328125 5.960938 -9.101562 6.484375 -8.65625 C 7.015625 -8.207031 7.28125 -7.535156 7.28125 -6.640625 C 7.28125 -6.054688 7.140625 -5.566406 6.859375 -5.171875 C 6.585938 -4.785156 6.195312 -4.519531 5.6875 -4.375 Z M 2.515625 -8.296875 L 2.515625 -4.984375 L 4.109375 -4.984375 C 4.710938 -4.984375 5.171875 -5.125 5.484375 -5.40625 C 5.796875 -5.6875 5.953125 -6.097656 5.953125 -6.640625 C 5.953125 -7.179688 5.796875 -7.59375 5.484375 -7.875 C 5.171875 -8.15625 4.710938 -8.296875 4.109375 -8.296875 Z M 2.515625 -8.296875 "/>
</symbol>
<symbol overflow="visible" id="glyph0-18">
<path style="stroke:none;" d="M 1.359375 -6.296875 L 1.359375 -7.4375 L 9.359375 -4.53125 L 9.359375 -3.5 L 1.359375 -0.59375 L 1.359375 -1.71875 L 7.796875 -4 Z M 1.359375 -6.296875 "/>
</symbol>
</g>
</defs>
<g id="surface3285">
<rect x="0" y="0" width="279" height="156" style="fill:rgb(100%,100%,100%);fill-opacity:1;stroke:none;"/>
<path style="fill-rule:evenodd;fill:rgb(100%,100%,100%);fill-opacity:1;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(0%,0%,0%);stroke-opacity:1;stroke-miterlimit:10;" d="M 30.7 0 L 34.7 0 L 34.7 1.2 L 30.7 1.2 Z M 30.7 0 " transform="matrix(20,0,0,20,-612,2)"/>
<g style="fill:rgb(0%,0%,0%);fill-opacity:1;">
<use xlink:href="#glyph0-1" x="10" y="18.005968"/>
<use xlink:href="#glyph0-2" x="15" y="18.005968"/>
<use xlink:href="#glyph0-3" x="22.777778" y="18.005968"/>
<use xlink:href="#glyph0-4" x="30.833333" y="18.005968"/>
<use xlink:href="#glyph0-2" x="38.888889" y="18.005968"/>
<use xlink:href="#glyph0-5" x="46.666667" y="18.005968"/>
<use xlink:href="#glyph0-6" x="53.333333" y="18.005968"/>
<use xlink:href="#glyph0-2" x="58.333333" y="18.005968"/>
<use xlink:href="#glyph0-1" x="66.111111" y="18.005968"/>
</g>
<path style="fill-rule:evenodd;fill:rgb(100%,100%,100%);fill-opacity:1;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(0%,0%,0%);stroke-opacity:1;stroke-miterlimit:10;" d="M 40.5 0 L 44.5 0 L 44.5 1.2 L 40.5 1.2 Z M 40.5 0 " transform="matrix(20,0,0,20,-612,2)"/>
<g style="fill:rgb(0%,0%,0%);fill-opacity:1;">
<use xlink:href="#glyph0-1" x="206" y="18.005968"/>
<use xlink:href="#glyph0-2" x="211" y="18.005968"/>
<use xlink:href="#glyph0-5" x="218.777778" y="18.005968"/>
<use xlink:href="#glyph0-7" x="225.444444" y="18.005968"/>
<use xlink:href="#glyph0-8" x="233.5" y="18.005968"/>
<use xlink:href="#glyph0-9" x="241.277778" y="18.005968"/>
<use xlink:href="#glyph0-10" x="249.333333" y="18.005968"/>
<use xlink:href="#glyph0-2" x="257.388889" y="18.005968"/>
<use xlink:href="#glyph0-1" x="265.166667" y="18.005968"/>
</g>
<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(0%,0%,0%);stroke-opacity:1;stroke-miterlimit:10;" d="M 32.7 1.2 L 32.7 7.6 " transform="matrix(20,0,0,20,-612,2)"/>
<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(0%,0%,0%);stroke-opacity:1;stroke-miterlimit:10;" d="M 42.5 1.2 L 42.5 7.6 " transform="matrix(20,0,0,20,-612,2)"/>
<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(0%,0%,0%);stroke-opacity:1;stroke-miterlimit:10;" d="M 32.7 2.4 L 42.016211 3.445703 " transform="matrix(20,0,0,20,-612,2)"/>
<path style="fill-rule:evenodd;fill:rgb(0%,0%,0%);fill-opacity:1;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(0%,0%,0%);stroke-opacity:1;stroke-miterlimit:10;" d="M 42.388867 3.4875 L 41.864063 3.680273 L 42.016211 3.445703 L 41.919922 3.183398 Z M 42.388867 3.4875 " transform="matrix(20,0,0,20,-612,2)"/>
<g style="fill:rgb(0%,0%,0%);fill-opacity:1;">
<use xlink:href="#glyph0-11" x="96" y="106.005968"/>
<use xlink:href="#glyph0-12" x="100.166667" y="106.005968"/>
<use xlink:href="#glyph0-13" x="107.388889" y="106.005968"/>
<use xlink:href="#glyph0-5" x="111" y="106.005968"/>
<use xlink:href="#glyph0-6" x="117.666667" y="106.005968"/>
<use xlink:href="#glyph0-14" x="122.666667" y="106.005968"/>
<use xlink:href="#glyph0-15" x="133.5" y="106.005968"/>
<use xlink:href="#glyph0-16" x="141.555556" y="106.005968"/>
<use xlink:href="#glyph0-17" x="151" y="106.005968"/>
<use xlink:href="#glyph0-18" x="159.888889" y="106.005968"/>
</g>
<g style="fill:rgb(0%,0%,0%);fill-opacity:1;">
<use xlink:href="#glyph0-1" x="112" y="52.005968"/>
<use xlink:href="#glyph0-2" x="117" y="52.005968"/>
<use xlink:href="#glyph0-3" x="124.777778" y="52.005968"/>
<use xlink:href="#glyph0-4" x="132.833333" y="52.005968"/>
<use xlink:href="#glyph0-2" x="140.888889" y="52.005968"/>
<use xlink:href="#glyph0-5" x="148.666667" y="52.005968"/>
<use xlink:href="#glyph0-6" x="155.333333" y="52.005968"/>
</g>
<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(0%,0%,0%);stroke-opacity:1;stroke-miterlimit:10;" d="M 42.5 5.3 L 33.184375 6.250586 " transform="matrix(20,0,0,20,-612,2)"/>
<path style="fill-rule:evenodd;fill:rgb(0%,0%,0%);fill-opacity:1;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(0%,0%,0%);stroke-opacity:1;stroke-miterlimit:10;" d="M 32.811133 6.288672 L 33.283203 5.989258 L 33.184375 6.250586 L 33.333984 6.486523 Z M 32.811133 6.288672 " transform="matrix(20,0,0,20,-612,2)"/>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

336
informational/adversarial-models.md Normal file
View File

@ -0,0 +1,336 @@
---
title: ADVERSARIAL-MODELS
name: Waku v2 Adversarial Models and Attack-based Threat List
category: Informational
tags:
editor: Daniel Kaiser <danielkaiser@status.im>
contributors:
---
## Abstract
This document lists adversarial models and attack-based threats relevant in the context of Waku v2.
## Motivation and Background
Future versions of this document will serve as a comprehensive list of adversarial models and attack based threats relevant for [Waku v2](https://rfc.vac.dev/spec/10/).
The main purpose of this document is being a linkable resource for specifications that address protection as well as mitigation mechanisms within the listed models.
Discussing and introducing countermeasures to specific attacks in specific models is out of scope for this document.
Analyses and further information about Waku's properties within these models may be found in our *Waku v2 Anonymity Analysis* series of research log posts:
* [Part I: Definitions and Waku Relay](https://vac.dev/wakuv2-relay-anon)
Note: This document adds to the adversarial models and threat list discussed in our [research log post](https://vac.dev/wakuv2-relay-anon).
It does not cover analysis of Waku, as the research log post does.
Future versions of this document will extend the adversarial models and threat list.
## Informal Definitions: Security, Privacy, and Anonymity
The concepts of security, privacy, and anonymity are linked and have quite a bit of overlap.
### Security
Of the three, [Security](https://en.wikipedia.org/wiki/Information_security) has the clearest agreed upon definition,
at least regarding its key concepts: *confidentiality*, *integrity*, and *availability*.
* confidentiality: data is not disclosed to unauthorized entities.
* integrity: data is not modified by unauthorized entities.
* availability: data is available, i.e. accessible by authorized entities.
While these are the key concepts, the definition of information security has been extended over time including further concepts,
e.g. [authentication](https://en.wikipedia.org/wiki/Authentication) and [non-repudiation](https://en.wikipedia.org/wiki/Non-repudiation).
### Privacy
Privacy allows users to choose which data and information
* they want to share
* and with whom they want to share it.
This includes data and information that is associated with and/or generated by users.
Protected data also comprises metadata that might be generated without users being aware of it.
This means, no further information about the sender or the message is leaked.
Metadata that is protected as part of the privacy-preserving property does not cover protecting the identities of sender and receiver.
Identities are protected by the [anonymity property](#anonymity).
Often privacy is realized by the confidentiality property of security.
This neither makes privacy and security the same, nor the one a sub category of the other.
While security is abstract itself (its properties can be realized in various ways), privacy lives on a more abstract level using security properties.
Privacy typically does not use integrity and availability.
An adversary who has no access to the private data, because the message has been encrypted, could still alter the message.
### Anonymity
Privacy and anonymity are closely linked.
Both the identity of a user and data that allows inferring a user's identity should be part of the privacy policy.
For the purpose of analysis, we want to have a clearer separation between these concepts.
We define anonymity as *unlinkablity of users' identities and their shared data and/or actions*.
We subdivide anonymity into *receiver anonymity* and *sender anonymity*.
#### Receiver Anonymity
We define receiver anonymity as *unlinkability of users' identities and the data they receive and/or related actions*.
Because each [Waku message](https://rfc.vac.dev/spec/14/) is associated with a content topic, and each receiver is interested in messages with specific content topics,
receiver anonymity in the context of Waku corresponds to *subscriber-topic unlinkability*.
An example for the "action" part of our receiver anonymity definition is subscribing to a specific topic.
#### Sender Anonymity
We define sender anonymity as *unlinkability of users' identities and the data they send and/or related actions*.
Because the data in the context of Waku is Waku messages, sender anonymity corresponds to *sender-message unlinkability*.
#### Anonymity Trilemma
[The Anonymity trilemma](https://freedom.cs.purdue.edu/projects/trilemma.html) states that only two out of *strong anonymity*, *low bandwidth*, and *low latency* can be guaranteed in the *global attacker* model.
Waku's goal, being a modular set of protocols, is to offer any combination of two out of these three properties, as well as blends.
A fourth factor that influences [the anonymity trilemma](https://freedom.cs.purdue.edu/projects/trilemma.html) is *frequency and patterns* of messages.
The more messages there are, and the more randomly distributed they are, the better the anonymity protection offered by a given anonymous communication protocol.
So, incentivising users to use the protocol, for instance by lowering entry barriers, helps protecting the anonymity of all users.
The frequency/patterns factor is also related to [k-anonymity](https://en.wikipedia.org/wiki/K-anonymity).
### Censorship Resistance
Another security related property that Waku aims to offer is censorship resistance.
Censorship resistance guarantees that users can participate even if an attacker tries to deny them access.
So, censorship resistance ties into the availability aspect of security.
In the context of Waku that means users should be able to send messages as well as receive all messages they are interested in,
even if an attacker tries to prevent them from disseminating messages or tries to deny them access to messages.
An example for a censorship resistance technique is Tor's [Pluggable Transports](https://www.pluggabletransports.info/about/).
## Adversarial Models
The following lists various attacker types with varying degrees of power.
The more power an attacker has, the more difficult it is to gain the respective attacker position.
Each attacker type comes in a passive and an active variant.
While a passive attacker can stay hidden and is not suspicious,
the respective active attacker has more (or at least the same) deanonymization power.
We also distinguish between internal and external attackers.
Since in permissionless protocols it is easy to obtain an internal position,
in practice attackers are expected to mount combined attacks that leverage both internal and external attacks.
### Internal
In the passive variant, an internal attacker behaves like an honest node towards peers.
The passive internal attacker has the same access rights as any honest node.
In the active variant, an internal attacker can additionally drop, inject, and alter messages.
With respect to Waku relay, for example, an internal attacker participates in the same pubsub topic as its victims,
and can read messages related to that topic.
#### Single Node
This attacker controls a single node.
#### Multi Node
This attacker controls a fixed number of nodes (not scaling with the total number of nodes in the network).
The multi node position can be achieved by setting up multiple nodes.
Botnets might be leveraged to increase the number of available hosts.
Multi node attackers could use [Sybil attacks](https://en.wikipedia.org/wiki/Sybil_attack) to increase the number of controlled nodes.
A countermeasure is for nodes to only accept libp2p gossipsub graft requests from peers with different IP addresses, or even different subnets.
Nodes controlled by the attacker can efficiently communicate out-of-band to coordinate.
#### Scaling Multi Node
This attacker controls a number of nodes that scales linearly with the number of nodes in the network.
The attacker controls $p%$ of all nodes in the network.
Nodes controlled by the attacker can efficiently communicate out-of-band to coordinate.
### External
An external attacker can only see encrypted traffic.
Waku protocols are protected by a secure channel set up with [Noise](../standards/core/noise.md).
#### Local
A local attacker has access to communication links in a local network segment.
This could be a rogue access point (with routing capability).
#### AS
An AS attacker controls a single AS (autonomous system).
A passive AS attacker can listen to traffic on arbitrary links within the AS.
An active AS attacker can drop, delay, inject, and alter traffic on arbitrary links within the AS.
In practice, a malicious ISP would be considered as an AS attacker.
A malicious ISP could also easily setup a set of nodes at specific points in the network,
gaining internal attack power similar to a strong *multi node* or even *scaling multi node* attacker.
#### Global (On-Net)
A global (on-net) attacker has complete overview over the whole network.
A passive global attacker can listen to traffic on all links,
while the active global attacker basically carries the traffic: it can freely drop, delay, inject, and alter traffic at all positions in the network.
This basically corresponds to the [Dolev-Yao model](https://en.wikipedia.org/wiki/Dolev%E2%80%93Yao_model).
An entity with this power would, in practice, also have the power of the internal *scaling multi node* attacker.
## Attack-based Threats
The following lists various attacks against [Waku v2](https://rfc.vac.dev/spec/10/) protocols.
If not specifically mentioned, the attacks refer to [Waku relay](/spec/11) and the underlying [libp2p GossipSub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md).
We also list the weakest attacker model in which the attack can be successfully performed against.
An attack is considered more powerful if it can be successfully performed in a weaker attacker model.
Note: This list is work in progress.
We will either expand this list adding more attacks in future versions of this document,
or remove it and point to the "Security Considerations" sections of respective RFCs.
### Prerequisite: Get a Specific Position in the Network
Some attacks require the attacker node(s) to be in a specific position in the network.
In most cases, this corresponds to trying to get into the mesh peer list for the desired pubsub topic of the victim node.
In libp2p gossipsub, and by extension Waku v2 relay, nodes can simply send a graft message for the desired topic to the victim node.
If the victim node still has open slots, the attacker gets the desired position.
This only requires the attacker to know the gossipsub multiaddress of the victim node.
A *scaling multi node* attacker can leverage DHT based discovery systems to boost the probability of malicious nodes being returned,
which in turn significantly increases the probability of attacker nodes ending up in the peer lists of victim nodes.
### Sender Deanonymization
This section lists attacks that aim at deanonymizing a message sender.
We assume that protocol messages are transmitted within a secure channel set up using the [Noise Protocol Framework](https://noiseprotocol.org/).
For [Waku Relay](https://rfc.vac.dev/spec/11/) this means we only consider messages with version field `2`,
which indicates that the payload has to be encoded using [Noise](../standards/core/noise.md).
Note: The currently listed attacks are against libp2p in general.
The [data field of Waku v2 relay](https://rfc.vac.dev/spec/11/#message-fields) must be a [Waku v2 message](https://rfc.vac.dev/spec/14/).
The attacks listed in the following do not leverage that fact.
#### Replay Attack
In a replay attack, the attacker replays a valid message it received.
Waku relay is inherently safe against replay attack,
because GossipSub nodes, and by extension Waku relay nodes,
feature a `seen` cache, and only relay messages they have not seen before.
Further, replay attacks will be punished by [RLN Relay](https://rfc.vac.dev/spec/17/).
#### Observing Messages
If Waku relay was not protected with Noise, the AS attacker could simply check for messages leaving $v$ which have not been relayed to $v$.
These are the messages sent by $v$.
Waku relay protects against this attack by employing secure channels setup using Noise.
#### Neighbourhood Surveillance
This attack can be performed by a single node attacker that is connected to all peers of the victim node $v$ with respect to a specific topic mesh.
The attacker also has to be connected to $v$.
In this position, the attacker will receive messages $m_v$ sent by $v$ both on the direct path from $v$, and on indirect paths relayed by peers of $v$.
It will also receive messages $m_x$ that are not sent by $v$. These messages $m_x$ are relayed by both $v$ and the peers of $v$.
Messages that are received (significantly) faster from $v$ than from any other of $v$'s peers are very likely messages that $v$ sent,
because for these messages the attacker is one hop closer to the source.
The attacker can (periodically) measure latency between itself and $v$, and between itself and the peers of $v$ to get more accurate estimates for the expected timings.
An AS attacker (and if the topology allows, even a local attacker) could also learn the latency between $v$ and its well-behaving peers.
An active AS attacker could also increase the latency between $v$ and its peers to make the timing differences more prominent.
This, however, might lead to $v$ switching to other peers.
This attack cannot (reliably) distinguish messages $m_v$ sent by $v$ from messages $m_y$ relayed by peers of $v$ the attacker is not connected to.
Still, there are hop-count variations that can be leveraged.
Messages $m_v$ always have a hop-count of 1 on the path from $v$ to the attacker, while all other paths are longer.
Messages $m_y$ might have the same hop-count on the path from $v$ as well as on other paths.
Further techniques that are part of the *mass deanonymization* category, such as [bayesian analysis](#bayesian-analysis), can be used here as well.
#### Controlled Neighbourhood
If a multi node attacker manages to control all peers of the victim node, it can trivially tell which messages originated from $v$.
#### Correlation
Monitoring all traffic (in an AS or globally), allows the attacker to identify traffic correlated with messages originating from $v$.
This (alone) does not allow an external attacker to learn which message $v$ sent, but it allows identifying the respective traffic propagating through the network.
The more traffic in the network, the lower the success rate of this attack.
Combined with just a few nodes controlled by the attacker, the actual message associated with the correlated traffic can eventually be identified.
### Mass Deanonymization
While attacks in the *sender deanonymization* category target a set of either specific or arbitrary users,
attacks in the *mass deanonymization* category aim at deanonymizing (parts of) the whole network.
Mass deanonymization attacks do not necessarily link messages to senders.
They might only reduce the anonymity set in which senders hide,
or infer information about the network topology.
#### Graph Learning
Graph learning attacks are a prerequisite for some mass deanonymization attacks,
in which the attacker learns the overlay network topology.
Graph learning attacks require a *scaling multinode* attacker
For gossipsub this means an attacker learns the topic mesh for specific pubsub topics.
[Dandelion++](https://arxiv.org/abs/1805.11060) describes ways to perform this attack.
#### Bayesian Analysis
Bayesian analysis allows attackers to assign each node in the network a likelihood of having sent (originated) a specific message.
Bayesian analysis for mass deanonymization is detailed in [On the Anonymity of Peer-To-Peer Network Anonymity Schemes Used by Cryptocurrencies](https://arxiv.org/pdf/2201.11860).
It requires a *scaling node* attacker as well as knowledge of the network topology,
which can be learned via *graph learning* attacks.
### Denial of Service (DoS)
#### Flooding
In a flooding attack, attackers flood the network with bogus messages.
Waku employs [RLN Relay](https://rfc.vac.dev/spec/17/) as the main countermeasure to flooding.
[SWAP](https://rfc.vac.dev/spec/18/) also helps mitigating DoS attacks.
#### Black Hole (internal)
In a black hole attack, the attacker does not relay messages it is supposed to relay.
Analogous to a black hole, attacker nodes do not allow messages to leave once they entered.
While *single node* and smaller *multi node* attackers can have a negative effect on availability, the impact is not significant.
A *scaling multi node* attacker, however, can significantly disrupt the network with such an attack.
The effects of this attack are especially severe in conjunction with deanonymization mitigation techniques that reduce the out-degree of the overlay,
such as [Waku Dandelion](../standards/application/dandelion.md).
[Waku Dandelion](../standards/application/dandelion.md)) also discusses mitigation techniques compensating the amplified black hole potential.)
#### Traffic Filtering (external)
A local attacker can filter and drop all Waku traffic within its controlled network segment.
An AS attacker can filter and drop all Waku traffic within its authority, while a global attacker can censor the whole network.
A countermeasure are censorship resistance techniques like [Pluggable Transports](https://www.pluggabletransports.info/about/).
An entity trying to censor Waku can employ both the *black hole* attack and *traffic filtering*;
the former is internal while the latter is external.
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
* [10/WAKU2](https://rfc.vac.dev/spec/10/)
* [11/WAKU2-RELAY](https://rfc.vac.dev/spec/11/)
* [libp2p GossipSub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md)
* [Security](https://en.wikipedia.org/wiki/Information_security)
* [Authentication](https://en.wikipedia.org/wiki/Authentication)
* [Anonymity Trilemma](https://freedom.cs.purdue.edu/projects/trilemma.html)
* [Waku v2 message](https://rfc.vac.dev/spec/14/)
* [Pluggable Transports](https://www.pluggabletransports.info/about/)
* [Sybil attack](https://en.wikipedia.org/wiki/Sybil_attack)
* [Dolev-Yao model](https://en.wikipedia.org/wiki/Dolev%E2%80%93Yao_model)
* [Noise Protocol Framework](https://noiseprotocol.org/)
* [Noise](../standards/core/noise.md)
* [17/WAKU-RLN-RELAY](https://rfc.vac.dev/spec/17/)
* [18/WAKU2-SWAP](https://rfc.vac.dev/spec/18/)
* [Dandelion++](https://arxiv.org/abs/1805.11060)
* [On the Anonymity of Peer-To-Peer Network Anonymity Schemes Used by Cryptocurrencies](https://arxiv.org/pdf/2201.11860)
* [Waku Dandelion](../standards/application/dandelion.md))

56
informational/relay-static-shard-alloc.md Normal file
View File

@ -0,0 +1,56 @@
---
title: RELAY-STATIC-SHARD-ALLOC
name: Waku v2 Relay Static Shard Allocation
status: raw
category: Informational
tags: waku/informational
editor: Daniel Kaiser <danielkaiser@status.im>
contributors:
---
## Abstract
This document lists static shard flag index assignments (see [WAKU2-RELAY-SHARDING](../standards/core/relay-sharding.md)).
## Background
Similar to the [IANA port allocation](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml),
this document lists static shard index assignments (see [WAKU2-RELAY-SHARDING](../standards/core/relay-sharding.md).
## Assingment Process
> *Note*: Future versions of this document will specify the assignment process.
### List of Cluster Ids
| index | Protocol/App | Description |
| --- | --- | --- |
| 0 | global | global use |
| 1 | reserved | [The Waku Network](https://rfc.vac.dev/spec/64/#network-shards) |
| 2 | reserved | |
| 3 | reserved | |
| 4 | reserved | |
| 5 | reserved | |
| 6 | reserved | |
| 7 | reserved | |
| 8 | reserved | |
| 9 | reserved | |
| 10 | reserved | |
| 11 | reserved | |
| 12 | reserved | |
| 13 | reserved | |
| 14 | reserved | |
| 15 | reserved | |
| 16 | Status | Status main net |
| 17 | Status | |
| 18 | Status | |
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
* [WAKU2-RELAY-SHARDING](../standards/core/relay-sharding.md)
* [IANA port allocation](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml)

4
spellcheck.yaml Normal file
View File

@ -0,0 +1,4 @@
matrix:
- name: markdown
sources:
- '**/*.md'

297
standards/application/dandelion.md Normal file
View File

@ -0,0 +1,297 @@
---
title: DANDELION
name: Waku v2 Dandelion
category: Standards Track
tags: waku/anonymity
editor: Daniel Kaiser <danielkaiser@status.im>
contributors:
---
## Abstract
This document specifies a deanonymization mitigation technique,
based on [Dandelion](https://arxiv.org/abs/1701.04439) and [Dandelion++](https://arxiv.org/abs/1805.11060),
for Waku Relay.
It mitigates mass deanonymization in the [multi-node (botnet) attacker model](../../informational/adversarial-models.md/#multi-node),
even when the number of malicious nodes is linear in the number of total nodes in the network.
Based on the insight that symmetric message propagation makes deanonymization easier,
it introduces a probability for nodes to simply forward the message to one select relay node
instead of disseminating messages as per usual relay operation.
## Background and Motivation
[Waku Relay](https://rfc.vac.dev/spec/11/), offers privacy, pseudonymity, and a first layer of anonymity protection by design.
Being a modular protocol family [Waku v2](https://rfc.vac.dev/spec/10/)
offers features that inherently carry trade-offs as separate building blocks.
Anonymity protection is such a feature.
The [Anonymity Trilemma](https://freedom.cs.purdue.edu/projects/trilemma.html)
states that an anonymous communication network can only have two out of
low bandwidth consumption, low latency, and strong anonymity.
Even when choosing low bandwidth and low latency, which is the trade-off that basic Waku Relay takes,
better anonymity properties (even though not strong per definition) can be achieved by sacrificing some of the efficiency properties.
44/WAKU2-DANDELION specifies one such technique, and aims at gaining the best "bang for the buck"
in terms of efficiency paid for anonymity gain.
44/WAKU2-DANDELION is based on [Dandelion](https://arxiv.org/abs/1701.04439)
and [Dandelion++](https://arxiv.org/abs/1805.11060).
Dandelion is a message spreading method, which, compared to other methods,
increases the uncertainty of an attacker when trying to link messages to senders.
Libp2p gossipsub aims at spanning a [d-regular graph](https://en.wikipedia.org/wiki/Regular_graph) topology, with d=6 as the [default value](https://rfc.vac.dev/spec/29/#gossipsub-v10-parameters).
Messages are forwarded within this (expected) symmetric topology,
which reduces uncertainty when trying to link messages to senders.
Dandelion breaks this symmetry by subdividing message spreading into a "stem" and a "fluff" phase.
In the "stem" phase, the message is sent to a single select relay node.
With a certain probability, this message is relayed further on the "stem",
or enters the fluff phase.
On the stem, messages are relayed to single peers, respectively,
while in fluff phase, messages are spread as per usual relay operation (optionally augmented by random delays to further reduce symmetry).
The graph spanned by stem connections is referred to as the anonymity graph.
Note: This is an early raw version of the specification.
It does not strictly follow the formally evaluated Dandelion++ paper,
as we want to experiment with relaxing (and strengthening) certain model properties.
In specific, we aim at a version that has tighter latency bounds.
[Further research](https://arxiv.org/pdf/2201.11860.pdf) suggests that Dandelion++'s design choices are not optimal,
which further assures that tweaking design choices makes sense.
We will refine design decisions in future versions of this specification.
Further information on Waku anonymity may be found in our [Waku Privacy and Anonymity Analysis](https://vac.dev/wakuv2-relay-anon).
## Theory and Functioning
44/WAKU2-DANDELION can be seen as an anonymity enhancing add-on to [Waku Relay](https://rfc.vac.dev/spec/11/) message dissemination,
which is based on [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md).
44/WAKU2-DANDELION subdivides message dissemination into a "stem" and a "fluff" phase.
This specification is mainly concerned with specifying the stem phase.
The fluff phase corresponds to [Waku Relay](https://rfc.vac.dev/spec/11/),
with optional fluff phase augmentations such as random delays.
Adding random delay in the fluff phase further reduces symmetry in dissemination patterns and
introduces more uncertainty for the attacker.
Specifying fluff phase augmentations is out of scope for this document.
*Note:
We plan to add a separate specification for fluff phase augmentations.
We envision stem and fluff phase as abstract concepts.
The Dandelion stem and fluff phases instantiate these concepts.
Future stem specifications might comprise: none (standard relay), Dandelion stem, Tor, and mix-net.
As for future fluff specifications: none (standard relay), diffusion (random delays), and mix-net.*
Messages relayed by nodes supporting 44/WAKU2-DANDELION are either in stem phase or in fluff phase.
We refer to the former as a stem message and to the latter as a fluff message.
A message starts in stem phase, and at some point, transitions to fluff phase.
Nodes, on the other hand, are in stem state or fluff state.
Nodes in stem state relay stem messages to a single relay node, randomly selected per epoch for each incoming stem connection.
Nodes in fluff state transition stem messages into fluff phase and relay them accordingly.
Fluff messages are always disseminated via Waku Relay,
by both nodes in stem state and nodes in fluff state.
Messages originated in the node (i.e. messages coming from the application layer of our node),
are always sent as stem messages.
The stem phase can be seen as a different protocol, and messages are introduced into Waku Relay, and by extension gossipsub,
once they arrive at a node in fluff state for the first time.
44/WAKU2-DANDELION uses [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/) as the protocol for relaying stem messages.
There are no negative effects on gossipsub peer scoring,
because Dandelion nodes in *stem state* still normally relay Waku Relay (gossipsub) messages.
## Specification
Nodes $v$ supporting 44/WAKU2-DANDELION MUST either be in stem state or in fluff state.
This does not include relaying messages originated in $v$, for which $v$ SHOULD always be in stem state.
### Choosing the State
On startup and when a new epoch starts,
node $v$ randomly selects a number $r$ between 0 and 1.
If $r < q$, for $q = 0.2$, the node enters fluff state, otherwise, it enters stem state.
New epochs start when `unixtime` (in seconds) $\equiv 0 \mod 600$,
corresponding to 10 minute epochs.
### Stem State
On entering stem state,
nodes supporting 44/WAKU2-DANDELION MUST randomly select two nodes for each pubsub topic from the respective gossipsub mesh node set.
These nodes are referred to as stem relays.
Stem relays MUST support [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/).
If a chosen peer does not support [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/),
the node SHOULD switch to fluff state.
(We may update this strategy in future versions of this document.)
Further, the node establishes a map that maps each incoming stem connection
to one of its stem relays chosen at random (but fixed per epoch).
Incoming stem connections are identified by the [Peer IDs](https://docs.libp2p.io/concepts/peers/#peer-id/)
of peers the node receives [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/) messages from.
Incoming [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/) connections from peers that do not support 44/WAKU2-DANDELION are identified and mapped in the same way.
This makes the protocol simpler, increases the anonymity set, and offers Dandelion anonymity properties to such peers, too.
The node itself is mapped in the same way, so that all messages originated by the node are relayed via a per-epoch-fixed Dandelion relay, too.
While in stem state, nodes MUST relay stem messages to the respective stem relay.
Received fluff messages MUST be relayed as specified in the fluff state section.
The stem protocol ([19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/)) is independent of the fluff protocol ([Waku Relay](https://rfc.vac.dev/spec/11/)).
While in stem state, nodes MUST NOT gossip about stem messages,
and MUST NOT send control messages related to stem messages.
(An existing gossipsub implementation does *not* have to be adjusted to not send gossip about stem messages,
because these messages are only handed to gossipsub once they enter fluff phase.)
#### Fail Safe
Nodes $v$ in stem state SHOULD store messages attached with a random timer between $t_1 = 5 * 100ms$ and $t_2 = 2 * t_1$.
This time interval is chosen because
* we assume $100\,ms$ as an average per hop delay, and
* using $q=0.2$ will lead to an expected number of 5 stem hops per message.
If $v$ does not receive a given message via Waku Relay (fluff) before the respective timer runs out,
$v$ will disseminate the message via Waku Relay.
### Fluff State
In fluff state, nodes operate as usual Waku Relay nodes.
The Waku Relay functionality might be augmented by a future specification, e.g. adding random delays.
Note: The [Dandelion](https://arxiv.org/abs/1701.04439) paper describes the fluff phase as regular forwarding.
Since Dandelion is designed as an update to the Bitcoin network using diffusion spreading,
this regular forwarding already comprises random delays.
## Implementation Notes
Handling of the 44/WAKU2-DANDELION stem phase can be implemented as an extension to an existing [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/) implementation.
Fluff phase augmentations might alter gossipsub message dissemination (e.g. adding random delays).
If this is the case, they have to be implemented on the libp2p gossipsub layer.
## Security/Privacy Considerations
### Denial of Service: Black Hole Attack
In a [black hole attack](../../informational/adversarial-models.md/#black-hole-internal), malicious nodes prevent messages from being spread,
metaphorically not allowing messages to leave once they entered.
This requires the attacker to control nodes on all dissemination paths.
Since the number of dissemination paths is significantly reduced in the stem phase,
Dandelion spreading reduces the requirements for a black hole attack.
The fail-safe mechanism specified in this document (proposed in the Dandelion paper), mitigates this.
### Anonymity Considerations
#### Attacker Model and Anonymity Goals
44/WAKU2-DANDELION provides significant mitigation against mass deanonymization in the
passive [scaling multi node model](../../informational/adversarial-models.md/#scaling-multi-node).
in which the attacker controls a certain percentage of nodes in the network.
44/WAKU2-DANDELION provides significant mitigation against mass deanonymization
even if the attacker knows the network topology, i.e. the anonymity graph and the relay mesh graph.
Mitigation in stronger models, including the *active scaling multi-node* model, is weak.
We will elaborate on this in future versions of this document.
44/WAKU2-DANDELION does not protect against targeted deanonymization attacks.
#### Non-Dandelion Peers
Stem relays receiving messages can either be in stem state or in fluff state themselves.
They might also not support 44/WAKU2-DANDELION,
and interpret the message as classical [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/),
which effectively makes them act as fluff state relays.
While such peers lower the overall anonymity properties,
the [Dandelion++ paper](https://arxiv.org/abs/1805.11060)
showed that including those peers yields more anonymity compared to excluding these peers.
### Future Analysis
The following discusses potential relaxations in favour of reduced latency,
as well as their impact on anonymity.
This is still work in progress and will be elaborated on in future versions of this document.
Generally, there are several design choices to be made for the stem phase of a Dandelion-based specification:
1) the probability of continuing the stem phase, which determines the expected stem lengh,
2) the out degree in the stem phase, which set to 1 in this document (also in the Dandelion papers),
3) the rate of re-selecting stem relays among all gossipsub mesh peers (for a given pubsub topic), and
4) the mapping of incoming connections to outgoing connections.
#### Bound Stem Length
Choosing $q = 0.2$, 44/WAKU2-DANDELION has an expected stem length of 5 hops,
Assuming $100ms$ added delay per hop, the stem phase adds around 500ms delay on average.
There is a possibility for the stem to grow longer,
but some applications need tighter bounds on latency.
While fixing the stem length would yield tighter latency bounds,
it also reduces anonymity properties.
A fixed stem length requires the message to carry information about the remaining stem length.
This information reduces the uncertainty of attackers
when calculating the probability distribution assigning each node a probability for having sent a specific message.
We will quantify the resulting loss of anonymity in future versions of this document.
#### Stem Relay Selection
In its current version, 44/WAKU2-DANDELION nodes default to fluff state
if the random stem relay selection yields at least one peer that does not support [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/) (which is the stem protocol used in [44/WAKU2-DANDELION](https://rfc.vac.dev/spec/44/).
If nodes would reselect peers until they find peers supporting [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/),
malicious nodes would get an advantage if a significant number of honest nodes would not support [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19).
Even though this causes messages to enter fluff phase earlier,
we choose the trade-off in favour of protocol stability and sacrifice a bit of anonymity.
(We will look into improving this in future versions of this document.)
#### Random Delay in Fluff Phase
[Dandelion](https://arxiv.org/abs/1701.04439) and [Dandelion++](https://arxiv.org/abs/1805.11060)
assume adding random delays in the fluff phase as they build on Bitcoin diffusion.
44/WAKU2-DANDELION (in its current state) allows for zero delay in the fluff phase and outsources fluff augmentations to dedicated specifications.
While this lowers anonymity properties, it allows making Dandelion an opt-in solution in a given network.
Nodes that do not want to use Dandelion do not experience any latency increase.
We will quantify and analyse this in future versions of this specification.
We plan to add a separate fluff augmentation specification that will introduce random delays.
Optimal delay times depend on the message frequency and patterns.
This delay fluff augmentation specification will be oblivious to the actual message content,
because Waku Dandelion specifications add anonymity on the routing layer.
Still, it is important to note that [Waku2 messages](https://rfc.vac.dev/spec/14/#payloads) (in their current version) carry an originator timestamp,
which works against fluff phase random delays.
An analysis of the benefits of this timestamp versus anonymity risks is on our roadmap.
By adding a delay, the fluff phase modifies the behaviour of [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md),
which Waku Relay builds upon.
Note: Introducing random delays can have a negative effect on
[peer scoring](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#peer-scoring).
#### Stem Flag
While 44/WAKU2-DANDELION without fluff augmentation does not effect Waku Relay nodes,
messages sent by nodes that only support [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/) might be routed through a Dandelion stem without them knowing.
While this improves anonymity, as discussed above, it also introduces additional latency and lightpush nodes cannot opt out of this.
In future versions of this specification we might
* add a flag to [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/) indicating a message should be routed over a Dandelion stem (opt-in), or
* add a flag to [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/) indicating a message should *not* be routed over a Dandelion stem (opt-out), or
* introducing a fork of [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/) exclusively used for Dandelion stem.
In the current version, we decided against these options in favour of a simpler protocol and an increased anonymity set.
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
* [Dandelion](https://arxiv.org/abs/1701.04439)
* [Dandelion++](https://arxiv.org/abs/1805.11060)
* [multi-node (botnet) attacker model](../../informational/adversarial-models.md/#multi-node)
* [Waku Relay](https://rfc.vac.dev/spec/11/)
* [Waku v2](https://rfc.vac.dev/spec/10/)
* [d-regular graph](https://en.wikipedia.org/wiki/Regular_graph)
* [Anonymity Trilemma](https://freedom.cs.purdue.edu/projects/trilemma.html)
* [Waku Privacy and Anonymity Analysis](https://vac.dev/wakuv2-relay-anon).
* [On the Anonymity of Peer-To-Peer Network Anonymity Schemes Used by Cryptocurrencies](https://arxiv.org/pdf/2201.11860.pdf)
* [Adversarial Models](https://rfc.vac.dev/spec/45/)
* [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/)

358
standards/application/device-pairing.md Normal file
View File

@ -0,0 +1,358 @@
---
title: WAKU2-DEVICE-PAIRING
name: Device pairing and secure transfers with Noise
category: Standards Track
tags: waku/core-protocol
editor: Giuseppe <giuseppe@status.im>
contributors:
---
## Abstract
In this document we describe a compound protocol
for enabling two devices to mutually authenticate
and securely exchange (arbitrary) information over the Waku network.
## Background / Rationale / Motivation
In order to implement multi-device communications using one of the Noise session management mechanisms proposed in [WAKU2-NOISE-SESSIONS](./noise-sessions/noise-sessions.md),
we require a protocol to securely exchange (cryptographic) information between 2 or more devices possessed by a user.
Since, in this scenario, the devices would be close to each other,
authentication can be initialized by exchanging a QR code out-of-band
and then securely completed over the Waku network.
The protocol we propose consists of two main subprotocols or *phases*:
- [Device Pairing](#Device-Pairing): two phisically close devices initialize the *pairing* by exchanging a QR code out-of-band. The devices then exchange and authenticate their respective long-term device ID static key by exchanging handshake messages over the Waku network;
- [Secure Transfer](#Secure-Transfer): the devices securely exchange information in encrypted form using key material obtained during a successful pairing phase. The communication will happen over the Waku network, hence the devices do not need to be phisically close in this phase.
## Theory / Semantics
### Device Pairing
In the pairing phase, device `B` requests to be paired to a device `A`.
Once the two devices are paired, the devices will be mutually authenticated
and will share a Noise session within which they can securely exchange information.
The request is made by exposing a QR code that, by default, has to be scanned by device `A`.
If device `A` doesn't have a camera while device `B` does,
[it is possible](#Rationale) to execute a slightly different pairing (with same security guarantees),
where `A` is exposing a QR code instead.
This protocol is designed in order to achieve two main security objectives:
- resistance to Man-in-the-Middle attacks;
- provide network anonymity on devices' static keys, i.e. only paired devices will learn each other static key.
#### Employed Cryptographic Primitives
- `H`: the underlying cryptographically-secure hash function, e.g. SHA-256;
- `HKDF`: the key derivation function (based on `H`);
- `Curve25519`: the underlying elliptic curve for Diffie-Hellman (DH) operations.
#### The `WakuPairing` Noise Handshake
The devices execute a custom handshake derived from `XX`,
where they mutually exchange and authenticate their respective device static key
by exchanging messages over the content topic with the following [format](https://rfc.vac.dev/spec/23/#content-topic-format)
```
contentTopic = /{application-name}/{application-version}/wakunoise/1/sessions_shard-{shard-id}/proto
```
The handshake, detailed in next section, can be summarized as:
```
WakuPairing:
a. <- eB {H(sB||r), contentTopicParams, messageNametag}
...
b. -> eA, eAeB {H(sA||s)} [authcode]
c. <- sB, eAsB {r}
d. -> sA, sAeB, sAsB {s}
{}: payload, []: user interaction
```
#### Protocol Flow
1. The device `B` exposes through a QR code a [base64 (url safe)](https://datatracker.ietf.org/doc/html/rfc4648#section-5) serialization of:
- An ephemeral public key `eB`;
- The content topic parameters `contentTopicParams = {application-name}, {application-version}, {shard-id}`.
- A (randomly generated) 16-bytes long `messageNametag`.
- A commitment `H(sB||r)` for its static key `sB` where `r` is a random fixed-lenght value.
2. The device `A`:
- scans the QR code;
- obtains `eB`, `contentTopicParams`, `messageNametag`, `Hash(sB||r)`;
- checks if `{application-name}` and `{application-version}` from `contentTopicParams` match the local application name and version: if not, aborts the pairing. Sets `contentTopic = /{application-name}/{application-version}/wakunoise/1/sessions_shard-{shard-id}/proto`;
- initializes the Noise handshake by passing `contentTopicParams`, `messageNametag` and `Hash(sB||r)` to the handshake prologue;
- executes the pre-handshake message, i.e. processes the key `eB`;
- executes the first handshake message over `contentTopic`, i.e.
- processes and sends a Waku message containing an ephemeral key `eA`;
- performs `DH(eA,eB)` (which computes a symmetric encryption key);
- attaches as payload to the handshake message the (encrypted) commitment `H(sA||s)` for `A`'s static key `sA`, where `s` is a random fixed-length value;
- an 8-digits authorization code `authcode` obtained as `HKDF(h) mod 10^8` is displayed on the device, where `h` is the [handshake hash value](https://noiseprotocol.org/noise.html#overview-of-handshake-state-machine) obtained once the first handshake message is processed.
3. The device `B`:
- sets `contentTopic = /{application-name}/{application-version}/wakunoise/1/sessions_shard-{shard-id}/proto`;
- listens to messages sent to `contentTopic` and locally filters only those with [Waku payload](./noise.md/#abnf) starting with `messageNametag`. If any, continues.
- initializes the Noise handshake by passing `contentTopicParams`, `messageNametag` and `Hash(sB||r)` to the handshake prologue;
- executes the pre-handshake message, i.e. processes its ephemeral key `eB`;
- executes the first handshake message, i.e.
- obtains from the received message a public key `eA`. If `eA` is not a valid public key, the protocol is aborted.
- performs `DH(eA,eB)` (which computes a symmetric encryption key);
- decrypts the commitment `H(sA||s)` for `A`'s static key `sA`.
- an 8 decimal digits authorization code `authcode` obtained as `HKDF(h) mod 10^8` is displayed on the device, where `h`is the [handshake hash value](https://noiseprotocol.org/noise.html#overview-of-handshake-state-machine) obtained once the first handshake message is processed.
4. Device `A` and `B` wait for the user to confirm with an interaction (button press)
that the authorization code displayed on both devices are the same.
If not, the protocol is aborted.
5. The device `B`:
- executes the second handshake message, i.e.
- processes and sends his (encrypted) device static key `sB` over `contentTopic`;
- performs `DH(eA,sB)` (which updates the symmetric encryption key);
- attaches as payload the (encrypted) commitment randomness `r` used to compute `H(sB||r)`.
6. The device `A`:
- listens to messages sent to `contentTopic` and locally filters only those with Waku payload starting with `messageNametag`. If any, continues.
- decrypts the received message and obtains the public key `sB`. If `sB` is not a valid public key, the protocol is aborted.
- performs `DH(eA,sB)` (which updates a symmetric encryption key);
- decrypts the payload to obtain the randomness `r`.
- computes `H(sB||r)` and checks if this value corresponds to the commitment obtained in step 2. If not, the protocol is aborted.
- executes the third handshake message, i.e.
- processes and sends his (encrypted) device static key `sA` over `contentTopic`;
- performs `DH(sA,eB)` (which updates the symmetric encryption key);
- performs `DH(sA,sB)` (which updates the symmetric encryption key);
- attaches as payload the (encrypted) commitment randomness `s` used to compute `H(sA||s)`.
- calls [Split()](http://www.noiseprotocol.org/noise.html#the-symmetricstate-object) and obtains two cipher states to encrypt inbound and outbound messages.
7. The device `B`:
- listens to messages sent to `contentTopic` and locally filters only those with Waku payload starting with `messageNametag`. If any, continues.
- obtains from decrypting the received message a public key `sA`. If `sA` is not a valid public key, the protocol is aborted.
- performs `DH(sA,eB)` (which updates a symmetric encryption key);
- performs `DH(sA,sB)` (which updates a symmetric encryption key);
- decrypts the payload to obtain the randomness `s`.
- Computes `H(sA||s)` and checks if this value corresponds to the commitment obtained in step 3. If not, the protocol is aborted.
- Calls [Split()](http://www.noiseprotocol.org/noise.html#the-symmetricstate-object) and obtains two cipher states to encrypt inbound and outbound messages.
#### The `WakuPairing` for Devices without a Camera
In the above pairing handshake, the QR is by default exposed by device `B` and not by `A`
because in most use-cases we foresee, the secure transfer phase would consist in
exchanging a single message (e.g., Noise sessions, cryptographic keys, signatures, etc.) from device `A` to `B`.
However, since the user(s) confirm(s) at the end of message `b.` that the authorization code is the same on both devices,
the role of the handhsake initiator and responder can be safely swapped in message `a.` and `b.`.
Indeed, if the pairing phase successfully completes on both devices,
the authentication code, the committed static keys and the Noise processing rules will ensure that no Man-in-the-Middle attack took place
and that messages can be securely exchanged bi-directionally in the transfer phase.
This allows pairing in case device `A` does not have a camera to scan a QR (e.g. a desktop client) while device `B` has.
The resulting handshake would then be:
```
WakuPairing2:
a. -> eA {H(sB||r), contentTopicParams, messageNametag}
...
b. <- eB, eAeB {H(sB||r)} [authcode]
c. <- sB, eAsB {r}
d. -> sA, sAeB, sAsB {s}
{}: payload, []: user interaction
```
## Secure Transfer
The pairing phase is designed to be application-agnostic
and should be flexible enough to mutually authenticate
and allow exchange of cryptographic key material
between two devices over a distributed network of Waku2 nodes.
Once the handshake is concluded,
(privacy-sensitive) information can be exchanged using the encryption keys agreed upon the pairing phase.
If stronger security guarantees are required,
some [additional tweaks](#Implementation-Suggestions) are possible.
## Implementation Suggestions
### Timebox QR exposure
We suggest to timebox the exposure of each pairing QR code to few seconds, e.g. 30.
After this time limit, a QR code containing a new ephemeral key, random static key commitment and message nametag (content topic parameters could remain the same)
should replace the previously exposed QR, which can then be discarded.
The reason for such suggestion is due to the fact that if an attacker is able to compromise one of the ephemeral keys,
he might successfully realize an undetected MitM attack up to the `authcode` confirmation
(we note that compromising ephemeral keys is outside our and Noise security assumptions).
The attacker could indeed proceed as follows:
- intercepts the QR;
- blocks/delays the delivery of the pairing message `b.`;
- compromises `A` or `B` ephemeral key;
- recovers the genuine `authcode` that would have been generated by `A` and `B`;
- generates ~`10^8` random `t` values until the Noise processing of the message `b'. -> eC, eCeB {H(sC||t)} `, where `eC` and `sC` are the attacker ephemeral and static key, respectively, results in computing the same `authcode` as the one between `A` and `B`;
- delivers the message `b'. -> eC, eCeB {H(sC||t)}` to `B` (before `A` is able to deliver its message `b.`).
At this point `A` and `B` will observe the same `authcode` (and would then confirm it),
but `B` will process the attacker's ephemeral key `eC` instead of `eA`.
However, the attacker would not be able to open to device `A` the static key commitment `H(sB||s)` sent by device `B` out-of-band,
and the pairing will abort on `A` side before it reveals its static key.
Device `B`, instead, will successfully complete the pairing with the attacker.
Hence, timeboxing the QR exposure,
also in combination with increasing the number of decimal digits of the `authcode`,
will strongly limit the probability that an attacker can successfully impersonate device `A` to `B`.
We stress once more, that such attack requires the compromise of an ephemeral key (outside our security model)
and that device `A` will in any case detect a mismatch and abort the pairing,
regardless of the fact that the QR timeboxing mitigation is implemented or not.
### Randomized Rekey
The Noise Protocol framework supports [`Rekey()`](http://www.noiseprotocol.org/noise.html#rekey)
in order to update encryption keys *"so that a compromise of cipherstate keys will not decrypt older* \[exchanged\] *messages"*.
However, if a certain cipherstate key is compromised,
it will be possible for the attacker not only to decrypt messages encrypted under that key,
but also all those messages encrypted under any successive new key obtained through a call to `Rekey()`.
This could be mitigated by attaching an ephemeral key to messages sent after a [Split()](http://www.noiseprotocol.org/noise.html#the-symmetricstate-object)
so that a new random symmetric key can be derived,
in a similar fashion to [Double-Ratchet](https://signal.org/docs/specifications/doubleratchet/).
This can be practically achieved by:
- keeping the full Handhshake State even after the handshake is complete (*by Noise specification a call to [`Split()`](http://www.noiseprotocol.org/noise.html#the-symmetricstate-object) should delete the Handshake State*)
- continuing updating the Handshake State by processing every after-handshake exchanged message (i.e. the `payload`) according to the Noise [processing rules](http://www.noiseprotocol.org/noise.html#processing-rules) (i.e. by calling `EncryptAndHash(payload)` and `DecryptAndHash(payload)`);
- adding to each (or every few) message exchanged in the transfer phase a random ephemeral key `e` and perform Diffie-Hellman operations with the other party's ephemeral/static keys in order to update the underlying CipherState and recover new random inbound/outbound encryption keys by calling [`Split()`](http://www.noiseprotocol.org/noise.html#the-symmetricstate-object).
In short, the transfer phase would look like (but not necessarily the same as):
```
TransferPhase:
-> eA, eAeB, eAsB {payload}
<- eB, eAeB, sAeB {payload}
...
{}: payload
```
### Messages Nametag Derivation
To reduce metadata leakages and increase devices's anonymity over the p2p network,
[WAKU2-NOISE](./noise.md/#session-states) suggests to use some common secrets `mntsInbound, mntsOutbound` (e.g. `mntsInbound, mntsOutbound = HKDF(h)`
where `h` is the [handshake hash value](https://noiseprotocol.org/noise.html#overview-of-handshake-state-machine) of the Handshake State at some point of the pairing phase)
in order to frequently and deterministically change the `messageNametag` of messages exchanged during the pairing and transfer phase -
ideally, at each message exchanged.
Given the proposed construction,
the `mntsInbound` and `mntsOutbound` secrets can be used to iteratively generate the `messageNametag` field of Waku payloads
for inbound and outbound messages, respectively.
The derivation of `messageNametag` should be deterministic only for communicating devices
and independent from message content,
otherwise lost messages will prevent computing the next message nametag.
A possible approach consists in computing the `n`-th `messageNametag` as `H( mntsInbound || n)`,
where `n` is serialized as `uint64`.
In this way, sender's and recipient's devices
can keep updated a buffer of `messageNametag` to sieve
while listening to messages sent over `/{application-name}/{application-version}/wakunoise/1/sessions-{shard-id}/` (i.e., the next 50 not yet seen).
They will then be able to further identify if one or more messages were eventually lost
or not-yet-delivered during the communication.
This approach brings also the advantage that
communicating devices can efficiently identify encrypted messages addressed to them.
We note that since the `ChaChaPoly` cipher used to encrypt messages supports *additional data*,
an encrypted payload can be further authenticated by passing the `messageNametag` as additional data to the encryption/decryption routine.
In this way, an attacker would be unable to craft an authenticated Waku message
even in case the currently used symmetric encryption key is compromised,
unless `mntsInbound`, `mntsOutbound` or the `messageNametag` buffer lists were compromised too.
## Security/Privacy Considerations
### Assumptions
- The attacker is active, i.e. can interact with both devices `A` and `B` by sending messages over `contentTopic`.
- The attacker has access to the QR code, that is knows the ephemeral key `eB`, the commitment `H(sB||r)` and the `contentTopic` exposed by the device `B`.
- Devices `A` and `B` are considered trusted (otherwise the attacker will simply exfiltrate the relevant information from the attacked device).
- As common for Noise, we assume that ephemeral keys cannot be compromised, while static keys might be later compromised. However, we enforce in the pairing phase extra security mechanisms (i.e. use of commitments for static keys) that will prevent some attacks possible when ephemeral keys are weak or get compromised.
### Rationale
- The device `B` exposes a commitment to its static key `sB` because:
- it can commit to its static key before the authentication code is confirmed without revealing it.
- If the private key of `eB` is weak or gets compromised, an attacker can impersonate `B` by sending in message `c.` to device `A` his own static key and successfully complete the pairing phase. Note that being able to compromise `eB` is not contemplated by our security assumptions.
- `B` cannot adaptively choose a static key based on the state of the Noise handshake at the end of message `b.`, i.e. after the authentication code is confirmed. Note that device `B` is trusted in our security assumptions.
- Confirming the authentication code after processing message `b.` will ensure that no Man-in-the-Middle (MitM) can later send a static key different than `sB`.
- The device `A` sends a commitment to its static key `sA` because:
- it can commit to its static key before the authentication code is confirmed without revealing it.
- `A` cannot adaptively choose a static key based on the state of the Noise handshake at the end of message `b.`, i.e. after the authentication code is confirmed. Note that device `A` is trusted in our security assumptions.
- Confirming the authentication code after processing message `b.` will ensure that no MitM can later send a static key different than `sA`.
- The authorization code is shown and has to be confirmed at the end of message `b.` because:
- an attacker that frontruns device `A` by sending faster his own ephemeral key would be detected before he's able to know device `B` static key `sB`;
- it ensures that no MitM attacks will happen during *the whole* pairing handshake, since commitments to the (later exchanged) device static keys will be implicitly acknowledged by the authorization code confirmation;
- it enables to safely swap the role of handshake initiator and responder (see above);
- Device `B` sends his static key first because:
- by being the pairing requester, it cannot probe device `A` identity without revealing its own (static key) first. Note that device `B` static key and its commitment can be bound to other cryptographic material (e.g., seed phrase).
- Device `B` opens a commitment to its static key at message `c.` because:
- if device `A` replies concluding the handshake according to the protocol, device `B` acknowledges that device `A` correctly received his static key `sB`, since `r` was encrypted under an encryption key derived from the static key `sB` and the genuine (due to the previous `authcode` verification) ephemeral keys `eA` and `eB`.
- Device `A` opens a commitment to its static key at message `d.` because:
- if device `B` doesn't abort the pairing, device `A` acknowledges that device `B` correctly received his static key `sA`, since `s` was encrypted under an encryption key derived from the static keys `sA` and `sB` and the genuine (due to the previous `authcode` verification) ephemeral keys `eA` and `eB`.
## Application to Noise Sessions
### The N11M session management mechanism
In the [`N11M` session management mechanism](./noise-sessions/noise-sessions.md/#the-n11m-session-management-mechanism),
one of Alice's devices is already communicating with one of Bob's devices within an active Noise session,
e.g. after a successful execution of a Noise handshake.
Alice and Bob would then share some cryptographic key material,
used to encrypt their communications.
According to [WAKU2-NOISE-SESSIONS](./noise-sessions/noise-sessions.md) this information consists of:
- A `session-id` (32 bytes)
- Two cipher state `CSOutbound`, `CSInbound`, where each of them contains:
- an encryption key `k` (2x32bytes)
- a nonce `n` (2x8bytes)
- (optionally) an internal state hash `h` (2x32bytes)
for a total of **176 bytes** of information.
In a [`N11M`](./noise-sessions/noise-sessions.md/#the-n11m-session-management-mechanism) session mechanism scenario,
all (synced) Alice's devices that are communicating with Bob
share the same Noise session cryptographic material.
Hence, if Alice wishes to add a new device,
she must securely transfer a copy of such data from one of her device `A` to a new device `B` in her possession.
In order to do so she can:
- pair device `A` with `B` in order to have a Noise session between them;
- securely transfer within such session the 176 bytes serializing the active session with Bob;
- manually instantiate in `B` a Noise session with Bob from the received session serialization.
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
### Normative
- [35/WAKU2-NOISE](./noise.md/#session-states)
- [WAKU2-NOISE-SESSIONS](./noise-sessions/noise-sessions.md/)
### Informative
- [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/35/#abnf)
- [The Double-Ratchet Algorithm](https://signal.org/docs/specifications/doubleratchet/)
- [The Noise Protocol Framework specifications](http://www.noiseprotocol.org/noise.html)
- [IETF RFC 4648 - The Base16, Base32, and Base64 Data Encodings](https://datatracker.ietf.org/doc/html/rfc4648)

155
standards/application/noise-sessions.md Normal file
View File

@ -0,0 +1,155 @@
---
title: WAKU2-NOISE-SESSIONS
name: Session Management for Waku Noise
tags: waku-core-protocol
editor: Giuseppe <giuseppe@status.im>
contributors:
---
## Introduction
In [WAKU2-NOISE](../noise.md) we defined how Waku messages' payloads can be encrypted using key material derived from key agreements based on the [Noise Protocol Framework](http://www.noiseprotocol.org/noise.html).
Once two users complete a Noise handshake,
an encryption/decryption session - _or a Noise session_ - would be instantiated.
This post provides an overview on how we can possibly implement and manage one or multiple Noise sessions in Waku.
## Preliminaries
We assume that two users, e.g. Alice and Bob, successfully completed a Noise handshake.
Using [Noise terminology]((http://www.noiseprotocol.org/noise.html)), at the end of the handshake they will share:
- two _Cipher States_ `CSOutbound` and `CSInbound`, to encrypt and decrypt outbound and inbound messages, respectively;
- a handshake hash value `h`.
As suggested in Noise specifications in regards to [Channel Binding](http://www.noiseprotocol.org/noise.html#channel-binding),
we can identify a Noise session with a `session-id` derived from the handshake hash value `h` shared on completion of a Noise handshake.
More specifically, when Alice and Bob call [Split()](http://www.noiseprotocol.org/noise.html#the-symmetricstate-object) in order to derive the two final encryption and decryption Cipher States,
they further compute `session-id = HKDF(h)` using the supported key derivation function `HKDF`.
Such `session-id` will uniquely identify the Noise cryptographic session instantiated on completion of a Noise handshake,
which would then consist of the tuple `(session-id, CSOutbound, CSInbound)`.
For each instantiated Noise session we assume this tuple to be properly persisted,
since it is required to either retrieve and encrypt/decrypt any further exchanged message.
Once a Noise session is instantiated,
any further encrypted message between Alice and Bob within this session is exchanged on a `contentTopic` with name `/{application-name}/{application-version}/wakunoise/1/sessions/{ct-id}/proto`,
where `ct-id = Hash(Hash(session-id))`
and `/{application-name}/{application-version}/` identifies the application currently employing [WAKU2-NOISE](../noise.md).
## Session states
A Noise session corresponding to a certain `session-id`:
- is always **active** as long as it is not marked as **stale**.
For an active `session-id`, new messages are published on the content topic `/{application-name}/{application-version}/wakunoise/1/sessions/{ct-id}/proto`;
- is marked as **stale** if a [session termination message](../noise.md/#session-termination-message) containing `Hash(session-id)` is published on the content topic `/{application-name}/{application-version}/wakunoise/1/sessions/{ct-id}/proto`.
Session information relative to stale sessions MAY be deleted from users' device, unless required for later channel binding purposes.
When a Noise session is marked as stale, it means that one party requested its termination while being online,
since publication of a hash pre-image for `ct-id` is required (i.e. `Hash(session-id)`).
Currently, it is not possible to mark a Noise session as stale when `session-id` is lost or gets corrupted in users' devices.
However, since `session-id` is shared between Alice and Bob,
one party MAY decide to mark a Noise session as stale if no message from the other end was received within a certain fixed time window.
The above mechanism allows a Noise session to be marked as stale either privately or publicly,
depending if `Hash(session-id)` is sent on `/{application-name}/{application-version}/wakunoise/1/sessions/{ct-id}/proto` to the other party in encrypted form or not, respectively.
When a Noise session is publicly marked as stale,
network peers MAY discard all [stored](https://rfc.vac.dev/spec/13/) messages addressed to the content topic `/{application-name}/{application-version}/wakunoise/1/sessions/{ct-id}/proto`.
In this the case and in order for parties to retrieve any eventually delayed message,
peers SHOULD wait a fixed amount of time before discarding stored messages corresponding to a stale Noise session.
A stale Noise session cannot be directly marked as active
and parties are required to instantiate a new Noise session if they wish to communicate again.
However, parties can optionally persist and include the `session-id` corresponding to a stale Noise session in the [prologue information](https://noiseprotocol.org/noise.html#prologue) employed in the Noise handshake they execute to instantiate their new Noise session.
This effectively emulates a mechanism to _"re-activate"_ a stale Noise session by binding it to a newly created active Noise session.
In order to reduce users' metadata leakage, it is desirable (as suggested in [WAKU2-NOISE](../noise.md/#after-handshake)) that content topics used for communications change every time a new message is exchanged.
This can be easily realized by employing a key derivation function to compute a new `session-id` from the previously employed one (e.g. `session-id = HKDF(prev-session-id)`),
while keeping the Inbound/outbound Cipher States, the content topic derivation mechanism and the stale mechanism the same as above.
In this case, when one party sends **and** receives at least one message,
he SHALL publicly mark as stale all Noise sessions relative to messages exchanged before the earlier of these two send/receive events.
## Multi-Device support
Alice and Bob might possess one or more devices (e.g. laptops, smartphones, etc.) they wish to use to communicate.
In the following, we assume Alice and Bob to possess $N$ and $M$ devices, respectively.
Since a Noise session contains cryptographic material required to encrypt and decrypt messages exchanged on a pre-defined content topic derived from a `session-id`,
messages should be encrypted and decrypted within the Noise session instantiated between the currently-in-use sender's and receiver's device.
This is achieved through two main supported session management mechanisms that we called `N11M` and `NM`, respectively.
### The $N11M$ session management mechanism
In a $N11M$ setting, each party's device shares the same Noise session information used to encrypt and decrypt messages exchanged with the other party.
![](../../images/N11M.png)
More precisely, once the first Noise session between any of Alice's and Bob's device is instantiated,
its session information is securely propagated to all other devices,
which then become able to send and receive new messages on the content topic associated to such session.
We note, however, that two devices belonging to one party cannot simultaneously send different messages to the other, since only the first message received will be correctly decrypted using the next nonce.
The most updated session information between Alice and Bob is propagated in encrypted form to other devices,
using previously instantiated Noise sessions.
In particular, all Alice's (resp., Bob's) devices that want to receive such updated session information, are required to have an already instantiated Noise session between them in order to receive it in encrypted form.
The propagated session information corresponds to the latest session information stored on the device currently communicating with (any of the devices of) the other party.
We note that sessions information is propagated only among devices belonging to the same party and not with other party's devices.
Hence, Alice has no knowledge on the number of devices Bob is using and vice versa.
When any device marks a Noise session between Alice and Bob as stale,
all other (updated) devices will consider such session as stale
without publishing the `Hash(session-id)` on the corresponding session content topic.
In case a Noise session between two devices belonging to the same party is marked as stale,
such two devices stop to reciprocally propagate any information regarding Noise sessions instantiated with other parties.
As regards security, an attacker that compromises an encrypted message propagating session information,
might be able to compromise one or multiple messages exchanged within the session such information refers to.
This can be mitigated by adopting techniques similar to the the ones proposed in [WAKU2-NOISE](../noise.md/#after-handshake),
where encryption keys are changed every time a new message is exchanged.
This session management mechanism is loosely based on the paper ["Multi-Device for Signal"](https://eprint.iacr.org/2019/1363.pdf).
## The $NM$ session management mechanism
In a $NM$ setting, we require all of $N$ Alice's devices to have an active Noise session with each of Bob's $M$ devices,
for a total of $NM$ concurrently active Noise sessions between Alice and Bob.
![](../../images/NM.png)
A message is sent from the currently-in-use sender's device to all recipent's devices,
by properly encrypting and sending it to the content topics of each corresponding active Noise session.
We note that this allows the recipient to receive a message on all his devices simultaneously.
However, on the sender side, only the device which effectively sent the message will know its full content.
If it is required for sent messages to be available on all sender's devices,
each pair of sender's devices SHOULD have an active Noise session used for syncing purposes:
this sums up to a total of $N-1$ and $M-1$ extra Noise sessions instantiated on each Alice's and Bob's device, respectively.
Thus, if Alice wants to send a message to Bob from one of her $N$ devices,
she encrypts and sends her message to each of Bob's $M$ devices
(and, eventually, to each of her other $N-1$ devices),
using the appropriate Noise session information.
If one device marks a Noise session as stale,
all active sessions instantiated with such device SHOULD be marked as stale as soon as possible.
If the device declaring a stale session does not send a session termination message to all the other party's devices with which has an active session,
the other party SHOULD send a termination message to mark all such Noise sessions as stale.
This session management mechanism is loosely based on [Signal's Sesame Algorithm](https://signal.org/docs/specifications/sesame/).
# References
- [13/WAKU2-STORE](https://rfc.vac.dev/spec/13/)
- [WAKU2-NOISE](../noise.md)
- [The Noise Protocol Framework](http://www.noiseprotocol.org/noise.html)
- [The Sesame Algorithm: Session Management for Asynchronous Message Encryption](https://signal.org/docs/specifications/sesame/)
- ["Multi-Device for Signal"](https://eprint.iacr.org/2019/1363.pdf)

345
standards/application/noise.md Normal file
View File

@ -0,0 +1,345 @@
---
title: WAKU2-NOISE
name: Noise Protocols for Waku Payload Encryption
tags: waku-core-protocol
editor: Giuseppe <giuseppe@status.im>
contributors:
---
This specification describes how payloads of [Waku messages](https://rfc.vac.dev/spec/14/) with [version 2](https://rfc.vac.dev/spec/14/#version2) can be encrypted
in order to achieve confidentiality, authenticity, and integrity
as well as some form of identity-hiding on communicating parties.
This specification extends the functionalities provided by [26/WAKU-PAYLOAD](https://rfc.vac.dev/spec/26/),
adding support to modern symmetric encryption primitives
and asymmetric key-exchange protocols.
Specifically, it adds support to the [`ChaChaPoly`](https://www.ietf.org/rfc/rfc7539.txt) cipher for symmetric authenticated encryption.
It further describes how the [Noise Protocol Framework](http://www.noiseprotocol.org/noise.html) can be used to exchange cryptographic keys and encrypt/decrypt messages
in a way that the latter are authenticated and protected by *strong forward secrecy*.
This ultimately allows Waku applications to instantiate end-to-end encrypted communication channels with strong conversational security guarantees,
as similarly done by [5/SECURE-TRANSPORT](https://specs.status.im/spec/5) but in a more modular way,
adapting key-exchange protocols to the knowledge communicating parties have of each other.
## Design requirements
- *Confidentiality*: the adversary should not be able to learn what data is being sent from one Waku endpoint to one or several other Waku endpoints.
- *Strong forward secrecy*: an active adversary cannot decrypt messages nor infer any information on the employed encryption key,
even in the case he has access to communicating parties' long-term private keys (during or after their communication).
- *Authenticity*: the adversary should not be able to cause a Waku endpoint to accept messages coming from an endpoint different than their original senders.
- *Integrity*: the adversary should not be able to cause a Waku endpoint to accept data that has been tampered with.
- *Identity-hiding*: once a secure communication channel is established,
a passive adversary should not be able to link exchanged encrypted messages to their corresponding sender and recipient.
## Supported Cryptographic Protocols
### Noise Protocols
Two parties executing a Noise protocol exchange one or more [*handshake messages*](http://www.noiseprotocol.org/noise.html#message-format) and/or [*transport messages*](http://www.noiseprotocol.org/noise.html#message-format).
A Noise protocol consists of one or more Noise handshakes.
During a Noise handshake, two parties exchange multiple handshake messages.
A handshake message contains *ephemeral keys* and/or *static keys* from one of the parties
and an encrypted or unencrypted payload that can be used to transmit optional data.
These public keys are used to perform a protocol-dependent sequence of Diffie-Hellman operations,
whose results are all hashed into a shared secret key.
After a handshake is complete, each party will then use the derived shared secret key to send and receive authenticated encrypted transport messages.
We refer to [Noise protocol framework specifications](http://www.noiseprotocol.org/noise.html#processing-rules) for the full details on how parties shared secret key is derived from each exchanged message.
Four Noise handshakes are currently supported: `K1K1`, `XK1`, `XX`, `XXpsk0`. Their description can be found in [Appendix: Supported Handshakes Description](#Appendix-Supported-Handshake-Description).
These are instantiated combining the following cryptographic primitives:
- [`Curve25519`](http://www.noiseprotocol.org/noise.html#the-25519-dh-functions) for Diffie-Hellman key-exchanges (32 bytes curve coordinates);
- [`ChaChaPoly`](http://www.noiseprotocol.org/noise.html#the-chachapoly-cipher-functions) for symmetric authenticated encryption (16 bytes authentication tag);
- [`SHA256`](http://www.noiseprotocol.org/noise.html#the-sha256-hash-function) hash function used in [`HMAC`](http://www.noiseprotocol.org/noise.html#hash-functions) and [`HKDF`](http://www.noiseprotocol.org/noise.html#hash-functions) keys derivation chains (32 bytes output size);
#### Content Topics and Message Nametags of Noise Handshake Messages
We note that all [design requirements](#Design-requirements) on exchanged messages would be satisfied only *after* a supported Noise handshake is completed,
corresponding to a total of 1 Round Trip Time communication *(1-RTT)*.
In particular, identity-hiding properties can be guaranteed only if the recommendation described in [After-handshake](#After-handshake) are implemented.
In the following, we assume that communicating parties reciprocally know an initial [`contentTopic`](https://rfc.vac.dev/spec/14/#wakumessage)
where they can send/receive the first handshake message(s).
We further assume that messages sent over a certain `contentTopic` can be efficiently identified by their intended recipients
thanks to an arbitrary 16 bytes long `message-nametag` field embedded in the message payload
which is known in advance before messages reception.
The second handshake message MAY be sent/received with a `message-nametag` deterministically derived from the handshake state obtained after processing the first handshake message
(using, for example, `HKDF` over the handshake hash value `h`).
This allows
- the recipient to efficiently continue the handshakes started by each initiator;
- the initiators to efficiently associate the recipient's second handshake message to their first handshake message,
However, this does not provide any identity-hiding guarantee to the recipient.
After the second handshake message is correctly received by initiators, the recommendation described in [After-handshake](#After-handshake) SHOULD be implemented to provide full identity-hiding guarantees for both initiator and recipient against passive attackers.
### Encryption Primitives
The symmetric primitives supported are:
- [`ChaChaPoly`](https://www.ietf.org/rfc/rfc7539.txt) for authenticated encryption (16 bytes authentication tag).
## Specification
When [14/WAKU-MESSAGE version](https://rfc.vac.dev/spec/14/#payload-encryption) is set to 2,
the corresponding `WakuMessage`'s `payload` will encapsulate the two fields `handshake-message` and `transport-message`.
The `handshake-message` field MAY contain
- a Noise handhshake message (only encrypted/unencrypted public keys).
The `transport-message` field MAY contain
- a Noise handshake message payload (encrypted/unencrypted);
- a Noise transport message;
- a `ChaChaPoly` ciphertext.
When a `transport-message` encodes a `ChaChaPoly` ciphertext, the corresponding `handshake-message` field MUST be empty.
The following fields are concatenated to form the `payload` field:
- `message-nametag`: an arbitrary identifier for the Waku message (16 byte).
If the underlying encryption primitive supports it, the contents of this field SHOULD be passed as additional data to the encryption and decryption routines.
- `protocol-id`: identifies the protocol or primitive in use (1 byte).
Supported values are:
- `0`: protocol specification omitted (set for [after-handshake](#After-handshake) messages);
- `10`: Noise protocol `Noise_K1K1_25519_ChaChaPoly_SHA256`;
- `11`: Noise protocol `Noise_XK1_25519_ChaChaPoly_SHA256`;
- `12`: Noise protocol `Noise_XX_25519_ChaChaPoly_SHA256`;
- `13`: Noise protocol `Noise_XXpsk0_25519_ChaChaPoly_SHA256`;
- `30`: `ChaChaPoly` symmetric encryption.
- `handshake-message-len`: the length in bytes of the Noise handshake message (1 byte).
If `protocol-id` is not equal to `0`, `10`, `11`, `12`, `13`, this field MUST be set to `0`;
- `handshake-message`: the Noise handshake message (`handshake-message-len` bytes).
If `handshake-message-len` is not `0`,
it contains the concatenation of one or more Noise Diffie-Hellman ephemeral or static keys
encoded as in [Public Keys Encoding](#Public-Keys-Encoding);
- `transport-message-len`: the length in bytes of `transport-message` (8 bytes, stored in Little-Endian);
- `transport-message`: the transport message (`transport-message-len` bytes);
Only during a Noise handshake, this field would contain the Noise handshake message payload.
The symmetric encryption authentication data for `transport-message`, when present, is appended at the end of `transport-message` (16 bytes).
### ABNF
Using [Augmented Backus-Naur form (ABNF)](https://tools.ietf.org/html/rfc5234) we have the following format:
```abnf
; message nametag
message-nametag = 16OCTET
; protocol ID
protocol-id = 1OCTET
; contains the size of handshake-message
handshake-message-len = 1OCTET
; contains one or more Diffie-Hellman public keys
handshake-message = *OCTET
; contains the size of transport-message
transport-message-len = *OCTET
; contains the transport message, eventually encrypted.
; If encrypted, authentication data is appended
transport-message = *OCTET
; the Waku WakuMessage payload field
payload = message-nametag protocol-id handshake-message-len handshake-message transport-message-len transport-message
```
### Protocol Payload Format
Based on the specified `protocol-id`,
the Waku message `payload` field will encode different types of protocol-dependent messages.
In particular, if `protocol-id` is
- `0`: payload encodes an [after-handshake](#After-handshake) message.
- `handshake-message-len` MAY be 0;
- `transport-message` contains the Noise transport message;
- `10`,`11`,`12`,`13`: payload encodes a supported Noise handshake message.
- `transport-message` contains the Noise transport message;
- `30`: payload encapsulate a `ChaChaPoly` ciphertext `ct`.
- `handshake-message-len` is set to `0`;
- `transport-message` contains the concatenation of the encryption nonce (12 bytes) followed by the ciphertext `ct` and the authentication data for `ct` (16 bytes);
- `transport-message-len` is set accordingly to `transport-message` length;
### Public Keys Serialization
Diffie-Hellman public keys can be trasmitted in clear
or in encrypted form (cf. [`WriteMessage`](http://www.noiseprotocol.org/noise.html#the-handshakestate-object)) with authentication data attached.
To distinguish between these two cases, public keys are serialized as the concatenation of the following three fields:
- `flag`:
is equal to `1` if the public key is encrypted;
`0` otherwise (1 byte);
- `pk`:
if `flag = 0`, it contains an encoding of the X coordinate of the public key.
If `flag = 1`, it contains a symmetric encryption of an encoding of the X coordinate of the public key, followed by encryption's authentication data;
The corresponding serialization is obtained as `flag pk`.
As regards the underlying supported [cryptographic primitives](#Cryptographic-primitives):
- `Curve25519` public keys X coordinates are encoded in little-endian as 32 bytes arrays;
- `ChaChaPoly` authentication data consists of 16 bytes
(nonces are implicitely defined by Noise [processing rules](http://www.noiseprotocol.org/noise.html#processing-rules)).
In all supported Noise protocols,
parties' static public keys are transmitted encrypted (cf. [`EncryptAndHash`](http://www.noiseprotocol.org/noise.html#the-symmetricstate-object)),
while ephemeral keys MAY be encrypted after a handshake is complete.
### Padding
To prevent some metadata leakage,
encrypted transport messages SHOULD be padded before encryption.
It is therefore recommended to right pad transport messages using [RFC2630](https://datatracker.ietf.org/doc/html/rfc2630#section-6.3) so that their final length is a multiple of 248 bytes.
## After-handshake
During the initial 1-RTT communication,
handshake messages [might be linked](#Content-Topics-and-Message-Nametags-of-Noise-Handshake-Messages),
depending on the `message-nametag` derivation rule implemented,
to the respective parties through the `contentTopic` and `message-nametag` fields employed for such communication.
After a handshake is completed,
parties MAY derive from their shared secret key (preferably using `HKDF`)
two random `nametag-secret-outbound` and `nametag-secret-inbound` values used to deterministically derive
two arbitrary-long ordered lists of `message-nametag`
used to indentify outbound and inbound messages, respectively
(e.g. the `n`-th inbound `message-nametag` MAY be computed as `HKDF(nametag-secret-inbound || n)`).
This allows communicating parties to efficiently identify messages addressed to them sent over a certain `contentTopic`
and thus minimize the number of trial decryptions.
When communicating,
parties SHOULD set `protocol-id` to `0`
to reduce metadata leakages and indicate that the message is an *after-handshake* message.
Each party SHOULD attach an (unencrypted) ephemeral key in `handshake-message` to every message sent.
According to [Noise processing rules](http://www.noiseprotocol.org/noise.html#processing-rules),
this allows updates to the shared secret key
by hashing the result of an ephemeral-ephemeral Diffie-Hellman exchange every 1-RTT communication.
## Backward Support for Symmetric/Asymmetric Encryption
It is possible to have backward compatibility to symmetric/asymmetric encryption primitives from [26/WAKU-PAYLOAD](https://rfc.vac.dev/spec/26/),
effectively encapsulating payload encryption [14/WAKU-MESSAGE version 1](https://rfc.vac.dev/spec/14/#version1) in [version 2](https://rfc.vac.dev/spec/14/#version2).
It suffices to extend the list of supported `protocol-id` to:
- `254`: AES-256-GCM symmetric encryption;
- `255`: ECIES asymmetric encryption.
and set the `transport-message` field to the [26/WAKU-PAYLOAD](https://rfc.vac.dev/spec/26) `data` field, whenever these `protocol-id` values are set.
Namely, if `protocol-id = 254, 255` then:
- `message-nametag`: is empty;
- `handshake-message-len`: is set to `0`;
- `handshake-message`: is empty;
- `transport-message`: contains the [26/WAKU-PAYLOAD](https://rfc.vac.dev/spec/26/) `data` field (AES-256-GCM or ECIES, depending on `protocol-id`);
- `transport-message-len` is set accordingly to `transport-message` length;
When a `transport-message` corresponding to `protocol-id = 254, 255` is retrieved,
it SHOULD be decoded as the `data` field in [26/WAKU-PAYLOAD](https://rfc.vac.dev/spec/26/) specification.
## Appendix: Supported Handshakes Description
Supported Noise handshakes address four typical scenarios occurring when an encrypted communication channel between Alice and Bob is going to be created:
- Alice and Bob know each others' static key.
- Alice knows Bob's static key;
- Alice and Bob share no key material and they don't know each others' static key.
- Alice and Bob share some key material, but they don't know each others' static key.
**Adversarial Model**: an active attacker who compromised one party's static key may lower the identity-hiding security guarantees provided by some handshakes. In our security model we exclude such adversary, but for completeness we report a summary of possible de-anonymization attacks that can be performed by an active attacker.
### The `K1K1` Handshake
If Alice and Bob know each others' static key (e.g., these are public or were already exchanged in a previous handshake) , they MAY execute a `K1K1` handshake. Using [Noise notation](https://noiseprotocol.org/noise.html#overview-of-handshake-state-machine) *(Alice is on the left)* this can be sketched as:
```
K1K1:
-> s
<- s
...
-> e
<- e, ee, es
-> se
```
We note that here only ephemeral keys are exchanged. This handshake is useful in case Alice needs to instantiate a new separate encrypted communication channel with Bob, e.g. opening multiple parallel connections, file transfers, etc.
**Security considerations on identity-hiding (active attacker)**: no static key is transmitted, but an active attacker impersonating Alice can check candidates for Bob's static key.
### The `XK1` Handshake
Here, Alice knows how to initiate a communication with Bob and she knows his public static key: such discovery can be achieved, for example, through a publicly accessible register of users' static keys, smart contracts, or through a previous public/private advertisement of Bob's static key.
A Noise handshake pattern that suits this scenario is `XK1`:
```
XK1:
<- s
...
-> e
<- e, ee, es
-> s, se
```
Within this handshake, Alice and Bob reciprocally authenticate their static keys `s` using ephemeral keys `e`. We note that while Bob's static key is assumed to be known to Alice (and hence is not transmitted), Alice's static key is sent to Bob encrypted with a key derived from both parties ephemeral keys and Bob's static key.
**Security considerations on identity-hiding (active attacker)**: Alice's static key is encrypted with forward secrecy to an authenticated party. An active attacker initiating the handshake can check candidates for Bob's static key against recorded/accepted exchanged handshake messages.
### The `XX` and `XXpsk0` Handshakes
If Alice is not aware of any static key belonging to Bob (and neither Bob knows anything about Alice), she can execute an `XX` handshake, where each party tran**X**mits to the other its own static key.
The handshake goes as follows:
```
XX:
-> e
<- e, ee, s, es
-> s, se
```
We note that the main difference with `XK1` is that in second step Bob sends to Alice his own static key encrypted with a key obtained from an ephemeral-ephemeral Diffie-Hellman exchange.
This handshake can be slightly changed in case both Alice and Bob pre-shares some secret `psk` which can be used to strengthen their mutual authentication during the handshake execution. One of the resulting protocol, called `XXpsk0`, goes as follow:
```
XXpsk0:
-> psk, e
<- e, ee, s, es
-> s, se
```
The main difference with `XX` is that Alice's and Bob's static keys, when transmitted, would be encrypted with a key derived from `psk` as well.
**Security considerations on identity-hiding (active attacker)**: Alice's static key is encrypted with forward secrecy to an authenticated party for both `XX` and `XXpsk0` handshakes. In `XX`, Bob's static key is encrypted with forward secrecy but is transmitted to a non-authenticated user which can then be an active attacker. In `XXpsk0`, instead, Bob's secret key is protected by forward secrecy to a partially authenticated party (through the pre-shared secret `psk` but not through any static key), provided that `psk` was not previously compromised (in such case identity-hiding properties provided by the `XX` handshake applies).
## References
1. [5/SECURE-TRANSPORT](https://specs.status.im/spec/5)
2. [10/WAKU2](https://rfc.vac.dev/spec/10)
3. [26/WAKU-PAYLOAD](https://rfc.vac.dev/spec/26)
4. [14/WAKU-MESSAGE](https://rfc.vac.dev/spec/14/#version1)
5. [Noise protocol](http://www.noiseprotocol.org/noise.html)
6. [Noise handshakes as key-exchange mechanism for Waku2](https://forum.vac.dev/t/noise-handshakes-as-key-exchange-mechanism-for-waku2/130)
7. [Augmented Backus-Naur form (ABNF)](https://tools.ietf.org/html/rfc5234)
8. [RFC2630 - Content-encryption Process and padding](https://datatracker.ietf.org/doc/html/rfc2630#section-6.3)
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

43
standards/application/tor-push.md Normal file
View File

@ -0,0 +1,43 @@
---
title: TOR-PUSH
name: Waku v2 Tor Push
category: Best Current Practice
tags: waku/application
editor: Daniel Kaiser <danielkaiser@status.im>
contributors:
---
## Abstract
This document extends the [11/WAKU2-RELAY](https://rfc.vac.dev/spec/11), specifying Waku Tor Push,
which allows nodes to push messages via Tor into the Waku relay network.
Waku Tor Push builds on [46/GOSSIPSUB-TOR-PUSH](https://rfc.vac.dev/spec/46).
**Protocol identifier**: /vac/waku/relay/2.0.0
Note: Waku Tor Push does not have a dedicated protocol identifier.
It uses the same identifier as Waku relay.
This allows Waku relay nodes that are oblivious to Tor Push to process messages received via Tor Push.
## Functional Operation
In its current version, Waku Tor Push corresponds to [46/GOSSIPSUB-TOR-PUSH](https://rfc.vac.dev/spec/46)
applied to [11/WAKU2-RELAY](https://rfc.vac.dev/spec/11/),
instead of [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md).
## Security/Privacy Considerations
see [46/GOSSIPSUB-TOR-PUSH](https://rfc.vac.dev/spec/46)
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
* [11/WAKU2-RELAY](https://rfc.vac.dev/spec/11)
* [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md)
* [46/GOSSIPSUB-TOR-PUSH](https://rfc.vac.dev/spec/46)
* [Tor](https://www.torproject.org/)

163
standards/core/enr.md Normal file
View File

@ -0,0 +1,163 @@
---
title: WAKU2-ENR
name: Waku v2 usage of ENR
tags: waku/core-protocol
editor: Franck Royer <franck@status.im>
contributors:
---
## Abstract
This RFC describes the usage of the ENR (Ethereum Node Records) format for [10/WAKU2](https://rfc.vac.dev/spec/10/) purposes.
The ENR format is defined in [EIP-778](https://eips.ethereum.org/EIPS/eip-778) [[3]](#references).
This RFC is an extension of EIP-778, ENR used in Waku v2 MUST adhere to both EIP-778 and 31/WAKU2-ENR.
## Motivation
EIP-1459 with the usage of ENR has been implemented [[1]](#references) [[2]](#references) as a discovery protocol for Waku v2.
EIP-778 specifies a number of pre-defined keys.
However, the usage of these keys alone does not allow for certain transport capabilities to be encoded,
such as Websocket.
Currently, Waku v2 nodes running in a Browser only support websocket transport protocol.
Hence, new ENR keys need to be defined to allow for the encoding of transport protocol other than raw TCP.
### Usage of Multiaddr Format Rationale
One solution would be to define new keys such as `ws` to encode the websocket port of a node.
However, we expect new transport protocols to be added overtime such as quic.
Hence, this would only provide a short term solution until another RFC would need to be added.
Moreover, secure websocket involves SSL certificates.
SSL certificates are only valid for a given domain and ip, so an ENR containing the following information:
- secure websocket port
- ipv4 fqdn
- ipv4 address
- ipv6 address
Would carry some ambiguity: Is the certificate securing the websocket port valid for the ipv4 fqdn?
the ipv4 address?
the ipv6 address?
The [10/WAKU2](https://rfc.vac.dev/spec/10/) protocol family is built on the [libp2p](https://github.com/libp2p/specs) protocol stack.
Hence, it uses [multiaddr](https://github.com/multiformats/multiaddr) to format network addresses.
Directly storing one or several multiaddresses in the ENR would fix the issues listed above:
- multiaddr is self-describing and support addresses for any network protocol:
No new RFC would be needed to support encoding other transport protocols in an ENR.
- multiaddr contains both the host and port information, allowing the ambiguity previously described to be resolved.
## `multiaddrs` ENR key
We define a `multiaddrs` key.
- The value MUST be a list of binary encoded multiaddr prefixed by their size.
- The size of the multiaddr MUST be encoded in a Big Endian unsigned 16-bit integer.
- The size of the multiaddr MUST be encoded in 2 bytes.
- The `secp256k1` value MUST be present on the record;
`secp256k1` is defined in [EIP-778](https://eips.ethereum.org/EIPS/eip-778) and contains the compressed secp256k1 public key.
- The node's peer id SHOULD be deduced from the `secp256k1` value.
- The multiaddresses SHOULD NOT contain a peer id except for circuit relay addresses
- For raw TCP & UDP connections details, [EIP-778](https://eips.ethereum.org/EIPS/eip-778) pre-defined keys SHOULD be used;
The keys `tcp`, `udp`, `ip` (and `tcp6`, `udp6`, `ip6` for IPv6) are enough to convey all necessary information;
- To save space, `multiaddrs` key SHOULD only be used for connection details that cannot be represented using the [EIP-778](https://eips.ethereum.org/EIPS/eip-778) pre-defined keys.
- The 300 bytes size limit as defined by [EIP-778](https://eips.ethereum.org/EIPS/eip-778) still applies;
In practice, it is possible to encode 3 multiaddresses in ENR, more or less could be encoded depending on the size of each multiaddress.
### Usage
#### Many connection types
Alice is a node operator, she runs a node that supports inbound connection for the following protocols:
- TCP 10101 on `1.2.3.4`
- UDP 20202 on `1.2.3.4`
- TCP 30303 on `1234:5600:101:1::142`
- UDP 40404 on `1234:5600:101:1::142`
- Secure Websocket on `wss://example.com:443/`
- QUIC on `quic://quic.example.com:443/`
- A circuit relay address `/ip4/1.2.3.4/tcp/55555/p2p/QmRelay/p2p-circuit/p2p/QmAlice`
Alice SHOULD structure the ENR for her node as follows:
| key | value |
|--- |--- |
| `tcp` | `10101` |
| `udp` | `20202` |
| `tcp6` | `30303` |
| `udp6` | `40404` |
| `ip` | `1.2.3.4` |
| `ip6` | `1234:5600:101:1::142` |
| `secp256k1` | Alice's compressed secp256k1 public key, 33 bytes |
| `multiaddrs` | <code>len1 &#124; /dns4/example.com/tcp/443/wss &#124; len2 &#124; /dns4/quic.examle.com/tcp/443/quic &#124; len3 &#124; /ip4/1.2.3.4/tcp/55555/p2p/QmRelay </code> |
Where:
- `|` is the concatenation operator,
- `len1` is the length of `/dns4/example.com/tcp/443/wss` byte representation,
- `len2` is the length of `/dns4/quic.examle.com/tcp/443/quic` byte representation.
- `len3` is the length of `/ip4/1.2.3.4/tcp/55555/p2p/QmRelay` byte representation. Notice that the `/p2p-circuit` component is not stored, but, since circuit relay addresses are the only one containing a `p2p` component, it's safe to assume that any address containing this component is a circuit relay address. Decoding this type of multiaddresses would require appending the `/p2p-circuit` component.
#### Raw TCP only
Bob is a node operator, he runs a node that supports inbound connection for the following protocols:
- TCP 10101 on `1.2.3.4`
Bob SHOULD structure the ENR for her node as follows:
| key | value |
|--- |--- |
| `tcp` | `10101` |
| `ip` | `1.2.3.4` |
| `secp256k1` | Bob's compressed secp256k1 public key, 33 bytes |
Indeed, as Bob's node's connection details can be represented with EIP-778's pre-defined keys only
then it is not needed to use the `multiaddrs` key.
### Limitations
Supported key type is `secp256k1` only.
In the future, an extension of this RFC could be made to support other elliptic curve cryptography such as `ed25519`.
## `waku2` ENR key
We define a `waku2` field key:
- The value MUST be an 8-bit flag field,
where bits set to `1` indicate `true` and bits set to `0` indicate `false` for the relevant flags.
- The flag values already defined are set out below,
with `bit 7` the most significant bit and `bit 0` the least significant bit.
| bit 7 | bit 6 | bit 5 | bit 4 | bit 3 | bit 2 | bit 1 | bit 0 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `undef` | `undef` | `undef` | `undef` | `lightpush` | `filter` | `store` | `relay` |
- In the scheme above, the flags `lightpush`, `filter`, `store` and `relay` correlates with support for protocols with the same name.
If a protocol is not supported, the corresponding field MUST be set to `false`.
Indicating positive support for any specific protocol is OPTIONAL,
though it MAY be required by the relevant application or discovery process.
- Flags marked as `undef` is not yet defined.
These SHOULD be set to `false` by default.
### Usage
- A Waku v2 node MAY choose to populate the `waku2` field for enhanced discovery capabilities,
such as indicating supported protocols.
Such a node MAY indicate support for any specific protocol by setting the corresponding flag to `true`.
- Waku v2 nodes that want to participate in [Node Discovery Protocol v5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md) [[4]](#references), however,
MUST implement the `waku2` key with at least one flag set to `true`.
- Waku v2 nodes that discovered other participants using Discovery v5,
MUST filter out participant records that do not implement this field or do not have at least one flag set to `true`.
- In addition, such nodes MAY choose to filter participants on specific flags (such as supported protocols),
or further interpret the `waku2` field as required by the application.
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
- [1](https://github.com/status-im/nim-waku/pull/690)
- [2](https://github.com/vacp2p/rfc/issues/462#issuecomment-943869940)
- [3](https://eips.ethereum.org/EIPS/eip-778)
- [4](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md)

218
standards/core/incentivization.md Normal file
View File

@ -0,0 +1,218 @@
---
title: WAKU2-INCENTIVIZATION
name: Incentivization for Waku Light Protocols
category: Standards Track
tags:
- incentivization
editor: Sergei Tikhomirov <sergei@status.im>
contributors:
---
## Abstract
This document describes an approach to incentivization of Waku request-response protocols.
Incentivization is necessary for economically sustainable growth of Waku.
In an incentivized request-response protocol, only eligible (e.g., paying) clients receive the service.
Clients include eligibility proofs in their requests.
Eligibility proofs are designed to be used in multiple Waku protocols, such as Store, Lightpush, and Filter.
Store is planned to become the first Waku protocol to support incentivization.
We discuss the proof-of-concept implementation of incentivization for Store in a later section.
## Background / Rationale / Motivation
Decentralized protocols require incentivization to be economically sustainable.
While some aspects of a P2P network can successfully operate in a tit-for-tat model,
we believe that nodes that run the protocol in good faith need to be tangibly rewarded.
Motivating servers to expand resources on handling clients' requests allows us to scale the network beyond its initial altruism-based phase.
Incentivization is not necessarily limited to monetary rewards.
Reputation may also play a role.
For Waku request-response (i.e., client-server) protocols, we envision a combination of monetary and reputation-based incentivization.
See a [write-up on incentivization](https://github.com/waku-org/research/blob/1e3ed6a5cc47e6d1e7cb99271ddef9bf38429518/docs/incentivization.md) for our high-level reasoning on the topic.
## Theory / Semantics
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
Consider a request-response protocol with two roles: a client and a server.
A server MAY indicate to a client that it expects certain eligibility criteria to be met.
In that case, a client MUST provide a valid eligibility proof as part of its request.
Forms of eligibility proofs include:
- Proof of payment: for paid non-authenticated requests. A proof of payment, in turn, may also take different forms, such as a transaction hash or a ZK-proof. In order to interpret a proof of payment, the server needs information about its type.
- Proof of membership: for services for a predefined group of users. An example use case: an application developer pays in bulk for their users' requests. A client then prove that they belong to the user set of that application. A similar concept (RLN) is used in Waku Relay for spam prevention.
- Service credential: a proof of membership in a set of clients who have prepaid for the service (which may be considered a special case of proof of membership).
Upon a receiving a request:
- the server SHOULD check if the eligibility proof is included and valid;
- if that proof is absent or invalid, the server SHOULD send back response with a corresponding error code and error description;
- if the proof is valid, the server SHOULD send back the response that the client has requested.
Note that the protocol does not ensure atomicity.
It is technically possible for a server to fail to respond to an eligible request (in violation of the protocol).
Addressing this issue is left for future work.
## Wire Format Specification / Syntax
A client includes an `EligibilityProof` in its request.
A server includes an `EligibilityStatus` in its response.
```protobuf
syntax = "proto3";
message EligibilityProof {
optional bytes proof_of_payment = 1; // e.g., a txid
// may be extended with other eligibility proof types, such as:
//optional bytes proof_of_membership = 2; // e.g., an RLN proof
}
message EligibilityStatus {
optional uint32 status_code = 1;
optional string status_desc = 2;
}
```
We include the `other_eligibility_proof` field in `EligibilityProof` to reflect other types of eligibility proofs that could be added to the protocol later.
## Implementation in Store (PoC version)
This Section describes a proof-of-concept (PoC) implementation of incentivization in the Store protocol.
Note: this section may later be moved to Store RFC.
Store is one of Waku's request-response protocols.
A Store client queries the server for historic messages.
A Store server responds with a list of messages that pass the user's filter.
See [13/WAKU2-STORE](https://rfc.vac.dev/spec/13/) for the definitions of `HistoryQuery` and `HistoryResponse`.
The PoC Store incentivization makes the following simplifying assumptions:
- the client knows the server's on-chain address `A`;
- the client and the server have agreed on a constant price `r` per hour of message history.
To query messages from a period of length `t`, the client:
1. calculates the total price `p` as `p = r * t`;
2. pays `p` to the server's address `A` with an on-chain transaction;
3. waits until the transaction is confirmed with identifier `txid`;
4. includes `txid` in the request as a proof of payment.
It is the server's responsibility to keep track of the `txid`s from prior requests and to make sure they are not reused.
Note that `txid` may not always be practical as proof of payment due to on-chain confirmation latency.
To address this issue, future versions of the protocol may involve:
- paying for multiple requests in one transaction;
- using faster (likely L2-based) payment mechanisms.
### Wire Format Specifications for Store PoC incentivization
#### Request
We extend `HistoryQuery` to include an eligibility proof:
```protobuf
message HistoryQuery {
// the first field is reserved for future use
string pubsubtopic = 2;
repeated ContentFilter contentFilters = 3;
PagingInfo pagingInfo = 4;
// numbering gap left for non-eligibility-related protocol extensions
+ optional bytes eligibility_proof = 10;
}
```
An example of usage with `txid` as a proof of payment:
```protobuf
HistoryQuery history_query {
// the first field is reserved for future use
pubsubtopic: "example_pubsub_topic"
contentFilters: []
pagingInfo: {
// provide values for PagingInfo fields
}
eligibility_proof: {
proof_of_payment: 0xabc123 // txid for the client's payment
// eligibility proofs of other types are not included
};
}
```
#### Response
We extend the `HistoryResponse` to indicate the eligibility status:
```protobuf
message HistoryResponse {
// the first field is reserved for future use
repeated WakuMessage messages = 2;
PagingInfo pagingInfo = 3;
enum Error {
NONE = 0;
INVALID_CURSOR = 1;
+ NON_ELIGIBLE = 2;
}
Error error = 4;
+ EligibilityStatus eligibility_status = 5;
}
```
Example of a response if the client is eligible:
```protobuf
HistoryResponse response_example {
messages: [message_1, message_2]
pagingInfo: paging_info
error: NONE
eligibility_status: {
status_code: 200
status_desc: "OK"
}
}
```
Example of a response if the client is not eligible:
```protobuf
HistoryResponse response_example {
messages: [] // no messages sent to non-eligible clients
pagingInfo: paging_info
error: NON_ELIGIBLE
eligibility_status: {
status_code: 402
status_desc: "PAYMENT_REQUIRED"
}
}
```
## Security/Privacy Considerations
Eligibility proofs may reveal private information about the client.
In particular, a transaction identifier used as a proof of payment links the client's query to their on-chain activity.
Potential countermeasures may include using one-time addresses or ZK-based privacy-preserving protocols.
## Limitations and Future Work
This document is intentionally simplified in its initial version.
It assumes a shared understanding of prices and the blockchain addresses of servers.
Additionally, the feasibility of paying for each query is hindered by on-chain fees and confirmation delays.
We will address these challenges as the specification evolves alongside the corresponding PoC implementation.
The following ideas will be explored:
- Batch Payment: instead of paying for an individual query, the client would make a consolidated payment for multiple messages.
- Price Negotiation: rather than receiving prices off-band, the client would engage in negotiation with the server to determine costs.
- Dynamic Pricing: the price per message would be variable, based on the total size (in bytes) of all received messages.
- Subscriptions: the client would pay for a defined time period during which they can query any number of messages, subject to DoS protection.
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
### normative
- A high-level [incentivization outline](https://github.com/waku-org/research/blob/master/incentivization.md)
- [13/WAKU2-STORE](https://rfc.vac.dev/spec/13/) (for Store-specific sections)
### informative
RFCs of request-response protocols:
- [12/WAKU2-FILTER](https://rfc.vac.dev/spec/12)
- [13/WAKU2-STORE](https://rfc.vac.dev/spec/13/)
- [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/)
RFCs of Relay and RLN-Relay:
- [11/WAKU2-RELAY](https://rfc.vac.dev/spec/11)
- [17/WAKU2-RLN-RELAY](https://rfc.vac.dev/spec/17)

37
standards/core/metadata.md Normal file
View File

@ -0,0 +1,37 @@
---
title: WAKU2-METADATA
name: Waku Metadata Protocol
editor: Alvaro Revuelta <alrevuelta@status.im>
contributors:
---
## Metadata Protocol
Waku specifies a req/resp protocol that provides information about the node's medatadata. Such metadata is meant to be used
by the node to decide if a peer is worth connecting or not. The node that makes the request, includes its metadata
so that the receiver is aware of it, without requiring an extra interaction. The parameters are the following:
* `clusterId`: Unique identifier of the cluster that the node is running in.
* `shards`: Shard indexes that the node is subscribed to.
### Protocol id
`/vac/waku/metadata/1.0.0`
### Request
```proto
message WakuMetadataRequest {
optional uint32 cluster_id = 1;
repeated uint32 shards = 2;
}
```
### Response
```proto
message WakuMetadataResponse {
optional uint32 cluster_id = 1;
repeated uint32 shards = 2;
}
```

304
standards/core/network.md Normal file
View File

@ -0,0 +1,304 @@
---
title: WAKU2-NETWORK
name: Waku v2 Network
category: Best Current Practice
editor: Hanno Cornelius <hanno@status.im>
contributors:
---
## Abstract
This RFC specifies an opinionated deployment of [10/WAKU2](https://rfc.vac.dev/spec/10/) protocols
to form a coherent and shared decentralized messaging network
that is open-access,
useful for generalized messaging,
privacy-preserving,
scalable and
accessible even to resource-restricted devices.
We'll refer to this opinionated deployment simply as
_the public Waku Network_, _the Waku Network_ or, if the context is clear, _the network_
in the rest of this document.
## Theory / Semantics
### Routing protocol
The Waku Network is built on the [17/WAKU2-RLN-RELAY](https://rfc.vac.dev/spec/17/) routing protocol,
which in turn is an extension of [11/WAKU2-RELAY](https://rfc.vac.dev/spec/11/) with spam protection measures.
### Network shards
Traffic in the Waku Network is sharded into eight [17/WAKU2-RLN-RELAY](https://rfc.vac.dev/spec/17/) pubsub topics.
Each pubsub topic is named according to the static shard naming format
defined in [WAKU2-RELAY-SHARDING](../../core/relay-sharding.md)
with:
* `<cluster_id>` set to `1`
* `<shard_number>` occupying the range `0` to `7`.
In other words, the Waku Network is a [17/WAKU2-RLN-RELAY](https://rfc.vac.dev/spec/17/) network
routed on the combination of the eight pubsub topics:
```
/waku/2/rs/1/0
/waku/2/rs/1/1
...
/waku/2/rs/1/7
```
A node MUST use [WAKU-METADATA](./metadata.md) protocol to identify the `<cluster_id>` that every
inbound/outbound peer that attempts to connect supports. In any of the following cases, the node MUST trigger a disconnection:
* [WAKU-METADATA](./metadata.md) dial fails.
* [WAKU-METADATA](./metadata.md) reports an empty `<cluster_id>`.
* [WAKU-METADATA](./metadata.md) reports a `<cluster_id>` different than `1`.
## Roles
There are two distinct roles evident in the network, those of:
1) nodes, and
2) applications.
### Nodes
Nodes are the individual software units
using [10/WAKU2](https://rfc.vac.dev/spec/10/) protocols to form a p2p messaging network.
Nodes, in turn, can participate in a shard as full relayers, i.e. _relay nodes_,
or by running a combination of protocols suitable for resource-restricted environments, i.e. _non-relay nodes_.
Nodes can also provide various services to the network,
such as storing historical messages or protecting the network against spam.
See the section on [default services](#default-services) for more.
#### Relay nodes
Relay nodes MUST follow [17/WAKU2-RLN-RELAY](https://rfc.vac.dev/spec/17/)
to route messages to other nodes in the network
for any of the pubsub topics [defined as the Waku Network shards](#network-shards).
Relay nodes MAY choose to subscribe to any of these shards,
but MUST be subscribed to at least one defined shard.
Each relay node SHOULD be subscribed to as many shards as it has resources to support.
If a relay node supports an encapsulating application,
it SHOULD be subscribed to all the shards servicing that application.
If resource restrictions prevent a relay node from servicing all shards used by the encapsulating application,
it MAY choose to support some shards as a non-relay node.
#### Bootstrapping and discovery
Nodes MAY use any method to bootstrap connection to the network,
but it is RECOMMENDED that each node retrieves a list of bootstrap peers to connect to using [EIP-1459 DNS-based discovery](https://eips.ethereum.org/EIPS/eip-1459).
Relay nodes SHOULD use [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/) to continually discover other peers in the network.
Each relay node MUST encode its supported shards into its discoverable ENR
as described in [51/WAKU2-RELAY-SHARDING](https://rfc.vac.dev/spec/51/#discovery).
The ENR MUST be updated if the set of supported shards change.
A node MAY choose to ignore discovered peers that do not support any of the shards in its own subscribed set.
#### Transports
Relay nodes MUST follow [10/WAKU2](https://rfc.vac.dev/spec/10/) specifications with regards to supporting different transports.
If TCP transport is available, each relay node MUST support it as transport for both dialing and listening.
In addition, a relay node SHOULD support secure websockets for bidirectional communication streams,
for example to allow connections from and to web browser-based clients.
A relay node MAY support unsecure websockets if required by the application or running environment.
#### Default services
For each supported shard,
each relay node SHOULD enable and support the following protocols as a service node:
1. [12/WAKU2-FILTER](https://rfc.vac.dev/spec/12/) to allow resource-restricted peers to subscribe to messages matching a specific content filter.
2. [13/WAKU2-STORE](https://rfc.vac.dev/spec/13/) to allow other peers to request historical messages from this node.
3. [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/) to allow resource-restricted peers to request publishing a message to the network on their behalf.
4. [34/WAKU2-PEER-EXCHANGE](../../core/peer-exchange/peer-exchange.md) to allow resource-restricted peers to discover more peers in a resource efficient way.
#### Store service nodes
Each relay node SHOULD support [13/WAKU2-STORE](https://rfc.vac.dev/spec/13/) as a store service node,
for each supported shard.
The store SHOULD be configured to retain at least `12` hours of messages per supported shard.
Store service nodes SHOULD only store messages with a valid [`rate_limit_proof`](#message-attributes) attribute.
#### Non-relay nodes
Nodes MAY opt out of relay functionality on any network shard
and instead request services from relay nodes as clients
using any of the defined service protocols:
1. [12/WAKU2-FILTER](https://rfc.vac.dev/spec/12/) to subscribe to messages matching a specific content filter.
2. [13/WAKU2-STORE](https://rfc.vac.dev/spec/13/) to request historical messages matching a specific content filter.
3. [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/) to request publishing a message to the network.
4. [34/WAKU2-PEER-EXCHANGE](../../core/peer-exchange/peer-exchange.md) to discover more peers in a resource efficient way.
#### Store client nodes
Nodes MAY request historical messages from [13/WAKU2-STORE](https://rfc.vac.dev/spec/13/) service nodes as store clients.
A store client SHOULD discard any messages retrieved from a store service node that do not contain a valid [`rate_limit_proof`](#message-attributes) attribute.
The client MAY consider service nodes returning messages without a valid [`rate_limit_proof`](#message-attributes) attribute as untrustworthy.
The mechanism by which this may happen is currently underdefined.
### Applications
Applications are the higher-layer projects or platforms that make use of the generalized messaging capability of the network.
In other words, an application defines a payload used in the various [10/WAKU2](https://rfc.vac.dev/spec/10/) protocols.
Any participant in an application SHOULD make use of an underlying node in order to communicate on the network.
Applications SHOULD make use of an [autosharding](#autosharding) API
to allow the underlying node to automatically select the target shard on the Waku Network. See the section on [autosharding](#autosharding) for more.
## RLN rate-limiting
The [17/WAKU2-RLN-RELAY](https://rfc.vac.dev/spec/17/) network uses [32/RLN-V1](https://rfc.vac.dev/spec/32/) proofs
to ensure that a pre-agreed rate limit is not exceeded by any publisher.
While the network is under capacity,
individual relayers MAY choose to freely route messages without RLN proofs
up to a discretionary bandwidth limit after which messages without proofs MUST be discarded.
This bandwidth limit SHOULD be enforced using [bandwidth validation mechanism](#free-bandwidth-exceeded) separate from RLN rate-limiting.
This implies that quality of service and reliability is significantly lower for messages without proofs
and at times of high network utilization these messages may not be relayed at all.
### RLN Parameters
For the Waku Network,
the `epoch` is set to `1` second
and the maximum number of messages published per `epoch` is limited to `1` per publisher.
The `max_epoch_gap` is set to `20` seconds,
meaning that validators MUST _reject_ messages with an `epoch` more than 20 seconds into the past or future compared to the validator's own clock.
All nodes, validators and publishers,
SHOULD use Network Time Protocol (NTP) to synchronize their own clocks,
thereby ensuring valid timestamps for proof generation and validation.
### Memberships
Each publisher to the Waku Network SHOULD register an RLN membership
with one of the RLN storage contracts
moderated in the Sepolia registry contract with address [0xF1935b338321013f11068abCafC548A7B0db732C](https://sepolia.etherscan.io/address/0xF1935b338321013f11068abCafC548A7B0db732C#code).
Initial memberships are registered in the Sepolia RLN storage contract with address [0x58322513A35a8f747AF5A385bA14C2AbE602AA59](https://sepolia.etherscan.io/address/0x58322513A35a8f747AF5A385bA14C2AbE602AA59#code).
RLN membership setup and registration MUST follow [17/WAKU-RLN-RELAY](https://rfc.vac.dev/spec/17/#setup-and-registration),
with the `staked_fund` set to `0`.
In other words, the Waku Network does not use RLN staking.
### RLN Proofs
Each RLN member MUST generate and attach an RLN proof to every published message
as described in [17/WAKU-RLN-RELAY](https://rfc.vac.dev/spec/17/#publishing).
Slashing is not implemented for the Waku Network.
Instead, validators will penalise peers forwarding messages exceeding the rate limit
as specified for [the rate-limiting validation mechanism](#rate-limit-exceeded).
This incentivizes all nodes to validate RLN proofs
and reject messages violating rate limits
in order to continue participating in the network.
## Network traffic
All payload on the Waku Network MUST be encapsulated in a [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/)
with rate limit proof extensions defined for [17/WAKU2-RLN-RELAY](https://rfc.vac.dev/spec/17/#payloads).
Each message on the Waku Network SHOULD be validated by each relayer,
according to the rules discussed under [message validation](#message-validation).
### Message Attributes
- The mandatory `payload` attribute MUST contain the message data payload as crafted by the application.
- The mandatory `content_topic` attribute MUST specify a string identifier that can be used for content-based filtering. This is also crafted by the application. See [Autosharding](#autosharding) for more on the content topic format.
- The optional `meta` attribute MAY be omitted. If present this will form part of the message uniqueness vector described in [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/).
- The optional `version` attribute SHOULD be set to `0`. It MUST be interpreted as `0` if not present.
- The mandatory `timestamp` attribute MUST contain the Unix epoch time at which the message was generated by the application. The value MUST be in nanoseconds. It MAY contain a fudge factor of up to 1 seconds in either direction to improve resistance to timing attacks.
- The optional `ephemeral` attribute MUST be set to `true` if the message should not be persisted by the Waku Network.
- The optional `rate_limit_proof` attribute SHOULD be populated with the RLN proof as set out in [RLN Proofs](#rln-proofs). Messages with this field unpopulated MAY be discarded from the network by relayers. This field MUST be populated if the message should be persisted by the Waku Network.
### Message Size
Any Waku Message published to the network MUST NOT exceed an absolute maximum size of `150` kilobytes.
This limit applies to the entire message after protobuf serialization, including attributes.
It is RECOMMENDED not to exceed an average size of `4` kilobytes for Waku Messages published to the network.
### Message Validation
Relay nodes MUST apply [gossipsub v1.1 validation](https://github.com/libp2p/specs/blob/c96c9ec5909d64fe020d7630f3fd982bc18fd06a/pubsub/gossipsub/gossipsub-v1.1.md#extended-validators) to each relayed message and
SHOULD apply all of the rules set out in the section below to determine the validity of a message.
Validation has one of three outcomes,
repeated here from the [gossipsub specification](https://github.com/libp2p/specs/blob/c96c9ec5909d64fe020d7630f3fd982bc18fd06a/pubsub/gossipsub/gossipsub-v1.1.md#extended-validators) for ease of reference:
1. Accept - the message is considered valid and it MUST be delivered and forwarded to the network.
2. Reject - the message is considered invalid, MUST be rejected and SHOULD trigger a gossipsub scoring penalty against the transmitting peer.
3. Ignore - the message SHOULD NOT be delivered and forwarded to the network, but this MUST NOT trigger a gossipsub scoring penalty against the transmitting peer.
The following validation rules are defined:
#### Decoding failure
If a message fails to decode as a valid [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/).
the relay node MUST _reject_ the message.
This SHOULD trigger a penalty against the transmitting peer.
#### Invalid timestamp
If a message has a timestamp deviating by more than `20` seconds
either into the past or the future
when compared to the relay node's internal clock,
the relay node MUST _reject_ the message.
This allows for some deviation between internal clocks,
network routing latency and
an optional [fudge factor when timestamping new messages](#message-attributes).
#### Free bandwidth exceeded
If a message contains no RLN proof
and the current bandwidth utilization on the shard the message was published to
equals or exceeds `1` Mbps,
the relay node SHOULD _ignore_ the message.
#### Invalid RLN epoch
If a message contains an RLN proof
and the `epoch` attached to the proof deviates by more than `max_epoch_gap` seconds
from the relay node's own `epoch`,
the relay node MUST _reject_ the message.
`max_epoch_gap` is [set to `20` seconds](#rln-parameters) for the Waku Network.
#### Invalid RLN proof
If a message contains an RLN proof
and the zero-knowledge proof is invalid
according to the verification process described in [32/RLN-V1](https://rfc.vac.dev/spec/32/#verification),
the relay node MUST _ignore_ the message.
#### Rate limit exceeded
If a message contains an RLN proof
and the relay node detects double signaling
according to the verification process described in [32/RLN-V1](https://rfc.vac.dev/spec/32/#verification),
the relay node MUST _reject_ the message
for violating the agreed rate limit of `1` message every `1` second.
This SHOULD trigger a penalty against the transmitting peer.
## Autosharding
Nodes in the Waku Network SHOULD allow encapsulating applications to use autosharding,
as defined in [51/WAKU2-RELAY-SHARDING](https://rfc.vac.dev/spec/51/#automatic-sharding)
by automatically determining the appropriate pubsub topic
from the list [of defined Waku Network shards](#network-shards).
This allows the application to omit the target pubsub topic
when invoking any Waku protocol function.
Applications using autosharding MUST use content topics in the format
defined in [51/WAKU2-RELAY-SHARDING](https://rfc.vac.dev/spec/51/#content-topics-format-for-autosharding)
and SHOULD use the short length format:
```
/{application-name}/{version-of-the-application}/{content-topic-name}/{encoding}`
```
When an encapsulating application makes use of autosharding
the underlying node MUST determine the target pubsub topic(s)
from the content topics provided by the application
using the hashing mechanism defined in [51/WAKU2-RELAY-SHARDING](https://rfc.vac.dev/spec/51/#automatic-sharding).
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
* [WAKU2-RELAY-SHARDING](../../core/relay-sharding.md)
* [Peer-exchange](../../core/peer-exchange/peer-exchange.md)
## normative
(TBD)
A list of references that MUST be read to fully understand and/or implement this protocol.
See [RFC3967 Section 1.1](https://datatracker.ietf.org/doc/html/rfc3967#section-1.1).
## informative
(TBD)
A list of additional references.

168
standards/core/peer-exchange.md Normal file
View File

@ -0,0 +1,168 @@
---
title: WAKU2-PEER-EXCHANGE
name: Waku v2 Peer Exchange
category: Standards Track
tags: waku/core-protocol
editor: Daniel Kaiser <danielkaiser@status.im>
contributors:
---
## Abstract
This document specifies a simple request-response peer exchange protocol.
Responders send information about a requested number of peers.
The main purpose of this protocol is providing resource restricted devices with peers.
**Protocol identifier**: /vac/waku/peer-exchange/2.0.0-alpha1
## Background and Motivation
It may not be feasible on resource restricted devices to take part in distributed random sampling ambient peer discovery protocols such as [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/).
The Waku peer discovery protocol specified in this document allows resource restricted devices to request a list of peers from a service node.
Network parameters necessary to connect to this service node COULD be learned from a static bootstrapping method or using [EIP-1459: Node Discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459).
The advantage of using Waku peer exchange to discover new peers over using a static peer list or DNS discovery is a more even load distribution.
If a lot of (resource restricted) nodes would use the same service nodes as relay or store nodes, the load on these would be very high.
Heavily used static nodes also add a centralized element. Downtime of such a node might significantly impact the network.
However, the resource efficiency of this protocol comes at an anonymity cost, which is explained in the [Security/Privacy Considerations](#securityprivacy-considerations) section.
This protocol SHOULD only be used if [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/) is infeasible.
## Theory and Protocol Semantics
The peer exchange protocol specified in this document is a simple request-response protocol.
As Figure 1 illustrates, the requesting node sends a request to a peer, which acts as the responder.
The responder replies with a list of ENRs as specified in [WAKU2-ENR](../enr.md).
The [multiaddresses](https://docs.libp2p.io/concepts/addressing/) used to connect to the respective peers can be extracted from the ENRs.
![Figure 1: The responder provides a list of ENRs to the requester. These ENRs contain the information necessary for connecting to the respective peers.](../../images/protocol.svg)
In order to protect its anonymity, the responder MUST NOT provide peers from its actively used peer list as this opens pathways to *Neighbourhood Surveillance* attacks, as described in the
[Security/Privacy Considerations Section](#securityprivacy-considerations).
The responder SHOULD provide a set of peers that has been retrieved using ambient peer discovery methods supporting random sampling, e.g. [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/).
This both protects the responder's anonymity as well as helps distributing load.
To allow for fast responses, responders SHOULD retrieve peers unsolicited (before receiving a query)
and maintain a queue of peers for the purpose of providing them in peer exchange responses.
To get the best anonymity properties with respect to response peer sets, responders SHOULD use each of these peers only once.
To save bandwidth, and as a trade off to anonymity,
responders MAY maintain a larger cache of exchange peers and randomly sample response sets from this local cache.
The size of the cache SHOULD be large enough to allow randomly sampling peer sets that (on average) do not overlap too much.
The responder SHOULD periodically replace the oldest peers in the cache.
This document provides recommended choices for the cache size in the [Implementation Suggestions Section](#implementation-suggestions).
Requesters, in the context of the specified peer exchange protocol, SHOULD be resource restricted devices.
While any node could technically act as a requester, using the peer exchange protocol comes with two drawbacks:
* reducing [anonymity](#securityprivacy-considerations)
* causing load on responder nodes
## Wire Format Specification
```protobuf
syntax = "proto3";
message PeerInfo {
bytes enr = 1;
}
message PeerExchangeQuery {
uint64 num_peers = 1;
}
message PeerExchangeResponse {
repeated PeerInfo peer_infos = 1;
}
message PeerExchangeRPC {
PeerExchangeQuery query = 1;
PeerExchangeResponse response = 2;
}
```
The `enr` field contains a Waku ENR as specified in [WAKU2-ENR](../enr.md).
Requesters send a `PeerExchangeQuery` to a peer.
Responders SHOULD include a maximum of `num_peers` `PeerInfo` instances into a response.
Responders send a `PeerExchangeResponse` to requesters containing a list of `PeerInfo` instances, which in turn hold an ENR.
## Implementation Suggestions
### Discovery Interface
Implementations can implement the libp2p discovery interface (e.g. [nim](https://github.com/status-im/nim-libp2p/issues/140), [javascript](https://github.com/libp2p/js-libp2p-interfaces/tree/master/packages/interface-peer-discovery)).
### Exchange Peer Cache Size
The size of the (optional) exchange peer cache discussed in [Theory and Protocol Semantics](#theory-and-protocol-semantics)
depends on the average number of requested peers, which is expected to be the outbound degree of the underlying
[libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md) mesh network.
The recommended value for this outbound degree is 6 (see parameter `D` in [29/WAKU2-CONFIG](https://rfc.vac.dev/spec/29/)).
It is recommended for the cache to hold at least 10 times as many peers (60).
The recommended cache size also depends on the number of requesters a responder is expected to serve within a *refresh cycle*.
A refresh cycle is the time interval in which all peers in the cache are expected to be replaced.
If the number of requests expected per refresh cycle exceeds 600 (10 times the above recommended 60),
it is recommended to increase the cache size to at least a tenth of that number.
We will investigate peer exchange cache sizes and refresh strategies,
and provide suggestions based on that in future versions (draft, stable) of this document.
## Security/Privacy/Anonymity Considerations
The peer exchange protocol specified in this document comes with anonymity and security implications.
We differentiate these implications into the requester and responder side, respectively.
### Requester
With a simple peer exchange protocol, the requester is inherently susceptible to both *neighbourhood surveillance* and *controlled neighbourhood* attacks.
To mount a *neighbourhood surveillance* attack, an attacker has to connect to the peers of the victim node.
The peer exchange protocol allows a malicious responder to easily get into this position.
The responder connects to a set of peers and simply returns this set of peers to the requester.
The peer exchange protocol also makes it much easier to get into the position required for the *controlled neighbourhood* attack:
A malicious responder provides controlled peers in the response peer list.
More on these attacks may be found in our [research log article](https://vac.dev/wakuv2-relay-anon).
As a weak mitigation the requester MAY ask several peers and select a subset of the returned peers.
### Responder
Responders that answer with active mesh peers are more vulnerable to a *neighbourhood surveillance* attack.
Responding with the set of active mesh peers allows a malicious requester to get into the required position more easily.
It takes away the first hurdle of the *neighbourhood surveillance* attack: The attacker knows which peers to try to connect to.
This increased vulnerability can be avoided by only responding with randomly sampled sets of peers, e.g. by requesting a random peer set via [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/).
(As stated in the [Theory and Protocol Semantics Section](#theory-and-protocol-semantics),
these peer sets SHOULD be retrieved unsolicitedly before receiving requests to achieve faster response times.)
Responders are also susceptible to amplification DoS attacks.
Requesters send a simple message request which causes responders to engage in ambient peer discovery to retrieve a new random peer set.
As a mitigation, responders MAY feature a `seen cache` for requests and only answer once per time interval.
The exchange-peer cache discussed in [Theory and Protocol Semantics Section](#theory-and-protocol-semantics) also provides mitigation.
Still, frequent queries can tigger the refresh cycle more often. The `seen cache` MAY be used in conjunction to provide additional mitigation.
### Further Considerations
The response field contains ENRs as specified in [WAKU2-ENR](../enr.md).
While ENRs contain signatures, they do not violate the [Waku relay no-sign policy](https://rfc.vac.dev/spec/11/#signature-policy)),
because they are part of the discovery domain and are not propagated in the relay domain.
However, there might still be some form of leakage:
ENRs could be used to track peers and facilitate linking attacks.
We will investigate this further in our Waku anonymity analysis.
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
* [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/)
* [WAKU2-ENR](../enr.md)
* [multiaddress](https://docs.libp2p.io/concepts/addressing/)
* [libp2p discovery interface](https://github.com/status-im/nim-libp2p/issues/140)
* [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md)
* [29/WAKU2-CONFIG](https://rfc.vac.dev/spec/29/)
* [Waku relay anonymity](https://vac.dev/wakuv2-relay-anon)

278
standards/core/relay-sharding.md Normal file
View File

@ -0,0 +1,278 @@
---
title: RELAY-SHARDING
name: Waku v2 Relay Sharding
status: raw
category: Standards Track
tags: waku/core
editor: Daniel Kaiser <danielkaiser@status.im>
contributors:
- Simon-Pierre Vivier <simvivier@status.im>
---
## Abstract
This document describes ways of sharding the [Waku relay](https://rfc.vac.dev/spec/11/) topic,
allowing Waku networks to scale in the number of content topics.
> *Note*: Scaling in the size of a single content topic is out of scope for this document.
## Background and Motivation
[Unstructured P2P networks](https://en.wikipedia.org/wiki/Peer-to-peer#Unstructured_networks)
are more robust and resilient against DoS attacks compared to
[structured P2P networks](https://en.wikipedia.org/wiki/Peer-to-peer#Structured_networks)).
However, they do not scale to large traffic loads.
A single [libp2p gossipsub mesh](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0.md#gossipsub-the-gossiping-mesh-router),
which carries messages associated with a single pubsub topic, can be seen as a separate unstructured P2P network
(control messages go beyond these boundaries, but at its core, it is a separate P2P network).
With this, the number of [Waku relay](https://rfc.vac.dev/spec/11/) content topics that can be carried over a pubsub topic is limited.
This prevents app protocols that aim to span many multicast groups (realized by content topics) from scaling.
This document specifies three pubsub topic sharding methods (with varying degrees of automation),
which allow application protocols to scale in the number of content topics.
This document also covers discovery of topic shards.
## Named Sharding
*Named sharding* offers apps to freely choose pubsub topic names.
It is RECOMMENDED for App protocols to follow the naming structure detailed in [23/WAKU2-TOPICS](https://rfc.vac.dev/spec/23/).
With named sharding, managing discovery falls into the responsibility of apps.
From an app protocol point of view, a subscription to a content topic `waku2/xxx` on a shard named /mesh/v1.1.1/xxx would look like:
`subscribe("/waku2/xxx", "/mesh/v1.1.1/xxx")`
## Static Sharding
*Static sharding* offers a set of shards with fixed names.
Assigning content topics to specific shards is up to app protocols,
but the discovery of these shards is managed by Waku.
Static shards are managed in shard clusters of 1024 shards per cluster.
Waku static sharding can manage $2^16$ shard clusters.
Each shard cluster is identified by its index (between $0$ and $2^16-1$).
A specific shard cluster is either globally available to all apps,
specific for an app protocol,
or reserved for automatic sharding (see next section).
> *Note:* This leads to $2^16 * 1024 = 2^26$ shards for which Waku manages discovery.
App protocols can either choose to use global shards, or app specific shards.
Like the [IANA ports](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml),
shard clusters are divided into ranges:
| index (range) | usage |
| --- | --- |
| 0 - 15 | reserved |
| 16 - 65535| app-defined networks |
The informational RFC [WAKU2-RELAY-STATIC-SHARD-ALLOC](../../informational/relay-static-shard-alloc.md) lists the current index allocations.
The global shard with index 0 and the "all app protocols" range are treated in the same way,
but choosing shards in the global cluster has a higher probability of sharing the shard with other apps.
This offers k-anonymity and better connectivity, but comes at a higher bandwidth cost.
The name of the pubsub topic corresponding to a given static shard is specified as
`/waku/2/rs/<cluster_id>/<shard_number>`,
an example for the 2nd shard in the global shard cluster:
`/waku/2/rs/0/2`.
> *Note*: Because *all* shards distribute payload defined in [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/) via [protocol buffers](https://developers.google.com/protocol-buffers/),
the pubsub topic name does not explicitly add `/proto` to indicate protocol buffer encoding.
We use `rs` to indicate these are *relay shard* clusters; further shard types might follow in the future.
From an app point of view, a subscription to a content topic `waku2/xxx` on a static shard would look like:
`subscribe("/waku2/xxx", 43)`
for global shard 43.
And for shard 43 of the Status app (which has allocated index 16):
`subscribe("/waku2/xxx", 16, 43)`
### Discovery
Waku v2 supports the discovery of peers within static shards,
so app protocols do not have to implement their own discovery method.
Nodes add information about their shard participation in their [WAKU2-ENR](./enr.md/).
Having a static shard participation indication as part of the ENR allows nodes
to discover peers that are part of shards via [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/) as well as via DNS.
> *Note:* In the current version of this document,
sharding information is directly added to the ENR.
(see Ethereum ENR sharding bit vector [here](https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/p2p-interface.md#metadata)
Static relay sharding supports 1024 shards per cluster, leading to a flag field of 128 bytes.
This already takes half (including index and key) of the ENR space of 300 bytes.
For this reason, the current specification only supports a single shard cluster per node.
In future versions, we will add further (hierarchical) discovery methods.
We will update [WAKU2-ENR](./enr.md) accordingly, once this RFC moves forward.
This document specifies two ways of indicating shard cluster participation.
The index list SHOULD be used for nodes that participante in fewer than 64 shards,
the bit vector representation SHOULD be used for nodes participating in 64 or more shards.
Nodes MUST NOT use both index list (`rs`) and bit vector (`rsv`) in a single ENR.
ENRs with both `rs` and `rsv` keys SHOULD be ignored.
Nodes MAY interpret `rs` in such ENRs, but MUST ignore `rsv`.
#### Index List
| key | value |
|--- |--- |
| `rs` | <2-byte shard cluster index> &#124; <1-byte length> &#124; <2-byte shard index> &#124; ... &#124; <2-byte shard index> |
The ENR key is `rs`.
The value is comprised of
* a two-byte shard cluster index in network byte order, concatenated with
* a one-byte length field holding the number of shards in the given shard cluster, concatenated with
* two-byte shard indices in network byte order
Example:
| key | value |
|--- |--- |
| `rs` | 16u16 &#124; 3u8 &#124; 13u16 &#124; 14u16 &#124; 45u16 |
This example node is part of shards `13`, `14`, and `45` in the Status main-net shard cluster (index 16).
#### Bit Vector
| key | value |
|--- |--- |
| `rsv` | <2-byte shard cluster index> &#124; <128-byte flag field> |
The ENR key is `rsv`.
The value is comprised of a two-byte shard cluster index in network byte order concatenated with a 128-byte wide bit vector.
The bit vector indicates which shards of the respective shard cluster the node is part of.
The right-most bit in the bit vector represents shard `0`, the left-most bit represents shard `1023`.
The representation in the ENR is inspired by [Ethereum shard ENRs](https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/validator.md#sync-committee-subnet-stability)),
and [this](https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/validator.md#sync-committee-subnet-stability)).
Example:
| key | value |
|--- |--- |
| `rsv` | 16u16 &#124; `0x[...]0000100000003000` |
The `[...]` in the example indicates 120 `0` bytes.
This example node is part of shards `13`, `14`, and `45` in the Status main-net shard cluster (index 16).
(This is just for illustration purposes, a node that is only part of three shards should use the index list method specified above.)
## Automatic Sharding
Autosharding selects shards automatically and is the default behavior for shard choice.
The other choices being static and named sharding as seen in previous sections.
Shards (pubsub topics) SHOULD be computed from content topics with the procedure below.
#### Algorithm
Hash using Sha2-256 the concatenation of
the content topic `application` field (UTF-8 string of N bytes) and
the `version` (UTF-8 string of N bytes).
The shard to use is the modulo of the hash by the number of shards in the network.
#### Example
| Field | Value | Hex
|--- |--- |---
| `application` | "myapp"| 0x6d79617070
| `version` | "1" | 0x31
| `network shards`| 8 | 0x8
- SHA2-256 of `0x6d7961707031` is `0x8e541178adbd8126068c47be6a221d77d64837221893a8e4e53139fb802d4928`
- `0x8e541178adbd8126068c47be6a221d77d64837221893a8e4e53139fb802d4928` MOD `8` equals `0`
- The shard to use has index 0
### Content Topics Format for Autosharding
Content topics MUST follow the format in [23/WAKU2-TOPICS](https://rfc.vac.dev/spec/23/#content-topic-format).
In addition, a generation prefix MAY be added to content topics.
When omitted default values are used.
Generation default value is `0`.
- The full length format is `/{generation}/{application-name}/{version-of-the-application}/{content-topic-name}/{encoding}`
- The short length format is `/{application-name}/{version-of-the-application}/{content-topic-name}/{encoding}`
#### Example
- Full length `/0/myapp/1/mytopic/cbor`
- Short length `/myapp/1/mytopic/cbor`
#### Generation
The generation number monotonously increases and indirectly refers to the total number of shards of the Waku Network.
<!-- Create a new RFC for each generation spec. -->
#### Topic Design
Content topics have 2 purposes: filtering and routing.
Filtering is done by changing the `{content-topic-name}` field.
As this part is not hashed, it will not affect routing (shard selection).
The `{application-name}` and `{version-of-the-application}` fields do affect routing.
Using multiple content topics with different `{application-name}` field has advantages and disadvantages.
It increases the traffic a relay node is subjected to when subscribed to all topics.
It also allows relay and light nodes to subscribe to a subset of all topics.
### Problems
#### Hot Spots
Hot spots occur (similar to DHTs), when a specific mesh network (shard) becomes responsible for (several) large multicast groups (content topics).
The opposite problem occurs when a mesh only carries multicast groups with very few participants: this might cause bad connectivity within the mesh.
The current autosharding method does not solve this problem.
> *Note:* Automatic sharding based on network traffic measurements to avoid hot spots in not part of this specification.
#### Discovery
For the discovery of automatic shards this document specifies two methods (the second method will be detailed in a future version of this document).
The first method uses the discovery introduced above in the context of static shards.
The second discovery method will be a successor to the first method,
but is planned to preserve the index range allocation.
Instead of adding the data to the ENR, it will treat each array index as a capability,
which can be hierarchical, having each shard in the indexed shard cluster as a sub-capability.
When scaling to a very large number of shards, this will avoid blowing up the ENR size, and allows efficient discovery.
We currently use [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/) for discovery,
which is based on Ethereum's [discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md).
While this allows to sample nodes from a distributed set of nodes efficiently and offers good resilience,
it does not allow to efficiently discover nodes with specific capabilities within this node set.
Our [research log post](https://vac.dev/wakuv2-apd) explains this in more detail.
Adding efficient (but still preserving resilience) capability discovery to discv5 is ongoing research.
[A paper on this](https://github.com/harnen/service-discovery-paper) has been completed,
but the [Ethereum discv5 specification](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory.md)
has yet to be updated.
When the new capability discovery is available,
this document will be updated with a specification of the second discovery method.
The transition to the second method will be seamless and fully backwards compatible because nodes can still advertise and discover shard memberships in ENRs.
## Security/Privacy Considerations
See [WAKU2-ADVERSARIAL-MODELS](../../informational/adersarial-models.md), especially the parts on k-anonymity.
We will add more on security considerations in future versions of this document.
### Receiver Anonymity
The strength of receiver anonymity, i.e. topic receiver unlinkablity,
depends on the number of content topics (`k`), as a proxy for the number of peers and messages, that get mapped onto a single pubsub topic (shard).
For *named* and *static* sharding this responsibility is at the app protocol layer.
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
* [11/WAKU2-RELAY](https://rfc.vac.dev/spec/11/)
* [Unstructured P2P network](https://en.wikipedia.org/wiki/Peer-to-peer#Unstructured_networks)
* [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/)
* [WAKU2-ENR](./enr.md)
* [23/WAKU2-TOPICS](https://rfc.vac.dev/spec/23/)
* [Ethereum ENR sharding bit vector](https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/p2p-interface.md#metadata)
* [Ethereum discv5 specification](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory.md)
* [Research log: Waku Discovery](https://vac.dev/wakuv2-apd)
* [WAKU2-RELAY-STATIC-SHARD-ALLOC](../../informational/relay-static-shard-alloc.md)

69
template.md Normal file
View File

@ -0,0 +1,69 @@
---
title: TEMPLATE
name: Specification Template
category: (Standards Track|Informational|Best Current Practice)
tags: an optional list of tags, not standard
editor: Jimmy Debe <jimmy@status.im>
contributors:
---
### (Info, remove this section)
This section contains meta info about writing specifications.
This section (including its subsections) MUST be removed.
[COSS](https://rfc.vac.dev/spec/1/) explains the Vac RFC process.
### Tags
The `tags` metadata SHOULD contain a list of tags if applicable.
* `core` for Waku protocol definitions
* `application` for applications built on top of Waku protocol,
* `informational` for general guidelines, background information etc.
## Abstract
## Background / Rationale / Motivation
This section serves as an introduction providing background information and a motivation/rationale for the specification.
## Theory / Semantics
This section SHOULD explain in detail how the proposed protocol works.
It may touch on the wire format where necessary for the explanation.
This section MAY also specify endpoint behaviour when receiving specific messages, e.g. the behaviour of certain caches etc.
## Wire Format Specification / Syntax
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”,
“NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
This section SHOULD not contain explanations of semantics and focus on concisely defining the wire format.
Implementations SHOULD adhere to these exact formats to interoperate with other implementations.
It is fine, if parts of the previous section that touch on the wire format are repeated.
The purpose of this section is having a concise definition of what an implementation sends and accepts.
Parts that are not specified here are considered implementation details.
Implementors are free to decide on how to implement these details.
## Implementation Suggestions (optional)
An optional *implementation suggestions* section may provide suggestions on how to approach implementation details, and,
if available, point to existing implementations for reference.
## (Further Optional Sections)
## Security/Privacy Considerations
If there are none, this section MAY state that fact.
This section MAY contain additional relevant information, e.g. an explanation as to why there are no security consideration for the respective document.
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
A list of references.