Version 3
The Tor relay ContactInfo string was primarily
intended to contain an email address and PGP key fingerprint but since this field accepts an arbitrary string
it has been used for multiple other purposes (website URLs, donation information, bitcoin addresses, …).
Making use of provided information in an automated way is hard since there is no specification on how
this string should look like. This is a specification to formalize the ContactInfo string.
This specification is optional (opt-in), operators can choose to implement it or not.
An example ContactInfo string as defined by this specification could look like this:
foo bar email:tor[]example.com url:https://example.com proof:uri-familyid-ed25519 uplinkbw:1000 ciissversion:3
In words this means:
url can be fetched from https://example.com/.well-known/tor-relay/ed25519-family-id.txtThe fields specified in this document coexist with other arbitrary strings located in the relay’s ContactInfo descriptor field. Defined fields may appear at any position within the ContactInfo string. A field identifier (key) MUST only be used once, if it appears multiple times in the ContactInfo string only the first occurence is considered. UTF-8 is supported to the extent that Tor supports it (proposal 285). Punycode encoding should be used for internationalized domain names.
Information is provided in key-value pairs:
key ":" value WS key ":" value ...
keys and values MUST NOT contain any whitespace. WS is a single or multiple whitespace characters (space, tab, ..). The order of keys is not mandatory but SHOULD follow the order in which they appear in this specification. Specifically the email field SHOULD be the first field.
The version field (ciissversion) and at least one additional field (any) is mandatory.
This field contains the email address of the technical contact managing this Tor relay. The given email address SHOULD be the same for all relays this entity manages. The value is an addr-spec as defined in RFC5322 but the “@” sign SHOULD be replaced with “[]”. We are aware that this is trivially defeated anti-spam “protection” but not all email address scrapers are aware of this specification (not targeted for Tor contact info data).
example value:
contact[]example.com
This field contains a URL (or hostname) pointing to the website of the entity (organization or person) responsible for this Tor relay.
If the url field is set, the proof field MUST also be set.
In most cases the responsible entity will be the same as the technical contact mentioned in the email field.
This field MUST be consistent across all relays where this entity is responsible.
It MUST point to a specific (non-shared) domain/hostname. Two organizations/persons can not have the same field content.
The url field is verified using the selected proof method described below (proof field).
When displaying the url field content on websites and tools implementing this specification:
url SHOULD be ignored if verification does not succeed.In cases where the responsible organization or person does not have a website, this field can be used to specify a DNS domain only. In that case “http(s)://” is omitted.
length: < 400 characters
valid characters: [_%/:a-zA-Z0-9.-]
example value:
https://example.com
The proof field is mandatory when the url field is set. It is ignored when url is not set.
The proof field gives the operator the option to tell interested entities how they can verify the domain in the url field.
This prevents operators from claiming arbitrary domains.
Since the url can be set to an arbitrary value - without consent of the entity it points to -
the proof field tells interested parties how they can verify the url value.
All relays using a given url value MUST have the same consistent proof value.
You can not use multiple distinct proof values within a single group of relays using a certain url value.
A relay operator can choose one out of two options to establish a proof (proofs can not be combined), they are also the two possible field values:
Tools performing proof checks SHOULD re-verify the proof at least every 6 months.
The “uri-familyid-ed25519” proof method uses the well-known “tor-relay” URI
/.well-known/tor-relay/ed25519-family-id.txt
to publish the public family ID on a fixed location on the domain given in the url field for verification.
The public family ID is written to a file ending with .public_family_id as a result of the tor --keygen-family filename command when generating the happy family key.
The public family ID is a 43 characters long case sensitive string.
Example: If the url points to “https://example.com”, the verification process fetches the ed25519 public family ID from:
https://example.com/.well-known/tor-relay/ed25519-family-id.txt
The text file must contain the public ed25519 family ID of the operator. During key rollover more than one public family ID might be present in the file.
The path and filename is static and defined in Tor proposal 326.
The text file MUST NOT contain the secret_family_key content!
Note: This URI MUST be accessible via HTTPS regardless whether the url uses HTTPS or not. The URI MUST NOT redirect to another domain.
The “dns-familyid-ed25519” proof method uses DNS instead of HTTPS.
DNSSEC MUST be enabled on the domain located in the url field to ensure the integrity of DNS records.
When choosing this method (for example because no webserver is available) the operator creates a single DNS TXT record
to prove its url field.
These DNS TXT records look as follows (example: url:example.com):
we-run-this-tor-ed25519-family-id.example.com
value: “put your public ed25519 family ID here” (a 43 character long case sensitive string)
During key rollover two DNS TXT records might exist at the same time.
It MUST NOT contain the secret_family_key content!
40 characters PGP key fingerprint (long form) without leading “0x” and without spaces.
Case insensitive. This key relates to the email address given in the email field,
but providing the pgp field without an email field is also possible.
This key SHOULD be available on https://keys.openpgp.org
length: MUST be exactly 40 characters long
valid characters: [a-fA-F0-9]
example value:
EF6E286DDA85EA2A4BA7DE684E2C6E8793298290
Email address of the abuse handling contact for this Tor relay. This is primarily relevant for Tor exit relays but can also be used on non-exit relays. The value is an addr-spec as defined in RFC5322 but the “@” sign SHOULD be replaced with “[]”. We are aware that this is trivially defeated anti-spam “protection” but not all email address scrapers are aware of this specification (not targeted for Tor contact info data).
example value:
abuse[]example.com
The technical contact’s keybase username. This identifier MUST be usable to create a valid keybase.io profile URL.
length: < 50 characters
valid characters: [a-fA-F0-9]
example value:
nusenu
The entity’s twitter/X username without the leading “@” (non-technical contact). The username MUST be usable to create a valid twitter/X profile URL. If the responsible organization or person has no twitter/X account, the technical contact’s twitter/X handle can be used instead.
length: MUST be 1-15 characters long
valid characters: [a-zA-Z0-9_]
example value:
torproject
The entity’s bluesky username without the leading “@” and trailing “.bsky.social”.
length: MUST be 1-50 characters long
example value:
torproject.org
URL pointing to the entity’s mastodon profile (responsible organization/person).
length: < 254 characters
example value:
https://mastodon.social/@nusenu
Matrix user identifier for the technical contact for this Tor relay.
example value:
@user:example.com
This field contains a Signal username.
Signal usernames are case insensitive.
length: <40 characters
valid characters: [a-z0-9_.]
This field contains an IRC network/nickname. The nickname MUST be registered.
length: <100
example value:
irc.oftc.net/exampleusername
XMPP handle for the technical contact of this Tor relay. The “@” sign SHOULD be replaced with “[]”.
length: < 254 characters
example value:
user[]example.com
OTR version 3 key fingerprint without spaces.
Case insensitive. This key fingerprint relates to the xmpp address given in the xmpp field.
length: MUST be exactly 40 characters long
valid characters: [a-fA-F0-9]
example value:
EF6E286DDA85EA2A4BA7DE684E2C6E8793298290
Commercial hoster domain where this server has been ordered. This is supposed to help other relay operators and future relay operators to find hosting providers. To normalize the provided domain:
If you are your own ISP (and are not offering a commercial service for others) this field MUST be omitted.
length: < 254 characters
valid characters: [a-zA-Z0-9.-]
example:
www.example-hoster.com
Monthly hosting costs the hosting company is charging for the server. This does not include time spent managing the relay. The amount MUST be provided with two digits after the decimal separator. The decimal separator MUST be a full stop (not a comma). The value MUST be followed by the currency in ISO4217 format.
On servers with multiple Tor instances the server hosting costs given in this field MUST be divided through the number of Tor relay instances running on that OS.
length: < 13 characters
valid characters: [A-Z0-9.]
example:
10.70USD
10.00EUR
invalid examples:
1USD
1.1USD
1,10USD
Logical network interface speed in Mbit/s (1Mbit/s = 1 000 000 Bit/s) or the value of RelayBandwidthRate in your torrc setting (whatever is smaller). For asymmetrical uplinks specify the lower of up- and download bandwidth.
On a server with multiple Tor instances the total available bandwidth of the server MUST be divided by the number of Tor relay instances running on it. This is an integer value.
length: < 7 characters
valid characters: [0-9]
example:
100
States if this is an unmetered or metered offering. In case of metered bandwidth the monthly included outbound (TX) traffic in GiB (GibiByte) MUST be provided. If no traffic is included in the monthly costs, this value MUST be set to 0. If the hoster meters in+outbound the hoster provided value must be divided by two. This is an integer value.
On a server with multiple Tor instances the total available monthly traffic of the server MUST be divided by the number of Tor relay instances running on it.
length: < 10 characters
valid characters: [unmetrd0-9]
example values:
unmetered
0
25600
Non-persistent memory (RAM) available on this server - measured in MB (Mebibytes). This is the output of free -m on most Unix-based systems.
On a server with multiple Tor instances the memory size MUST be divided by the number of Tor relay instances. This is an integer value.
length: < 10 characters
valid characters: [0-9]
example:
4096
Only relevant for relays running on bare metal. String without spaces describing the used CPU model.
example:
intel-i5-8400
States the underlying virtualization technology used on which the OS is running. Use “baremetal” for bare-metal servers (not virtualized).
length: < 15 characters
valid characters: [a-z-]
possible values:
kvm
qemu
bochs
xen
vmware
virtualbox
hyper-v
lxc
bhyve
openvz
parallels
vmm #https://man.openbsd.org/vmm
zvm
URL pointing to a website that contains donation information to support this Tor relay. This MUST be an HTTPS URL.
length: < 254 characters
example:
https://torservers.net/donate.html
Bitcoin or OpenAlias address where people can send donations to support the operation of this Tor relay.
length: < 100 characters
valid characters: [A-Za-z0-9]
Zcash address where people can send donations to support the operation of this Tor relay.
length: < 96 characters
valid characters: [A-Za-z0-9]
Monero or OpenAlias address where people can send donations to support the operation of this Tor relay.
length: < 100 characters
Single character stating whether the OfflineMasterKey feature is enabled (“y”) on this Tor instance or not (“n”).
length: 1 character
valid characters: [yn]
Integer stating the signing key renewal interval in days.
length: < 6 characters
valid characters: [0-9]
Single character stating whether this instance runs with Sandbox enabled (“y”) or not (“n”).
length: 1 character
valid characters: [yn]
String stating which OS distribution and version is used. Distribution and version is separated by a “/” sign.
On platforms where the file /etc/os-release is available os is created by taking the ID and VERSION_ID values. The version identifier is optional and may be omitted.
The string is case-insensitive.
length: < 21 characters
valid characters: [A-Za-z0-9/.]
examples:
OpenBSD/7.9
FreeBSD/17
ubuntu/26.04
debian/13
arch
String stating which tls library is used by the tor daemon.
length: < 15 characters
valid characters: [a-z]
example values:
openssl
libressl
Character stating whether AES-NI is available and used (“y”) or not available/not used (“n”).
length: 1 character
valid characters: [yn]
Single character stating whether automatic (unattended) updates are enabled (“y”) or not (“n”).
length: 1 character
valid characters: [yn]
States what configuration management system is used. Set to “manual” for no configuration management.
example values
ansible
chef
puppet
salt
length: < 16 characters
valid characters: [a-z]
This field is only relevant for exit relays, it is ignored on relays that do not allow exiting.
String describing the location of the used DNS resolver in relation to the exit relay.
Multiple options may apply and MUST be separated using a comma. The order is relevant, the primary resolver MUST appear first followed by fallback resolvers.
example values:
local
sameas
remote
local,sameas
valid characters: [a-z,]
This field is only relevant for exit relays, it is ignored on relays that do not allow exiting.
Character stating whether this exit relay is using a resolver that is performing DNS QNAME minimization (“y”) or not (“n”). QNAME minimization is defined in RFC7816.
length: 1 character
valid characters: [yn]
This field is only relevant for exit relays, it is ignored on relays that do not allow exiting.
Character stating whether this exit relay is using a resolver that is performing DNSSEC validation (“y”) or not (“n”).
length: 1 character
valid characters: [yn]
This field is only relevant for exit relays, it is ignored on relays that do not allow exiting.
Character stating whether this exit relay is using a resolver that is running the DNS root zone on loopback (“y”) to avoid latency and information disclosure to DNS root servers or not (“n”). This is defined in RFC7706.
length: 1 character
valid characters: [yn]
This field is mandatory.
Version of the ContactInfo Information Sharing Specification (this document) used to generate the ContactInfo string.
format: integer counter
valid characters: [0-9]
length: <4 digits
example values:
2
3
The machine readable information could be used by spammers and to target relay operators. The amount of spam observed has been limited. Operators concerned about spam should create a dedicated email address for the purpose of using it in the ContactInfo string. This email address can be rotated should there be any unacceptable amount of spam.
Attackers could use the additional information provided in these fields to specifically target only vulnerable systems. Operators concerned about sharing configuration information should omit this type of information, but can share other information.
The ContactInfo field size could potentially grow because of this specification. This is mitigated by directory data compression and diffs available since Tor version 0.3.1.
According to the manual there is no explicit ContactInfo size limit but there is a descriptor size limit. The max. descriptor size is 20000 bytes. The family size (number of listed fingerprints) and exit policy are two other relevant inputs.
The HTTPS endpoints located in field values MUST use certificates from a well known trusted certificate authority (for example Let’s Encrypt).