docs/proposed/magic-folder/user-interface-design.rst

   1 Magic Folder user interface design
   2 ==================================
   3
   4 Scope
   5 -----
   6
   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.
  10
  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.
  15
  16 Tickets on the Tahoe-LAFS trac with the `otf-magic-folder-objective6`_
  17 keyword are within the scope of the user interface design.
  18
  19 .. _otf-magic-folder-objective6: https://tahoe-lafs.org/trac/tahoe-lafs/query?status=!closed&keywords=~otf-magic-folder-objective6
  20
  21 Glossary
  22 ''''''''
  23
  24 Object: a file or directory
  25
  26 DMD: distributed mutable directory
  27
  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.)
  31
  32 Collective: the set of clients subscribed to a given Magic Folder.
  33
  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).
  37
  38
  39 Design Constraints
  40 ------------------
  41
  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:
  47
  48 * a write cap to its own *client DMD*.
  49 * a read cap to a *collective directory*.
  50
  51 The collective directory contains links to each client DMD named by the
  52 corresponding client's nickname.
  53
  54 This design was chosen to allow straightforward addition of clients without
  55 requiring each existing client to change its configuration.
  56
  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.
  65
  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
  69 client.
  70
  71 .. _`write coordination directive`: ../../write_coordination.rst
  72
  73 Within these constraints, for usability we want to minimize the number of steps
  74 required to configure a Magic Folder collective.
  75
  76
  77 Proposed Design
  78 ---------------
  79
  80 Three ``tahoe`` subcommands are added::
  81
  82   tahoe magic-folder create MAGIC: [MY_NICKNAME LOCAL_DIR]
  83
  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.
  87
  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.
  91
  92
  93   tahoe magic-folder invite MAGIC: THEIR_NICKNAME
  94
  95     Print an "invitation" that can be used to invite another
  96     client to join a Magic Folder, with the given nickname.
  97
  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).
 100
 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.
 106
 107
 108   tahoe magic-folder join INVITATION LOCAL_DIR
 109
 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.
 113
 114
 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.)
 120
 121
 122 Implementation
 123 ''''''''''''''
 124
 125 For "``tahoe magic-folder create MAGIC: [MY_NICKNAME LOCAL_DIR]``" :
 126
 127 1. Run "``tahoe create-alias MAGIC:``".
 128 2. If ``MY_NICKNAME`` and ``LOCAL_DIR`` are given, do the equivalent of::
 129
 130      INVITATION=`tahoe invite-magic-folder MAGIC: MY_NICKNAME`
 131      tahoe join-magic-folder INVITATION LOCAL_DIR
 132
 133
 134 For "``tahoe magic-folder invite COLLECTIVE_WRITECAP NICKNAME``" :
 135
 136 (``COLLECTIVE_WRITECAP`` can, as a special case, be an alias such as ``MAGIC:``.)
 137
 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.
 145
 146
 147 For "``tahoe magic-folder join INVITATION LOCAL_DIR``" :
 148
 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``.
 157
 158
 159 Discussion
 160 ----------
 161
 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).
 167
 168 .. _`Principle of Least Authority`: http://www.eros-os.org/papers/secnotsep.pdf
 169
 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.
 179
 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.
 188
 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.
 199
 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.
 205
 206 The implementation of the ``tahoe`` subcommands is straightforward
 207 and raises no further difficult design issues.