ContactInfo-Information-Sharing-Specification

KO | EN

gitlite — search

#hacktoberfest #ai #golang #go #deep-learning #linux #docker #nodejs #macos #java #awesome #kubernetes #vue #open-source

ContactInfo-Information-Sharing-Specification

(★ 10)

A specification for tor's ContactInfo field.

ContactInfo-Information-Sharing-Specification Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**Version 3**

# Overview

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.

# Example

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:
* the technical contact for this relay can be reached at tor@example.com
* the entity responsible for this relay has a website at https://example.com
* the proof file to verify the `url` can be fetched from https://example.com/.well-known/tor-relay/ed25519-family-id.txt
* this relay has an uplink bandwidth of 1000 Mbit/s
* this ContactInfo string implements version 3 of this specification

# Motivation

- increase information sharing among Tor relay operators
- improve the ability to contact relay operators
- increase trust in contact information
  - give operators a standardized way to authenticate some fields
  - detect relay operators impersonating other operators or entities that do not run relays
- collect additional (self-reported) relay metrics
  - for Tor relay operators 
  - for Tor developers
- provide metadata for Tor network graphs
- make hosting costs visible
- make it easier for current and future relay operators to find (rarely used) hosters
  - (indirectly) improve geo- and autonomous system diversity on the Tor network (more diverse is better)
  
## Design Goals

- make provided information machine readable
- allow for automatic verification (limited)
- do not require changes in Tor
- low entry barrier

# Defined Fields

