docs/convergence-secret.rst

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