Filename: ExtraRelayDescriptorFields.txt
Title: Adding x-namespace to relay descriptor for key:value pairs
Author: Virgil Griffith
Created: 2015-09-30
Status: Open
1. Motivation
We wish to allow developers to build new applications atop relays. Towards this end, we wish to add the ability for users to specify arbitrary new key-value entries under the "X-" namespace to the router descriptor [1]. The canonical applications for this are adding a bitcoin donation address and networking of tor2web nodes.
2. Proposal
Allow optional key-value lines in the relay's torrc file. These lines will be mirrored in the relay's descriptor which is then published in the directory consensus.
The following would be added to section 2.1.2 of the dir-spec
(Extra-info document format):
========================================================
"X-" CustomKey SP CustomValue NL
CustomKeyChar = "a"-"z" / "0" - "9" / "-" / "_"
CustomKey = 1*32 CustomKeyChar
CustomValueChar = atext / specialsÂ
CustomValue = 1*1024 CustomValueChar
Custom fields can appear multiple times, for example...
X-bitcoin 19mP9FKrXqL46Si58pHdhGKow88SUPy1V8
X-favoritequote Be excellent to each other. Party on dudes!
X-foo bar
If the same CustomKey appearing more than once is disallowed.
Possible values for CustomValueChar as specified per RFC 2822.
The sum size accounting for all such custom fields is truncated to 5 kilobytes.
========================================================
To mitigate the chance of a malformed torrc file, I additionally propose that the relay descriptor be scanned and if it does not match the specification, that it exit with error telling her torrc file is a likely culprit.
-V