from Sebastian: 235-kill-named-flag.txt
[torspec.git] / proposals / 190-shared-secret-bridge-authorization.txt
1 Filename: 190-shared-secret-bridge-authorization.txt
2 Title: Bridge Client Authorization Based on a Shared Secret
3 Author: George Kadianakis
4 Created: 04 Nov 2011
5 Status: Needs-Revision
6
7 1. Overview
8
9    Proposals 187 and 189 introduced AUTHORIZE and AUTHORIZED cells.
10    Their purpose is to make bridge relays scanning-resistant against
11    censoring adversaries capable of probing hosts to observe whether
12    they speak the Tor protocol.
13
14    This proposal specifies a bridge client authorization scheme based
15    on a shared secret between the bridge user and bridge operator.
16
17 2. Motivation
18
19    A bridge client authorization scheme should only allow clients who
20    show knowledge of a shared secret to talk Tor to the bridge.
21
22 3. Shared-secret-based authorization
23
24 3.1. Where do shared secrets come from?
25
26    A shared secret is a piece of data known only to the bridge
27    operator and the bridge client.
28
29    It's meant to be automatically generated by the bridge
30    implementation to avoid issues with insecure and weak passwords.
31
32    Bridge implementations SHOULD create shared secrets by generating
33    random data using a strong RNG or PRNG.
34
35 3.2. AUTHORIZE cell format
36
37    In shared-secret-based authorization, the MethodFields field of the
38    AUTHORIZE cell becomes:
39
40        'shared_secret'               [10 octets]
41
42    where:
43
44    'shared_secret', is the shared secret between the bridge operator
45                     and the bridge client.
46
47 3.3. Cell parsing
48
49    Bridge implementations MUST reject any AUTHORIZE cells whose
50    'shared_secret' field does not match the shared secret negotiated
51    between the bridge operator and authorized bridge clients.
52
53 4. Tor implementation
54
55 4.1. Bridge side
56
57    Tor bridge implementations MUST create the bridge shared secret by
58    generating 10 octets of random data using a strong RNG or PRNG.
59
60    Tor bridge implementations MUST store the shared secret in
61    'DataDirectory/keys/bridge_auth_ss_key' in hexadecimal encoding.
62
63    Tor bridge implementations MUST support the boolean
64    'BridgeRequireClientSharedSecretAuthorization' configuration file
65    option which enables bridge client authorization based on a shared
66    secret.
67
68    If 'BridgeRequireClientSharedSecretAuthorization' is set, bridge
69    implementations MUST generate a new shared secret, if
70    'DataDirectory/keys/bridge_auth_ss_key' does not already exist.
71
72 4.2. Client side
73
74    Tor client implementations must extend their Bridge line format to
75    support bridge shared secrets. The new format is:
76      Bridge [<method>] <address[:port]> [["keyid="]<id-fingerprint>] ["shared_secret="<shared_secret>]
77
78    where <shared_secret> is the bridge shared secret in hexadecimal
79    encoding.
80
81    Tor clients who use bridges with shared-secret-based client
82    authorization must specify the bridge's shared secret as in:
83      Bridge 12.34.56.78 shared_secret=934caff420aa7852b855
84
85 5. Discussion
86
87 5.1. What should actually happen when a bridge rejects an AUTHORIZE
88      cell?
89
90    When a bridge detects a badly formed or malicious AUTHORIZE cell,
91    it should assume that the other side is an adversary scanning for
92    bridges. The bridge should then act accordingly to avoid detection.
93
94    This proposal does not try to specify how a bridge can avoid
95    detection by an adversary.
96
97 6. Acknowledgements
98
99    Thanks to Nick Mathewson and Robert Ransom for the help and
100    suggestions while writing this proposal.
101