README 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121
  1. THIS PROJECT IS STILL IN EARLY DEVELOPMENT IT USES EXPERIMENTAL
  2. CRYPTOGRAPHIC LIBRARIES AND IT HAS NOT HAD ANY KIND OF SECURITY
  3. OR CRYPTOGRAPHY REVIEW THIS SOFTWARE MIGHT BE BROKEN AND UNSAFE
  4. https://xkcd.com/949/
  5. WebWormhole creates ephemeral pipes between computers to send files
  6. or other data. Try it at https://webwormhole.io or on the command
  7. line.
  8. On one computer the tool generates a one-time code:
  9. $ cat hello.txt
  10. hello, world
  11. $ ww send hello.txt
  12. east-pep-aloe
  13. On another use the code to establish a connection:
  14. $ ww receive east-pep-aloe
  15. $ cat hello.txt
  16. hello, world
  17. To install the command line tool:
  18. $ go install webwormhole.io/cmd/ww@latest
  19. This requires Go 1.13 or newer.
  20. To run the signalling server you need to compile the WebAssembly
  21. files first.
  22. $ make wasm
  23. $ ww server -https= -http=localhost:8000
  24. To package the browser extension for Firefox or Chrome:
  25. $ make webwormhole-ext.zip
  26. WebWormhole is inspired by and uses a model very similar to that
  27. of Magic Wormhole.
  28. https://github.com/warner/magic-wormhole
  29. It differs in that it uses WebRTC to make its connections. This
  30. allows us to make use of WebRTC's NAT traversal tricks, as well as
  31. the fact that it can be used in browsers. The exchange of session
  32. descriptions (offers and answers) is protected by PAKE (we use
  33. CPace) and a generated random password, similar to Magic Wormhole.
  34. The session descriptions include the fingerprints of the DTLS
  35. certificates that WebRTC uses to secure its communications.
  36. The author operates the signalling server at webwormhole.io, its
  37. alias wrmhl.link, and a relay server. These are free to use but
  38. come with no SLAs or any guarantees of uptime. They facilitate
  39. establishing connections between peers, but do not handle any
  40. transferred data in cleartext.
  41. The protocol does not need to trust the signalling server to maintain
  42. the confidentiality of the files transferred. However, the convenience
  43. of using the web client directly on webwormhole.io comes at the
  44. cost of having to trust the code it serves. If the server is ever
  45. compromised it can be used inject malicious code that undermines
  46. the security of the client. To mitigate this, you can have more
  47. control over which version of the client you run by using the command
  48. line client or the browser extension. The extension is identical
  49. to the web client, but packaged for Chrome and Firefox, loads no
  50. remote code, and requires no permissions:
  51. https://addons.mozilla.org/firefox/addon/webwormhole/
  52. https://chrome.google.com/webstore/detail/jhombkhjanncdalcbcahinpjoacaiidn
  53. Unless otherwise noted, the source files in this repository are
  54. distributed under the BSD-style license found in the LICENSE file.
  55. Frequently asked questions
  56. Is it compatible with magic-wormhole?
  57. It is not. Maybe one day.
  58. This project started as a UI for magic-wormhole, but drifted
  59. away when I wanted to experiment with the PAKE used, the
  60. protocol, and the word lists.
  61. Why CPace and not another PAKE algorithm?
  62. CPace and PAKE2 were the finalists for CFRG PAKE selection
  63. process (https://github.com/cfrg/pake-selection), so it was
  64. going to be one of the two.
  65. CPace (https://tools.ietf.org/id/draft-haase-cpace-01.html)
  66. looked nice and simple to implement, and there wasn't a
  67. CPace Go package at the time, so it was a good opportunity
  68. and a learning exercise to write one. I ended up nerd-sniping
  69. Filippo instead and he beat me to write filippo.io/cpace.
  70. Why not the PGP word list?
  71. The PGP word list (https://en.wikipedia.org/wiki/PGP_word_list)
  72. is quite good as far as unambiguity goes. However, a few
  73. word combinations do make some unsavoury phrases. I switched
  74. to a word list that is more agreeable.
  75. Also, it would be nice to experiment with localised word
  76. lists.
  77. Don't you have to trust the web server anyway? What's the point of
  78. the PAKE?
  79. Yes and no. The application itself, because of the PAKE,
  80. does not need to trust the signalling server. You can install
  81. the command line tool, the browser extension, or host the
  82. web application's files yourself and not have to trust the
  83. signalling server at all. There's also a mobile app version
  84. in the works.
  85. The web version hosted on webwormhole.io exists as a middle
  86. ground between convenience and security. Like any other
  87. website you visit, you do have to trust it's not running
  88. any malicious code in your browser.