source: trunk/docs/magic-wormhole-invites.rst

Last change on this file was e3a6d759, checked in by Jean-Paul Calderone <exarkun@…>, at 2020-02-13T15:23:27Z

Remove the obvious documentation references

  • Property mode set to 100644
File size: 2.6 KB
Line 
1**********************
2Magic Wormhole Invites
3**********************
4
5Magic Wormhole
6==============
7
8`magic wormhole`_ is a server and a client which together use Password
9Authenticated Key Exchange (PAKE) to use a short code to establish a
10secure channel between two computers. These codes are one-time use and
11an attacker gets at most one "guess", thus allowing low-entropy codes
12to be used.
13
14.. _magic wormhole: https://github.com/warner/magic-wormhole#design
15
16
17Invites and Joins
18=================
19
20Inside Tahoe-LAFS we are using a channel created using `magic
21wormhole`_ to exchange configuration and the secret fURL of the
22Introducer with new clients.
23
24This is a two-part process. Alice runs a grid and wishes to have her
25friend Bob use it as a client. She runs ``tahoe invite bob`` which
26will print out a short "wormhole code" like ``2-unicorn-quiver``. You
27may also include some options for total, happy and needed shares if
28you like.
29
30Alice then transmits this one-time secret code to Bob. Alice must keep
31her command running until Bob has done his step as it is waiting until
32a secure channel is established before sending the data.
33
34Bob then runs ``tahoe create-client --join <secret code>`` with any
35other options he likes. This will "use up" the code establishing a
36secure session with Alice's computer. If an attacker tries to guess
37the code, they get only once chance to do so (and then Bob's side will
38fail). Once Bob's computer has connected to Alice's computer, the two
39computers performs the protocol described below, resulting in some
40JSON with the Introducer fURL, nickname and any other options being
41sent to Bob's computer. The ``tahoe create-client`` command then uses
42these options to set up Bob's client.
43
44
45
46Tahoe-LAFS Secret Exchange
47==========================
48
49The protocol that the Alice (the one doing the invite) and Bob (the
50one being invited) sides perform once a magic wormhole secure channel
51has been established goes as follows:
52
53Alice and Bob both immediately send an "abilities" message as
54JSON. For Alice this is ``{"abilities": {"server-v1": {}}}``. For Bob,
55this is ``{"abilities": {"client-v1": {}}}``.
56
57After receiving the message from the other side and confirming the
58expected protocol, Alice transmits the configuration JSON::
59
60    {
61        "needed": 3,
62        "total": 10,
63        "happy": 7,
64        "nickname": "bob",
65        "introducer": "pb://xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@example.com:41505/yyyyyyyyyyyyyyyyyyyyyyy"
66    }
67
68Both sides then disconnect.
69
70As you can see, there is room for future revisions of the protocol but
71as of yet none have been sketched out.
Note: See TracBrowser for help on using the repository browser.