source: trunk/docs/convergence-secret.rst

Last change on this file was 142185b, checked in by Brian Warner <warner@…>, at 2016-03-30T04:46:11Z

docs: add sphinx index.rst, improve headers

  • Property mode set to 100644
File size: 3.6 KB
1.. -*- coding: utf-8-with-signature -*-
4The Convergence Secret
7What Is It?
10The identifier of a file (also called the "capability" to a file) is derived
11from two pieces of information when the file is uploaded: the content of the
12file and the upload client's "convergence secret". By default, the
13convergence secret is randomly generated by the client when it first starts
14up, then stored in the client's base directory (<Tahoe's node
15dir>/private/convergence) and re-used after that. So the same file content
16uploaded from the same client will always have the same cap. Uploading the
17file from a different client with a different convergence secret would result
18in a different cap -- and in a second copy of the file's contents stored on
19the grid. If you want files you upload to converge (also known as
20"deduplicate") with files uploaded by someone else, just make sure you're
21using the same convergence secret when you upload files as them.
23The advantages of deduplication should be clear, but keep in mind that the
24convergence secret was created to protect confidentiality. There are two
25attacks that can be used against you by someone who knows the convergence
26secret you use.
28The first one is called the "Confirmation-of-a-File Attack". Someone who
29knows the convergence secret that you used when you uploaded a file, and who
30has a copy of that file themselves, can check whether you have a copy of that
31file. This is usually not a problem, but it could be if that file is, for
32example, a book or movie that is banned in your country.
34The second attack is more subtle. It is called the
35"Learn-the-Remaining-Information Attack". Suppose you've received a
36confidential document, such as a PDF from your bank which contains many pages
37of boilerplate text as well as containing your bank account number and
38balance. Someone who knows your convergence secret can generate a file with
39all of the boilerplate text (perhaps they would open an account with the same
40bank so they receive the same document with their account number and
41balance). Then they can try a "brute force search" to find your account
42number and your balance.
44The defense against these attacks is that only someone who knows the
45convergence secret that you used on each file can perform these attacks on
46that file.
48Both of these attacks and the defense are described in more detail in `Drew
49Perttula's Hack Tahoe-LAFS Hall Of Fame entry`_
51.. _`Drew Perttula's Hack Tahoe-LAFS Hall Of Fame entry`:
54What If I Change My Convergence Secret?
57All your old file capabilities will still work, but the new data that you
58upload will not be deduplicated with the old data. If you upload all of the
59same things to the grid, you will end up using twice the space until garbage
60collection kicks in (if it's enabled). Changing the convergence secret that a
61storage client uses for uploads can be though of as moving the client to a
62new "deduplication domain".
64How To Use It
67To enable deduplication between different clients, **securely** copy the
68convergence secret file from one client to all the others.
70For example, if you are on host A and have an account on host B and you have
71scp installed, run:
73  *scp ~/.tahoe/private/convergence
74  my_other_account@B:.tahoe/private/convergence*
76If you have two different clients on a single computer, say one for each
77disk, you would do:
79  *cp /tahoe1/private/convergence /tahoe2/private/convergence*
81After you change the convergence secret file, you must restart the client
82before it will stop using the old one and read the new one from the file.
Note: See TracBrowser for help on using the repository browser.