The 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](https://gitweb.torproject.org/torspec.git/tree/proposals/285-utf-8.txt)).
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.

## Overview of defined fields

* **[email](#email)**
  * **[url](#url)**
  * **[proof](#proof)**
  * **[ciissversion](#ciissversion)** (mandatory)
  * [pgp](#pgp)
  * [abuse](#abuse)
  * [keybase](#keybase)
  * [twitter](#twitter)
  * [bluesky](#bluesky)
  * [mastodon](#mastodon)
  * [matrix](#matrix)
  * [signal](#signal)
  * [irc](#irc)
  * [xmpp](#xmpp)
  * [otr3](#otr3)
  * [hoster](#hoster)
  * [cost](#cost)
  * [uplinkbw](#uplinkbw)
  * [trafficacct](#trafficacct)
  * [memory](#memory)
  * [cpu](#cpu)
  * [virtualization](#virtualization)
  * [btc](#btc)
  * [zec](#zec)
  * [xmr](#xmr)
  * [donationurl](#donationurl)
  * [offlinemasterkey](#offlinemasterkey)
  * [signingkeylifetime](#signingkeylifetime)
  * [sandbox](#sandbox)
  * [os](#os)
  * [tls](#tls)
  * [aesni](#aesni)
  * [autoupdate](#autoupdate)
  * [confmgmt](#confmgmt)
  * [dnslocation](#dnslocation)
  * [dnsqname](#dnsqname)
  * [dnssec](#dnssec)
  * [dnslocalrootzone](#dnslocalrootzone)

## contact information

### email
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](https://tools.ietf.org/html/rfc5322#section-3.4.1) 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
```

### url
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:
* The `url` SHOULD be ignored if verification does not succeed.
* End users MUST be able to tell verified from unverified URLs.

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
```

### proof

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:

* uri-familyid-ed25519
* dns-familyid-ed25519

Tools performing proof checks SHOULD re-verify the proof at least every 6 months.

#### uri-familyid-ed25519

The "uri-familyid-ed25519" proof method uses the well-known "tor-relay" URI
[/.well-known/tor-relay/ed25519-family-id.txt](https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/proposals/326-tor-relay-well-known-uri-rfc8615.md?ref_type=heads&plain=0#well-knowntor-relayed25519-family-idtxt)
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](https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/proposals/326-tor-relay-well-known-uri-rfc8615.md).

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.

#### dns-familyid-ed25519

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!

### pgp
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
```

### abuse
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](https://tools.ietf.org/html/rfc5322#section-3.4.1) 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
```

### keybase
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
```

### twitter
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
```

### bluesky

The entity's bluesky username without the leading "@" and trailing ".bsky.social".

length: MUST be 1-50 characters long

example value:

```
torproject.org
```

### mastodon
URL pointing to the entity's mastodon profile (responsible organization/person).

length: < 254 characters

example value:
 
 ```
 https://mastodon.social/@nusenu
 ```
 
### matrix

[Matrix](https://matrix.org/) [user identifier](https://matrix.org/docs/spec/appendices#user-identifiers)
for the technical contact for this Tor relay.

example value:

```
@user:example.com
```

### signal

This field contains a [Signal username](https://support.signal.org/hc/en-us/articles/6712070553754-Phone-Number-Privacy-and-Usernames#username_req).

Signal usernames are case insensitive.

length: <40 characters

valid characters: [a-z0-9_.]

### irc

This field contains an IRC network/nickname. The nickname MUST be registered.

length: <100

example value:

```
irc.oftc.net/exampleusername
```

### xmpp
[XMPP](https://en.wikipedia.org/wiki/XMPP) handle for the technical contact of this Tor relay. The "@" sign SHOULD be replaced with "[]".

length: < 254 characters

example value:

```
user[]example.com
```

### otr3
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
```

## hoster information

### hoster
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:
- The domain MUST NOT include a protocol specifier (like "https://").
- The provided domain MUST NOT redirect to another (sub)domain
- If the hoster has multiple domains (using different TLDs) use the international version.
- The domain MUST NOT include trailing slashes "/".

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
```

### cost
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](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).

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
```

### uplinkbw
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
 ```

### trafficacct
States if this is an unmetered or metered offering. In case of metered bandwidth the monthly included outbound (TX) traffic in GiB ([GibiByte](https://en.wikipedia.org/wiki/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
```

### memory 
Non-persistent memory (RAM) available on this server - measured in MB ([Mebibytes](https://en.wikipedia.org/wiki/Mebibyte)). 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
```

### cpu

Only relevant for relays running on bare metal.
String without spaces describing the used CPU model.

example:

```
intel-i5-8400
```

### virtualization
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
```

## donation information

### donationurl
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
```

### btc
Bitcoin or [OpenAlias](https://openalias.org/) address where people can send donations to support the operation of this Tor relay.

length: < 100 characters

valid characters: [A-Za-z0-9]

### zec
Zcash address where people can send donations to support the operation of this Tor relay.

length: < 96 characters

valid characters: [A-Za-z0-9]

### xmr
Monero or [OpenAlias](https://openalias.org/) address where people can send donations to support the operation of this Tor relay.

length: < 100 characters

## Tor configuration

### offlinemasterkey
Single character stating whether the [OfflineMasterKey](https://www.torproject.org/docs/tor-manual.html.en#OfflineMasterKey) feature is enabled ("y") on this Tor instance or not ("n").

length: 1 character

valid characters: [yn]

### signingkeylifetime
Integer stating the [signing key renewal interval](https://www.torproject.org/docs/tor-manual.html.en#SigningKeyLifetime) in days.

length: < 6 characters

valid characters: [0-9]

### sandbox
Single character stating whether this instance runs with [Sandbox](https://www.torproject.org/docs/tor-manual.html.en#Sandbox) enabled ("y") or not ("n").

length: 1 character

valid characters: [yn]

## OS Information

### os
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](https://www.freedesktop.org/software/systemd/man/os-release.html) 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
```

### tls
String stating which tls library is used by the tor daemon.

length: < 15 characters

valid characters: [a-z]

example values:

```
openssl
libressl
```
		
### aesni
Character stating whether AES-NI is available and used ("y") or not available/not used ("n").
 
length: 1 character

valid characters: [yn]
 
### autoupdate
Single character stating whether automatic (unattended) updates are enabled ("y") or not ("n").

length: 1 character

valid characters: [yn]

### confmgmt
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]

## DNS Configuration (Exits only)

### dnslocation

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.

* **local** means the resolver is running on the same host as the Tor process.
* **sameas** means the resolver is running on the same autonomous system as the exit relay and queries to the resolver do not cross another AS before reaching the resolver.
* **remote** means the resolver is running on a system outside the exit relay's autonomous system

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,]

### dnsqname

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](https://datatracker.ietf.org/doc/rfc7816/).

length: 1 character

valid characters: [yn]

### dnssec

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]

### dnslocalrootzone

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](https://tools.ietf.org/html/rfc7706).

length: 1 character

valid characters: [yn]

## Specification Version Information

### ciissversion

This field is mandatory.

Version of the **C**ontact**I**nfo **I**nformation **S**haring **S**pecification (this document) used to generate the ContactInfo string.

format: integer counter

valid characters: [0-9]

length: <4 digits

example values:

```
2
3
```

# Considerations

- increases exposure of relay operators

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.

- more information makes targeted exploitation easier / more silent

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.

- increased descriptor size and directory traffic

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.

- ContactInfo size constraints

According to the [manual](https://www.torproject.org/docs/tor-manual.html.en#ContactInfo) there is no explicit 
ContactInfo size limit but there is a descriptor size limit. 
The [max. descriptor size](https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt#n364) is 20000 bytes. 
The family size (number of listed fingerprints) and exit policy are two other relevant inputs.

## HTTPS URLs and used certificate authority

The HTTPS endpoints located in field values MUST use certificates from a well known trusted certificate authority (for example [Let's Encrypt](https://letsencrypt.org/)).

ContactInfo-Information-Sharing-Specification

ContactInfo-Information-Sharing-Specification Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ContactInfo-Information-Sharing-Specification

ContactInfo-Information-Sharing-Specification Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README