Insufficient documentation about how to administer the convergence secret.

[nejucomo]

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

[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.

[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).

[ClashTheBunny]

I submit this:

​Convergence Secret

[zooko]

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

2. 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.

[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.

2. 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.

[marlowe]

I can help with this, if you need it.

[ClashTheBunny]

Take it away! Thanks Marlowe!

[marlowe]

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

[davidsarah]

I don't see an attachment.

[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.

[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.

[zooko]

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

[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.

[zooko]

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!

[ClashTheBunny]

+1

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

[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.

[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.

[warner]

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