#1761 closed defect (fixed)

Insufficient documentation about how to administer the convergence secret.

Reported by: nejucomo Owned by: warner
Priority: normal Milestone: 1.10.0
Component: documentation Version: 1.9.1
Keywords: docs convergence usability easy reviewed Cc: clashthebunny@…
Launchpad Bug:

Description

A user in IRC just asked what the convergence secret was. I explained its purpose, and they said they already knew that from reading the docs.

What the did not know was "how to use it". The docs should be very clear by saying something like:

To enable deduplication between different clients, securely copy
the convergence secret file from one client to all the others.

For example, if you are on host A and have an account on host B
and you have scp installed, run:

  scp ~/.tahoe/private/convergence my_other_account@B:.tahoe/private/convergence

Attachments (1)

convergence-secret.rst (2.5 KB) - added by marlowe at 2013-03-18T06:22:58Z.

Download all attachments as: .zip

Change History (23)

comment:1 Changed at 2013-02-09T02:34:23Z by davidsarah

  • Component changed from unknown to documentation
  • Keywords easy added
  • Milestone changed from undecided to 1.10.0
  • Status changed from new to assigned

comment:2 follow-up: Changed at 2013-02-09T02:50:02Z by gdt

Also, it would be good to explain the impact of changing the convergence secret on a node which has stored some data. I believe that changing it does not impair retrieval at all, but smiply moves that node to a new deduplication domain. But I'm not sure, and probably others have the same question.

comment:3 in reply to: ↑ 2 Changed at 2013-02-10T00:16:08Z by davidsarah

Replying to gdt:

Also, it would be good to explain the impact of changing the convergence secret on a node which has stored some data.

+1

I believe that changing it does not impair retrieval at all, but simply moves that node to a new deduplication domain.

That's correct (for new uploads).

comment:4 Changed at 2013-03-14T15:50:01Z by ClashTheBunny

I submit this:

Convergence Secret

comment:5 Changed at 2013-03-14T15:51:17Z by ClashTheBunny

  • Cc clashthebunny@… added

comment:6 follow-up: Changed at 2013-03-14T17:29:48Z by zooko

  • Owner changed from davidsarah to someone
  • Status changed from assigned to new

