From: Daira Hopwood Date: Thu, 11 Jun 2015 20:33:09 +0000 (+0100) Subject: Finish user-interface.rst. fixes ticket:2443 X-Git-Tag: allmydata-tahoe-1.10.1~3 X-Git-Url: https://git.rkrishnan.org/(%5B%5E?a=commitdiff_plain;h=1105278589f15344ab9bf97e44c594451c276684;p=tahoe-lafs%2Ftahoe-lafs.git Finish user-interface.rst. fixes ticket:2443 Signed-off-by: Daira Hopwood --- diff --git a/docs/proposed/magic-folder/user-interface-design.rst b/docs/proposed/magic-folder/user-interface-design.rst index 6323dbe8..ce428b87 100644 --- a/docs/proposed/magic-folder/user-interface-design.rst +++ b/docs/proposed/magic-folder/user-interface-design.rst @@ -4,12 +4,12 @@ Magic Folder user interface design Scope ----- -In this Objective we will write the design document for how users can conveniently -and securely indicate which folders on some devices should be magically linked to -which folders on other devices. +In this Objective we will design a user interface to allow users to conveniently +and securely indicate which folders on some devices should be "magically" linked +to which folders on other devices. This is a critical usability and security issue for which there is no known perfect -solution, but which will hopefully be amenable to a "good enough" trade-off solution. +solution, but which we believe is amenable to a "good enough" trade-off solution. This document explains the design and justifies its trade-offs in terms of security, usability, and time-to-market. @@ -17,3 +17,191 @@ Tickets on the Tahoe-LAFS trac with the `otf-magic-folder-objective6`_ keyword are within the scope of the user interface design. .. _otf-magic-folder-objective6: https://tahoe-lafs.org/trac/tahoe-lafs/query?status=!closed&keywords=~otf-magic-folder-objective6 + +Glossary +'''''''' + +Object: a file or directory + +DMD: distributed mutable directory + +Folder: an abstract directory that is synchronized between clients. +(A folder is not the same as the directory corresponding to it on +any particular client, nor is it the same as a DMD.) + +Collective: the set of clients subscribed to a given Magic Folder. + +Diminishing: the process of deriving, from an existing capability, +another capability that gives less authority (for example, deriving a +read cap from a read/write cap). + + +Design Constraints +------------------ + +The design of the Tahoe-side representation of a Magic Folder, and the polling +mechanism that the Magic Folder clients will use to detect remote changes was +discussed in ``_, and we will not revisit that here. +The assumption made by that design was that each client would be configured with +the following information: + +* a write cap to its own *client DMD*. +* a read cap to a *collective directory*. + +The collective directory contains links to each client DMD named by the +corresponding client's nickname. + +This design was chosen to allow straightforward addition of clients without +requiring each existing client to change its configuration. + +Note that each client in a Magic Folder collective has the authority to add, +modify or delete any object within the Magic Folder. It is also able to control +to some extent whether its writes will be treated by another client as overwrites +or as conflicts. However, there is still a reliability benefit to preventing a +client from accidentally modifying another client's DMD, or from accidentally +modifying the collective directory in a way that would lose data. This motivates +ensuring that each client only has access to the caps above, rather than, say, +every client having a write cap to the collective directory. + +Another important design constraint is that we cannot violate the +`write coordination directive`_; that is, we cannot write to the same mutable +directory from multiple clients, even during the setup phase when adding a +client. + +.. _`write coordination directive`: ../../write_coordination.rst + +Within these constraints, for usability we want to minimize the number of steps +required to configure a Magic Folder collective. + + +Proposed Design +--------------- + +Three ``tahoe`` subcommands are added:: + + tahoe magic-folder create MAGIC: [MY_NICKNAME LOCAL_DIR] + + Create an empty Magic Folder. The MAGIC: local alias is set + to a write cap which can be used to refer to this Magic Folder + in future ``tahoe magic-folder invite`` commands. + + If MY_NICKNAME and LOCAL_DIR are given, the current client + immediately joins the newly created Magic Folder with that + nickname and local directory. + + + tahoe magic-folder invite MAGIC: THEIR_NICKNAME + + Print an "invitation" that can be used to invite another + client to join a Magic Folder, with the given nickname. + + The invitation must be sent to the user of the other client + over a secure channel (e.g. PGP email, OTR, or ssh). + + This command will normally be run by the same client that + created the Magic Folder. However, it may be run by a + different client if the ``MAGIC:`` alias is copied to + the ``private/aliases`` file of that other client, or if + ``MAGIC:`` is replaced by the write cap to which it points. + + + tahoe magic-folder join INVITATION LOCAL_DIR + + Accept an invitation created by ``tahoe magic-folder invite``. + The current client joins the specified Magic Folder, which will + appear in the local filesystem at the given directory. + + +There are no commands to remove a client or to revoke an +invitation, although those are possible features that could +be added in future. (When removing a client, it is necessary +to copy each file it added to some other client's DMD, if it +is the most recent version of that file.) + + +Implementation +'''''''''''''' + +For "``tahoe magic-folder create MAGIC: [MY_NICKNAME LOCAL_DIR]``" : + +1. Run "``tahoe create-alias MAGIC:``". +2. If ``MY_NICKNAME`` and ``LOCAL_DIR`` are given, do the equivalent of:: + + INVITATION=`tahoe invite-magic-folder MAGIC: MY_NICKNAME` + tahoe join-magic-folder INVITATION LOCAL_DIR + + +For "``tahoe magic-folder invite COLLECTIVE_WRITECAP NICKNAME``" : + +(``COLLECTIVE_WRITECAP`` can, as a special case, be an alias such as ``MAGIC:``.) + +1. Create an empty client DMD. Let its write URI be ``CLIENT_WRITECAP``. +2. Diminish ``CLIENT_WRITECAP`` to ``CLIENT_READCAP``, and + diminish ``COLLECTIVE_WRITECAP`` to ``COLLECTIVE_READCAP``. +3. Run "``tahoe ln CLIENT_READCAP COLLECTIVE_WRITECAP/NICKNAME``". +4. Print "``COLLECTIVE_READCAP|CLIENT_WRITECAP``" as the invitation, + accompanied by instructions on how to accept the invitation and + the need to send it over a secure channel. + + +For "``tahoe magic-folder join INVITATION LOCAL_DIR``" : + +1. Parse ``INVITATION`` as ``COLLECTIVE_READCAP|CLIENT_WRITECAP``. +2. Write ``CLIENT_WRITECAP`` to the file ``magic_folder_dircap`` + under the client's ``private`` directory. +3. Write ``COLLECTIVE_READCAP`` to the file ``collective_dircap`` + under the client's ``private`` directory. +4. Edit the client's ``tahoe.cfg`` to set + ``[magic_folder] enabled = True`` and + ``[magic_folder] local.directory = LOCAL_DIR``. + + +Discussion +---------- + +The proposed design has a minor violation of the +`Principle of Least Authority`_ in order to reduce the number +of steps needed. The invoker of "``tahoe magic-folder invite``" +creates the client DMD on behalf of the invited client, and +could retain its write cap (which is part of the invitation). + +.. _`Principle of Least Authority`: http://www.eros-os.org/papers/secnotsep.pdf + +A possible alternative design would be for the invited client +to create its own client DMD, and send it back to the inviter +to be linked into the collective directory. However this would +require another secure communication and another command +invocation per client. Given that, as mentioned earlier, each +client in a Magic Folder collective already has the authority +to add, modify or delete any object within the Magic Folder, +we considered the potential security/reliability improvement +here not to be worth the loss of usability. + +We also considered a design where each client had write access +to the collective directory. This would arguably be a more +serious violation of the Principle of Least Authority than the +one above (because all clients would have excess authority rather +than just the inviter). In any case, it was not clear how to make +such a design satisfy the `write coordination directive`_, +because the collective directory would have needed to be written +to by multiple clients. + +The reliance on a secure channel to send the invitation to its +intended recipient is not ideal, since it may involve additional +software such as clients for PGP, OTR, ssh etc. However, we believe +that this complexity is necessary rather than incidental, because +there must be some way to distinguish the intended recipient from +potential attackers who would try to become members of the Magic +Folder collective without authorization. By making use of existing +channels that have likely already been set up by security-conscious +users, we avoid reinventing the wheel or imposing substantial extra +implementation costs. + +The length of an invitation will be approximately the combined +length of a Tahoe-LAFS read cap and write cap. This is several +lines long, but still short enough to be cut-and-pasted successfully +if care is taken. Errors in copying the invitation can be detected +since Tahoe-LAFS cap URIs are self-authenticating. + +The implementation of the ``tahoe`` subcommands is straightforward +and raises no further difficult design issues.