1 Magic Folder user interface design
2 ==================================
7 In this Objective we will design a user interface to allow users to conveniently
8 and securely indicate which folders on some devices should be "magically" linked
9 to which folders on other devices.
11 This is a critical usability and security issue for which there is no known perfect
12 solution, but which we believe is amenable to a "good enough" trade-off solution.
13 This document explains the design and justifies its trade-offs in terms of security,
14 usability, and time-to-market.
16 Tickets on the Tahoe-LAFS trac with the `otf-magic-folder-objective6`_
17 keyword are within the scope of the user interface design.
19 .. _otf-magic-folder-objective6: https://tahoe-lafs.org/trac/tahoe-lafs/query?status=!closed&keywords=~otf-magic-folder-objective6
24 Object: a file or directory
26 DMD: distributed mutable directory
28 Folder: an abstract directory that is synchronized between clients.
29 (A folder is not the same as the directory corresponding to it on
30 any particular client, nor is it the same as a DMD.)
32 Collective: the set of clients subscribed to a given Magic Folder.
34 Diminishing: the process of deriving, from an existing capability,
35 another capability that gives less authority (for example, deriving a
36 read cap from a read/write cap).
42 The design of the Tahoe-side representation of a Magic Folder, and the polling
43 mechanism that the Magic Folder clients will use to detect remote changes was
44 discussed in `<remote-to-local-sync.rst>`_, and we will not revisit that here.
45 The assumption made by that design was that each client would be configured with
46 the following information:
48 * a write cap to its own *client DMD*.
49 * a read cap to a *collective directory*.
51 The collective directory contains links to each client DMD named by the
52 corresponding client's nickname.
54 This design was chosen to allow straightforward addition of clients without
55 requiring each existing client to change its configuration.
57 Note that each client in a Magic Folder collective has the authority to add,
58 modify or delete any object within the Magic Folder. It is also able to control
59 to some extent whether its writes will be treated by another client as overwrites
60 or as conflicts. However, there is still a reliability benefit to preventing a
61 client from accidentally modifying another client's DMD, or from accidentally
62 modifying the collective directory in a way that would lose data. This motivates
63 ensuring that each client only has access to the caps above, rather than, say,
64 every client having a write cap to the collective directory.
66 Another important design constraint is that we cannot violate the
67 `write coordination directive`_; that is, we cannot write to the same mutable
68 directory from multiple clients, even during the setup phase when adding a
71 .. _`write coordination directive`: ../../write_coordination.rst
73 Within these constraints, for usability we want to minimize the number of steps
74 required to configure a Magic Folder collective.
80 Three ``tahoe`` subcommands are added::
82 tahoe magic-folder create MAGIC: [MY_NICKNAME LOCAL_DIR]
84 Create an empty Magic Folder. The MAGIC: local alias is set
85 to a write cap which can be used to refer to this Magic Folder
86 in future ``tahoe magic-folder invite`` commands.
88 If MY_NICKNAME and LOCAL_DIR are given, the current client
89 immediately joins the newly created Magic Folder with that
90 nickname and local directory.
93 tahoe magic-folder invite MAGIC: THEIR_NICKNAME
95 Print an "invitation" that can be used to invite another
96 client to join a Magic Folder, with the given nickname.
98 The invitation must be sent to the user of the other client
99 over a secure channel (e.g. PGP email, OTR, or ssh).
101 This command will normally be run by the same client that
102 created the Magic Folder. However, it may be run by a
103 different client if the ``MAGIC:`` alias is copied to
104 the ``private/aliases`` file of that other client, or if
105 ``MAGIC:`` is replaced by the write cap to which it points.
108 tahoe magic-folder join INVITATION LOCAL_DIR
110 Accept an invitation created by ``tahoe magic-folder invite``.
111 The current client joins the specified Magic Folder, which will
112 appear in the local filesystem at the given directory.
115 There are no commands to remove a client or to revoke an
116 invitation, although those are possible features that could
117 be added in future. (When removing a client, it is necessary
118 to copy each file it added to some other client's DMD, if it
119 is the most recent version of that file.)
125 For "``tahoe magic-folder create MAGIC: [MY_NICKNAME LOCAL_DIR]``" :
127 1. Run "``tahoe create-alias MAGIC:``".
128 2. If ``MY_NICKNAME`` and ``LOCAL_DIR`` are given, do the equivalent of::
130 INVITATION=`tahoe invite-magic-folder MAGIC: MY_NICKNAME`
131 tahoe join-magic-folder INVITATION LOCAL_DIR
134 For "``tahoe magic-folder invite COLLECTIVE_WRITECAP NICKNAME``" :
136 (``COLLECTIVE_WRITECAP`` can, as a special case, be an alias such as ``MAGIC:``.)
138 1. Create an empty client DMD. Let its write URI be ``CLIENT_WRITECAP``.
139 2. Diminish ``CLIENT_WRITECAP`` to ``CLIENT_READCAP``, and
140 diminish ``COLLECTIVE_WRITECAP`` to ``COLLECTIVE_READCAP``.
141 3. Run "``tahoe ln CLIENT_READCAP COLLECTIVE_WRITECAP/NICKNAME``".
142 4. Print "``COLLECTIVE_READCAP|CLIENT_WRITECAP``" as the invitation,
143 accompanied by instructions on how to accept the invitation and
144 the need to send it over a secure channel.
147 For "``tahoe magic-folder join INVITATION LOCAL_DIR``" :
149 1. Parse ``INVITATION`` as ``COLLECTIVE_READCAP|CLIENT_WRITECAP``.
150 2. Write ``CLIENT_WRITECAP`` to the file ``magic_folder_dircap``
151 under the client's ``private`` directory.
152 3. Write ``COLLECTIVE_READCAP`` to the file ``collective_dircap``
153 under the client's ``private`` directory.
154 4. Edit the client's ``tahoe.cfg`` to set
155 ``[magic_folder] enabled = True`` and
156 ``[magic_folder] local.directory = LOCAL_DIR``.
162 The proposed design has a minor violation of the
163 `Principle of Least Authority`_ in order to reduce the number
164 of steps needed. The invoker of "``tahoe magic-folder invite``"
165 creates the client DMD on behalf of the invited client, and
166 could retain its write cap (which is part of the invitation).
168 .. _`Principle of Least Authority`: http://www.eros-os.org/papers/secnotsep.pdf
170 A possible alternative design would be for the invited client
171 to create its own client DMD, and send it back to the inviter
172 to be linked into the collective directory. However this would
173 require another secure communication and another command
174 invocation per client. Given that, as mentioned earlier, each
175 client in a Magic Folder collective already has the authority
176 to add, modify or delete any object within the Magic Folder,
177 we considered the potential security/reliability improvement
178 here not to be worth the loss of usability.
180 We also considered a design where each client had write access
181 to the collective directory. This would arguably be a more
182 serious violation of the Principle of Least Authority than the
183 one above (because all clients would have excess authority rather
184 than just the inviter). In any case, it was not clear how to make
185 such a design satisfy the `write coordination directive`_,
186 because the collective directory would have needed to be written
187 to by multiple clients.
189 The reliance on a secure channel to send the invitation to its
190 intended recipient is not ideal, since it may involve additional
191 software such as clients for PGP, OTR, ssh etc. However, we believe
192 that this complexity is necessary rather than incidental, because
193 there must be some way to distinguish the intended recipient from
194 potential attackers who would try to become members of the Magic
195 Folder collective without authorization. By making use of existing
196 channels that have likely already been set up by security-conscious
197 users, we avoid reinventing the wheel or imposing substantial extra
198 implementation costs.
200 The length of an invitation will be approximately the combined
201 length of a Tahoe-LAFS read cap and write cap. This is several
202 lines long, but still short enough to be cut-and-pasted successfully
203 if care is taken. Errors in copying the invitation can be detected
204 since Tahoe-LAFS cap URIs are self-authenticating.
206 The implementation of the ``tahoe`` subcommands is straightforward
207 and raises no further difficult design issues.