ClashTheBunny: Great! Thank you. I would prefer if the warning about why the convergence secret matters also referred to the "Learn-The-Remaining-Information" attack and not only to the "Confirm-The-File" attack. (See https://tahoe-lafs.org/hacktahoelafs/drew_perttula.html .)

We have an idea for how to manage documentation, which is that we put docs into the source tree in .rst form, and then in addition we make those docs browseable on the web. So a reasonable task for this ticket now would be for someone to convert Convergence Secret into .rst form, add it into the "docs/" subdirectory of the source tree, and the put links to it within the source browser from the Doc page. Make sense?

To recap, there are two things that I request somebody do before we close this ticket:

  1. edit Convergence Secret to warn that even if the file is unique to you, such as a statement from your bank, then the "Learn-The-Remaining-Information" attack could be used to reveal your confidential information to an attacker
  1. convert the text from trac wiki markup format from Convergence Secret to .rst format, put it in a file in git/docs/ and open a pull request on github.

comment:7 in reply to: ↑ 6 Changed at 2013-03-14T19:06:51Z by ClashTheBunny

  • Owner changed from someone to ClashTheBunny

Replying to zooko:>

  1. edit Convergence Secret to warn that even if the file is unique to you, such as a statement from your bank, then the "Learn-The-Remaining-Information" attack could be used to reveal your confidential information to an attacker

That link is what it already referenced, but I'll explain more as to what that situation involves in the text instead of just the Confirm-The-File attack. I actually hadn't processed fully what that meant until you made this comment.

  1. convert the text from trac wiki markup format from Convergence Secret to .rst format, put it in a file in git/docs/ and open a pull request on github.

I'll see what I can do. .rst is foggy, but I think it's pretty easy. I'll put it as a sub bullet under configuration on the "Doc" page.

comment:8 Changed at 2013-03-15T14:26:16Z by marlowe

I can help with this, if you need it.

comment:9 Changed at 2013-03-15T14:29:00Z by ClashTheBunny

  • Owner changed from ClashTheBunny to marlowe

Take it away! Thanks Marlowe!

comment:10 Changed at 2013-03-16T01:07:10Z by marlowe

  • Keywords review-needed added

Added convergence-secret.rst. Can someone please review this before I submit a pull request?

comment:11 Changed at 2013-03-18T04:37:24Z by davidsarah

I don't see an attachment.

Changed at 2013-03-18T06:22:58Z by marlowe

comment:12 Changed at 2013-03-18T08:20:36Z by ClashTheBunny

The first thing that David-Sarah wanted is still not updated. I'm updating the wiki page with the contents of convergence-secret.rst so that there are not two versions that need updating. That's version 3 of the wiki. Version 4 is in rst AND includes a paragraph explaining the first point that David-Sarah had mentioned.

comment:13 Changed at 2013-03-19T02:10:35Z by davidsarah

That seems ok as far as it goes, modulo Zooko's point in comment:6 (I think you meant Zooko instead of me). However there should be a link from the existing section on the convergence secret in configuration.rst, and maybe that section should just refer to convergence_secret.rst rather than duplicating information.

comment:14 Changed at 2013-04-04T16:47:01Z by zooko

  • Owner changed from marlowe to zooko
  • Status changed from new to assigned

comment:15 Changed at 2013-04-09T06:32:33Z by zooko

  • Owner changed from zooko to somebody
  • Status changed from assigned to new

I ended up rewriting part of it. Please review: https://github.com/tahoe-lafs/tahoe-lafs/pull/35

comment:16 follow-up: Changed at 2013-04-09T06:44:37Z by mk.fg

I propose that a following line should be added at the bottom of zooko's version of the doc:

Node restart is required in order for the new convergence secret to be used.

Reasoning is that sometimes it might be tempting to change convergence secret on-the-fly - for example, to prevent deduplicatiion between large sequential upload jobs, so that storage indexes of the former one can later be enumerated (e.g. with deep-manifest) and manually cleaned-up without having to worry about whether these indexes can be deduplicated with the next uploads.

Last edited at 2013-04-09T06:45:46Z by mk.fg (previous) (diff)

comment:17 in reply to: ↑ 16 Changed at 2013-04-09T06:49:28Z by zooko

  • Owner changed from somebody to mk.fg

Thanks! Good catch.

Yes, I think of convergence secret as actually being more fine-grained than the gateway. See #1419 and #1368.

Here's a new version of my doc patch. I also changed the word "node" to "client" in this doc in this revision.

https://github.com/zooko/tahoe-lafs/commit/6b5948c51a8be1cdadbb3bda907315bf3d96ede8

Please review!

comment:18 Changed at 2013-04-09T08:47:12Z by ClashTheBunny

+1

This looks correct and clear to me. I would say this is ready to go.

comment:19 Changed at 2013-04-09T12:07:44Z by zooko

  • Keywords reviewed added; review-needed removed
  • Owner changed from mk.fg to warner

comment:20 follow-up: Changed at 2013-04-09T18:04:13Z by warner

  • Resolution set to fixed
  • Status changed from new to closed

Looks good, landed in [643eb4f372b70d0e905858100e12e5f9a57cd873]

The only suggestion I'd make would be to eschew the unicode emdash in favor of a plain ASCII hyphen. "Be conservative in what you transmit". But we can address that later.

Version 0, edited at 2013-04-09T18:04:13Z by warner (next)

comment:21 in reply to: ↑ 20 Changed at 2013-04-09T18:59:21Z by zooko

Replying to warner:

Looks good, landed in 643eb4f372b70d0e

The only suggestion I'd make would be to eschew the unicode emdash in favor of a plain ASCII hyphen. "Be conservative in what you transmit". But we can address that later.

I don't object to changing it to a hyphen.

comment:22 Changed at 2013-04-09T19:24:38Z by warner

Ok, thanks, I'll ascii-ify the emdashes.

Note: See TracTickets for help on using tickets.