open.source/magic-wormhole
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

add docs for 0.3.0

Browse Source
This commit is contained in:
Brian Warner 2015-06-24 00:21:19 -07:00
parent 894da44244
commit f6eeaab0e4
4 changed files with 52 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
MANIFEST.in
View File

@ -1,5 +1,5 @@
include versioneer.py include versioneer.py
include src/wormhole/_version.py include src/wormhole/_version.py
include LICENSE README.md include LICENSE README.md NEWS.md
recursive-include docs *.md *.rst recursive-include docs *.md *.rst

19
NEWS.md Normal file
View File

@ -0,0 +1,19 @@
User-visible changes in "magic-wormhole":
## Release 0.3.0 (24-Jun-2015)
Add preliminary Twisted support, only for symmetric endpoints (no
initator/receiver distinction). Lacks code-entry tab-completion. May still
leave timers lingering. Add test suite (only for Twisted, so far).
Use a sqlite database for Relay server state, to survive reboots with less
data loss. Add "--advertise-version=" to "wormhole relay start", to override
the version we recommend to clients.
## Release 0.2.0 (10-Apr-2015)
Initial release: supports blocking/synchronous asymmetric endpoints
(Initiator on one side, Receiver on the other). Codes can be generated by
Initiator, or created externally and passed into both (as long as they start
with digits: NNN-anything).

15
README.md
View File

@ -113,12 +113,13 @@ All four commands accept:
## Library ## Library
The `wormhole` module makes it possible for other applications to use these The `wormhole` module makes it possible for other applications to use these
code-protected channels. The current release only includes code-protected channels. This includes blocking/synchronous support (for an
blocking/synchronous support, but a future release will include async/Twisted asymmetric pair of "initiator" and "receiver" endpoints), and async/Twisted
libraries too. The main module is named `wormhole.blocking.transcribe`, to support (for a symmetric scheme). The main module is named
reflect that it is for synchronous/blocking code, and uses a PAKE mode `wormhole.blocking.transcribe`, to reflect that it is for
whereby one user transcribes their code to the other. (internal names may synchronous/blocking code, and uses a PAKE mode whereby one user transcribes
change in the future). There are distinctive sides: one `Initiator`, and one their code to the other. (internal names may change in the future). The
synchronous support uses distinctive sides: one `Initiator`, and one
`Receiver`. `Receiver`.
The file-transfer tools use a second module named The file-transfer tools use a second module named
@ -138,7 +139,7 @@ This library is intended to be compatible with python2.6, 2.7, 3.3, and 3.4,
although proper tests have not yet been implemented. although proper tests have not yet been implemented.
It depends upon the SPAKE2, pynacl, requests, and argparse libraries. To run It depends upon the SPAKE2, pynacl, requests, and argparse libraries. To run
a relay server, you must also install Twisted. a relay server or use the async support, you must also install Twisted.
#### footnotes #### footnotes

25
docs/api.md
View File

@ -88,6 +88,27 @@ both sides are the same, call `d=get_data()` to continue the transfer. If you
call `get_data()` first, it will perform the complete transfer without call `get_data()` first, it will perform the complete transfer without
pausing. pausing.
## Generating the Invitation Code
In most situations, the Initiator will call `i.get_code()` to generate the
invitation code. This returns a string in the form `NNN-code-words`. The
numeric "NNN" prefix is the "channel id", and is a short integer allocated by
talking to the rendezvous server. The rest is a randomly-generated selection
from the PGP wordlist, providing a default of 16 bits of entropy. The
initiating program should display this code to the user, who should
transcribe it to the receiving user, who gives it to the Receiver object by
calling `r.set_code()`. The receiving program can also use
`input_code_with_completion()` to use a readline-based input function: this
offers tab completion of allocated channel-ids and known codewords.
Alternatively, the human users can agree upon an invitation code themselves,
and provide it to both programs later (with `i.set_code()` and
`r.set_code()`). They should choose a channel-id that is unlikely to already
be in use (3 or more digits are recommended), append a hyphen, and then
include randomly-selected words or characters. Dice, coin flips, shuffled
cards, or repeated sampling of a high-resolution stopwatch are all useful
techniques.
## Application Identifier ## Application Identifier
@ -114,7 +135,9 @@ This library includes the URL of a public relay run by the author.
Application developers can use this one, or they can run their own (see Application developers can use this one, or they can run their own (see
src/wormhole/servers/relay.py) and configure their clients to use it instead. src/wormhole/servers/relay.py) and configure their clients to use it instead.
## Polling and Shutdown (TODO) ## Polling and Shutdown
TODO: this is mostly imaginary
The reactor-based (Twisted-style) forms of these objects need to establish The reactor-based (Twisted-style) forms of these objects need to establish
TCP connections, re-establish them if they are lost, and sometimes (for TCP connections, re-establish them if they are lost, and sometimes (for