/usr/share/doc/onionbalance/html/design.html is in onionbalance 0.1.6-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Design Document — OnionBalance 0.1.6 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '0.1.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="top" title="OnionBalance 0.1.6 documentation" href="index.html" />
<link rel="next" title="Contributors" href="contributors.html" />
<link rel="prev" title="Use Cases" href="use-cases.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head>
<body role="document">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="design-document">
<h1>Design Document<a class="headerlink" href="#design-document" title="Permalink to this headline">¶</a></h1>
<p>This tool is designed to allow requests to Tor onion service to be
directed to multiple back-end Tor instances, thereby increasing
availability and reliability. The design involves collating the set of
introduction points created by one or more independent Tor onion service
instances into a single ‘master’ descriptor.</p>
<div class="section" id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>This tool is designed to allow requests to Tor onion service to be
directed to multiple back-end Tor instances, thereby increasing
availability and reliability. The design involves collating the set of
introduction points created by one or more independent Tor onion service
instances into a single ‘master’ onion service descriptor.</p>
<p>The master descriptor is signed by the onion service permanent key and
published to the HSDir system as normal.</p>
<p>Clients who wish to access the onion service would then retrieve the
<em>master</em> service descriptor and try to connect to introduction points
from the descriptor in a random order. If a client successfully
establishes an introduction circuit, they can begin communicating with
one of the onion services instances with the normal onion service
protocol defined in rend-spec.txt</p>
<dl class="docutils">
<dt>Instance</dt>
<dd>A load-balancing node running an individual onion service.</dd>
<dt>Introduction Point</dt>
<dd>A Tor relay chosen by an onion service instance as a medium-term
<em>meeting-place</em> for initial client connections.</dd>
<dt>Master Descriptor</dt>
<dd>An onion service descriptor published with the desired onion address
containing introduction points for each instance.</dd>
<dt>Management Server</dt>
<dd>Server running OnionBalance which collates introduction points and
publishes a master descriptor.</dd>
<dt>Metadata Channel</dt>
<dd>A direct connection from an instance to a management server which can
be used for instance descriptor upload and transfer of other data.</dd>
</dl>
</div>
<div class="section" id="retrieving-introduction-point-data">
<h2>Retrieving Introduction Point Data<a class="headerlink" href="#retrieving-introduction-point-data" title="Permalink to this headline">¶</a></h2>
<p>The core functionality of the OnionBalance service is the collation of
introduction point data from multiple onion service instances by the
management server.</p>
<div class="section" id="basic-mode">
<h3>Basic Mode<a class="headerlink" href="#basic-mode" title="Permalink to this headline">¶</a></h3>
<p>In the ‘Basic mode` of operation, the introduction point information is
transferred from the onion service instances to the management server
via the HSDir system. Each instance runs an onion service with an
instance specific permanent key. The instance publishes a descriptor to
the DHT at regularly intervals or when its introduction point set
changes.</p>
<p>On initial startup the management server will load the previously
published master descriptor from the DHT if it exists. The master
descriptor is used to prepopulate the introduction point set. The
management server regularly polls the HSDir system for a descriptor for
each of its instances. Currently polling occurs every 10 minutes. This
polling period can be tuned for hidden services with shorter or longer
lasting introduction points.</p>
<p>When the management server receives a new descriptor from the HSDir
system, it should before a number of checks to ensure that it is valid:</p>
<ul class="simple">
<li>Confirm that the descriptor has a valid signature and that the public
key matches the instance that was requested.</li>
<li>Confirm that the descriptor timestamp is equal or newer than the
previously received descriptor for that hidden service instance. This
reduces the ability of a HSDir to replay older descriptors for an
instance which may contain expired introduction points.</li>
<li>Confirm that the descriptor timestamp is not more than 4 hours in the
past. An older descriptor indicates that the instance may no longer
be online and publishing descriptors. The instance should not be
included in the master descriptor.</li>
</ul>
<p>It should be possible for two or more independent management servers to
publish descriptors for a single onion service. The servers would
publish independent descriptors which will replace each other on the
HSDir system.. Any difference in introduction point selection between
descriptors should not impact the end user.</p>
<div class="section" id="limitations">
<h4>Limitations<a class="headerlink" href="#limitations" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>A malicious HSDir could replay old instance descriptors in an attempt
to include expired introduction points in the master descriptor.
When an attacker does not control all of the responsible HSDirs this
attack can be mitigated by not accepting descriptors with a timestamp
older than the most recently retrieved descriptor.</li>
<li>The management server may also retrieve an old instance descriptor as
a result of churn in the DHT. The management server may attempt to
fetch the instance descriptor from a different set of HSDirs than the
instance published to.</li>
<li>An onion service instance may rapidly rotate its introduction point
circuits when subjected to a Denial of Service attack. An
introduction point circuit is closed by the onion service when it has
received <code class="docutils literal"><span class="pre">max_introductions</span></code> for that circuit. During DoS this
circuit rotating may occur faster than the management server polls
the HSDir system for new descriptors. As a result clients may
retrieve master descriptors which contain no currently valid
introduction points.</li>
<li>It is trivial for a HSDir to determine that a onion service is using
OnionBalance when in Basic mode. OnionBalance will try poll for
instance descriptors on a regular basis. A HSDir which connects to
onion services published to it would find that a backend instance is
serving the same content as the master service. This allows a HSDir
to trivially determine the onion addresses for a service’s backend
instances.</li>
</ul>
<p>Basic mode allows for scaling across multiple onion service
instances with no additional software or Tor modifications necessary
on the onion service instance. Basic mode does not hide that a
service is using OnionBalance. It also does not significantly
protect a service from introduction point denial of service or
actively malicious HSDirs.</p>
</div>
</div>
<div class="section" id="complex-mode">
<h3>Complex Mode<a class="headerlink" href="#complex-mode" title="Permalink to this headline">¶</a></h3>
<p>In Complex mode, introduction point information is uploaded directly from
each instance to the management server via an onion service. The onion
service instance does not publishing its onion service descriptor to the
HSDir system.</p>
<p>A descriptor is uploaded from an instance to its management servers
each time Tor generates a new onion service descriptor. A simple daemon
running on the onion service instance listens for the event emitted on
the Tor control port when a onion service descriptor is generated. The
daemon should retrieve the descriptor from the service’s local
descriptor cache and upload it to one or more management servers
configured for that onion service. The protocol for the metadata channel
is not yet defined.</p>
<p>The metadata channel should authorize connecting instance clients using
<code class="docutils literal"><span class="pre">basic</span></code> or <code class="docutils literal"><span class="pre">stealth</span></code> authorization.</p>
<p>Multiple management servers for the same onion service may communicate
with each other via a hidden service channel. This extra channel can be
used to signal when any of the management servers becomes unavailable. A
slave management server may begin publishing service descriptors if its
master management server is no longer available.</p>
<p>Complex mode requires additional software to be run on the service
instances. It also requires more complicated communication via a
metadata channel. In practice, this metadata channel may be less
reliable than the HSDir system.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The management server communication channel is not implemented yet. The
Complex Mode design may be revised significantly before implementation.</p>
</div>
<p>Complex mode minimizes the information transmitted via the HSDir
system and may make it more difficult for a HSDir to determine that
a service is using OnionBalance. It also makes it more difficult for
an active malicious HSDir to carry out descriptor replay attacks or
otherwise interfere with the transfer of introduction point
information. The management server is notified about new
introduction points shortly after they are created which will result
in more recent descriptor data during very high load or
denial-of-service situations.</p>
</div>
</div>
<div class="section" id="choice-of-introduction-points">
<h2>Choice of Introduction Points<a class="headerlink" href="#choice-of-introduction-points" title="Permalink to this headline">¶</a></h2>
<p>Tor onion service descriptors can include a maximum of 10 introduction
points. OnionBalance should select introduction points so as to
uniformly distribute load across the available backend instances.</p>
<p>Onionbalance will upload multiple distinct descriptors if you have configured
more than 10 instances.</p>
<ul class="simple">
<li><strong>1 instance</strong> - 3 IPs</li>
<li><strong>2 instance</strong> - 6 IPs (3 IPs from each instance)</li>
<li><strong>3 instance</strong> - 9 IPs (3 IPs from each instance)</li>
<li><strong>4 instance</strong> - 10 IPs (3 IPs from one instance, 2 from each other
instance)</li>
<li><strong>5 instance</strong> - 10 IPs (2 IPs from each instance)</li>
<li><strong>6-10 instances</strong> - 10 IPs (selection from all instances)</li>
<li><strong>11 or more instances</strong> - 10 IPs (distinct descriptors - selection from all instances)</li>
</ul>
<p>If running in Complex mode, introduction points can be selected so as to
obscure that a service is using OnionBalance. Always attempting to
choose 3 introduction points per descriptor may make it more difficult
for a passive observer to confirm that a service is running
OnionBalance. However behavioral characteristics such as the rate of
introduction point rotation may still allow a passive observer to
distinguish an OnionBalance service from a standard Tor onion service.
Selecting a smaller set of introduction points may impact on performance
or reliability of the service.</p>
<ul class="simple">
<li><strong>1 instance</strong> - 3 IPs</li>
<li><strong>2 instances</strong> - 3 IPs (2 IPs from one instance, 1 IP from the other
instance)</li>
<li><strong>3 instances</strong> - 3 IPs (1 IP from each instance)</li>
<li><strong>more than 3 instances</strong> - Select the maximum set of introduction
points as outlined previously.</li>
</ul>
<p>It may be advantageous to select introduction points in a non-random
manner. The longest-lived introduction points published by a backend
instance are likely to be stable. Conversely selecting more recently
created introduction points may more evenly distribute client
introductions across an instances introduction point circuits. Further
investigation of these options should indicate if there is significant
advantages to any of these approaches.</p>
</div>
<div class="section" id="generation-and-publication-of-master-descriptor">
<h2>Generation and Publication of Master Descriptor<a class="headerlink" href="#generation-and-publication-of-master-descriptor" title="Permalink to this headline">¶</a></h2>
<p>The management server should generate a onion service descriptor
containing the selected introduction points. This master descriptor is
then signed by the actual onion service permanent key. The signed master
descriptor should be published to the responsible HSDirs as normal.</p>
<p>Clients who wish to access the onion service would then retrieve the
‘master’ service descriptor and begin connect to introduction points at
random from the introduction point list. After successful introduction
the client will have created an onion service circuit to one of the
available onion services instances and can then begin communicating as
normally along that circuit.</p>
</div>
<div class="section" id="next-generation-onion-services-prop-224-compatibility">
<h2>Next-Generation Onion Services (Prop 224) Compatibility<a class="headerlink" href="#next-generation-onion-services-prop-224-compatibility" title="Permalink to this headline">¶</a></h2>
<p>In the next-generation onion service proposal (Prop224), introduction
point keys will no longer be independent of the instance/descriptor
permanent key. The proposal specifies that each introduction point
authentication key cross-certifies the descriptor’s blinded public key.
Each instance must know the master descriptor blinded public key during
descriptor generation.</p>
<p>One solution is to operate in the Complex mode described previously.
Each instance is provided with the descriptor signing key derived from
the same master identity key. Each introduction point authentication key
will then cross-certify the same blinded public key. The generated
service descriptors are not uploaded to the HSDir system. Instead the
descriptors are passed to the management server where introduction
points are selected and a master descriptor is published.</p>
<p>Alternatively a Tor control port command could be implemented to allow a
controller to request a onion service descriptor which has each
introduction point authentication key cross-certify a blinded public key
provided in the control port command. This would remove the need to
provide any master service private keys to backend instances.</p>
<p>The descriptor signing keys specified in Prop224 are valid for a limited
period of time. As a result the compromise of a descriptor signing key
does not lead to permanent compromise of the onion service</p>
</div>
<div class="section" id="implementation">
<h2>Implementation<a class="headerlink" href="#implementation" title="Permalink to this headline">¶</a></h2>
<p><strong>TODO</strong></p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="index.html">OnionBalance</a></h1>
<p class="blurb">Load balancing and redundancy for Tor hidden services.</p>
<h3>Navigation</h3>
<ul>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="getting-started.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="running-onionbalance.html">Running OnionBalance</a></li>
<li class="toctree-l1"><a class="reference internal" href="use-cases.html">Use Cases</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Design Document</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="#retrieving-introduction-point-data">Retrieving Introduction Point Data</a></li>
<li class="toctree-l2"><a class="reference internal" href="#choice-of-introduction-points">Choice of Introduction Points</a></li>
<li class="toctree-l2"><a class="reference internal" href="#generation-and-publication-of-master-descriptor">Generation and Publication of Master Descriptor</a></li>
<li class="toctree-l2"><a class="reference internal" href="#next-generation-onion-services-prop-224-compatibility">Next-Generation Onion Services (Prop 224) Compatibility</a></li>
<li class="toctree-l2"><a class="reference internal" href="#implementation">Implementation</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="contributors.html">Contributors</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Change Log</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="use-cases.html" title="previous chapter">Use Cases</a></li>
<li>Next: <a href="contributors.html" title="next chapter">Contributors</a></li>
</ul></li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.4.9</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
|
<a href="_sources/design.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>
|