Add docs about Revealer plugin copied from revealer.cc

index.rst

@@ -19,7 +19,7 @@ Electrum is a lightweight Bitcoin wallet.
    coldstorage
    hardware-linux
    tails
-   plugins
+   plugins/index
 
 
 .. toctree::

plugins.rst → plugins/index.rst

@@ -3,7 +3,7 @@ Plugins
 
 The plugin system of Electrum is designed to allow the development of new features without increasing the core code of Electrum. To enable or disable Plugins, see menubar > `Tools` > `Plugins`. 
 
-Below you can find a short description of each available tool. 
+Below you can find a short description of each available tool.
 
 
 Audio Modem
@@ -37,6 +37,14 @@ Revealer
 
 This plug-in allows you to create a visually encrypted backup of your wallet seeds, or of custom alphanumeric secrets.
 
+.. toctree::
+  :maxdepth: 1
+  :glob:
+
+  revealer/how_to_use
+  revealer/how_it_works
+  revealer/faq
+
 
 Two Factor Authentication
 -------------------------
@@ -51,5 +59,3 @@ Virtual Keyboard
 
 Add an optional virtual keyboard to the password dialog.
 Warning: do not use this if it makes you pick a weaker password.
-
-

plugins/revealer/faq.rst

@@ -0,0 +1,109 @@
+FAQ
+===
+
+What is the Revealer card?
+--------------------------
+
+A secure, visual representation of an ecryption key.
+
+
+What is the Secret card?
+------------------------
+
+A secure, visual representation of a secret encrypted by the Revealer.
+
+
+Can I reuse a Revealer to encrypt multiple secrets?
+---------------------------------------------------
+
+Yes, but you shouldn't.
+
+The Revealer is a one time pad, it only has perfect security as long as it’s
+used once. An adversary in possession of multiple Secrets, encrypted by the same
+Revealer, may be able to attack the Revealer. Depending on your threat model you
+might want to have more than one secret encrypted by the same Revealer. In this
+case, you need to make sure an adversary has no way of accessing two (or more)
+different Secrets encrypted by the same Revealer.
+
+
+Can I encrypt other secrets that are not an Electrum seed?
+----------------------------------------------------------
+
+Yes, you can encrypt any alphanumeric string. Use the ‘custom secret’ field at
+the encryption dialog of the software. BIP 39 and AEZEED seeds will fit on the
+card, but will have a smaller font size. The software will adjust the font size
+automatically after a certain amount of characters.
+
+
+How is the noise generated?
+---------------------------
+
+The deterministic noise is generated with the provably secure HMAC_DRBG
+(SHA-512) algorithm, seeded with 128 bits of entropy from the cryptographically
+secure /dev/urandom.
+
+
+Why should I use it?
+--------------------
+
+Unencrypted secrets may still be vulnerable to physical attacks (e.g., theft or
+copying). If your secrets are encrypted, an adversary with physical access can't
+read them. This allows you to create redundant backups without reducing safety.
+Ultimately it adds a layer of noise to your seed or password. Encrypting it
+visually, in two-factors, has the benefit that it doesn't require computers or
+expertise to decrypt.
+
+
+How to reveal the secret?
+-------------------------
+
+Place your Revealer card precisely on top of the Secret card.
+
+Observing the marks on diagonally opposing corners and pressing the card
+slightly down will give you a good image.
+
+
+What happens if I mistype the Revealer code?
+--------------------------------------------
+
+The code includes a checksum so the software detects it and does not let you
+proceed.
+
+
+What are the codes on the Revealers and Secrets?
+-------------------------------------------------
+
+On the Revealer, the first digit is the version number, followed by a 32 digit
+random seed (128 bits of entropy in hex format) used to generate the pattern,
+and finally a three digit checksum (the least important bits of
+``SHA256(version number + seed)``).
+
+On the Secret, the code consists of a version number and checksum (formatted as
+`VersionNumber_Checksum`). It's an identifier to facilitate matching it with the
+correct Revealer. It can't be used to reverse engineer the Revealer.
+
+
+Why only 128 bits?
+------------------
+
+If you can break 128 bits you can break bitcoin directly and won’t bother
+breaking revealer.
+
+
+I printed the PDFs but the cards don't line up.
+-----------------------------------------------
+
+Make sure that you print your PDF at 100% size, not ‘fit to paper’. If you still
+have difficulties reading your secrets, you might want to use the Printer
+Calibration tool.
+
+
+What is printer calibration and how does it work?
+-------------------------------------------------
+
+Printer calibration allows you to generate a PDF that is adjusted to your
+printer/paper. Each printer/paper will have (at least) a sub-milimiter
+difference in the size they print out. Revealer is a precision device, if those
+differences are big enough it might not be possible to read all the words at the
+same time, rather one line or a word a time depending on how big the size
+difference is.

plugins/revealer/how_it_works.rst

@@ -0,0 +1,80 @@
+How It Works
+============
+
+.. raw:: html
+
+  <p>
+  <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/D5ty8lIiI6o" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  </p>
+
+Technical Details
+-----------------
+
+Below is a technical description of the principles behind Revealer, there are
+also :doc:`instructions for encrypting your secrets <how_to_use>`.
+
+The plugin uses the Revealer to encrypt your secret following
+`this scheme <http://www.wisdom.weizmann.ac.il/~naor/PAPERS/visual_pap.ps.gz>`_
+described by legendary cryptographers Moni Naor and Adi Shamir, published in
+1994.
+
+.. image:: /png/revealer/revealer-0_11b.png
+  :align: center
+  :alt: Cropped sample of a Revealer card with ID 06DAA3EC93CC8579ED054A5946EB2277411B
+
+Each Revealer has a unique code. It consists of a single digit version number, a
+32 digit random seed (128 bits of entropy in hex format), and a three digit
+checksum (the least important bits of SHA256[version number + seed]). The
+version number indicates the dimensions of the Revealer, the random seed is used
+to generate the pattern, and the checksum offers some protection against
+mistypes.
+
+Step 1) Create a 159 x 97 pixel image made up of 15,423 bits of pseudo-random
+noise. The pseudo-random bits are generated with the provably secure HMAC_DRBG
+(SHA-512) algorithm, which is seeded by the Revealer random seed.
+
+.. _noise-figure:
+
+.. figure:: /png/revealer/noise.png
+  :width: 318px
+  :align: center
+  :alt: Pseudo randomized black and white pixels
+
+  Pseudo-random noise
+
+Step 2) The secret to be encrypted is an alphanumeric string also encoded as an
+image.
+
+.. figure:: /png/revealer/secret.png
+  :width: 318px
+  :align: center
+  :alt: IMPROVE PREVENT INCH DURING CANNON WINE PRAISE MAIL BROCCOLI BLIND WHEEL DEPART
+
+  Sample secret
+
+Step 3) A binary operation (XOR) is executed with the noise image (step 1) and
+the unencrypted secret image (step 2) to create the encrypted secret image:
+
+.. _encrypted-secret-figure:
+
+.. figure:: /png/revealer/encrypted_secret.png
+  :width: 318px
+  :align: center
+  :alt: Encrypted secret that looks like randomized black and white pixels
+
+  Encrypted secret
+
+Step 4) In order to perform an XOR operation without a computer, the original
+images need to be encoded in the following way: For each black pixel we use the
+matrix on the left, and for each white pixel the matrix on the right.
+
+.. image:: /png/revealer/code.png
+  :align: center
+  :alt: Two squares, each divided in 4 sections. First squares section colors in
+    clockwise order: white, black, white, black. Second squares section colors
+    in clockwise order: black, white, black, white.
+
+The decryption happens by XORing the encrypted Secret with the original noise.
+The Revealer is the encoded :ref:`noise <noise-figure>` and the Secret is the encoded
+:ref:`encrypted secret <encrypted-secret-figure>`. When they are overlayed, a visual XOR operation
+happens and the secret is revealed.

plugins/revealer/how_to_use.rst

@@ -0,0 +1,67 @@
+How To Use
+==========
+
+Encrypting a secret is a simple four step process.
+
+1. `Enable the plugin`_
+2. `Create or load a Revealer`_
+3. `Encrypt your secret`_
+4. `Test your backup`_
+
+
+Enable the plugin
+-----------------
+
+Revealer plugin is included with Electrum Bitcoin Wallet since version 3.2.
+Start Electrum, go to the menu ‘Tools->Plugins’, and activate the Revealer
+plugin.
+
+.. image:: /png/revealer/enable-plugin.png
+  :alt: Electrum plugins window with Revealer plugin enabled
+
+After restarting Electrum, the revealer icon is shown in the main window status
+bar.
+
+.. image:: /png/revealer/electrum-gui-with-revealer.png
+  :alt: Electrum main window with Revealer plugin icon
+
+
+Create or load a Revealer
+-------------------------
+
+Click the Revealer icon to open the setup dialog. Click "Create a new Revealer"
+or enter the code of an existing Revealer.
+
+.. image:: /png/revealer/setup.png
+  :alt: Revealer setup dialog window
+
+When creating a new Revealer, the path to the new PDF and PNG will be shown.
+
+
+Encrypt your secret
+-------------------
+
+Click next on the Revealer setup window. Choose to encrypt your current wallet's
+seed or enter a secret in the text area.
+
+.. image:: /png/revealer/encrypt.png
+  :alt: Revealer encrypt dialog window
+
+The path to your encrypted secret PDF and PNG will be shown.
+
+Print the Revealer and Secret
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Open the Revealer and Secret PDFs and print them out.
+
+.. image:: /png/revealer/print.png
+  :alt: Electrum dialog window showing the path to the newly encrypted secret
+
+Test your backup
+----------------
+
+Make sure you test that your backups work by printing and overlaying them to
+reveal the encrypted secret.
+
+.. image:: /png/revealer/one_card_revealer_zero_perspective_transparent.png
+  :alt: Sample Revealer and Secret overlayed on each other

plugins/revealer/warning_upgrade.rst

@@ -0,0 +1,59 @@
+:orphan:
+
+Warning and Upgrade
+===================
+
+On August 18th, 2018, Alan Evans published
+`Revealer.cc — Deepdive and warning`_, which raised questions about the security
+of the Pseudo Random Number Generator and warned against Revealer re-use.
+
+Our Response
+------------
+
+Revealer is based on a One Time Pad and should be used to encrypt one single
+secret. It is not secure to use the same Revealer multiple times. We understand
+that the warning against re-use on our FAQ was not loud enough and have added an
+extra warning directly on the software encryption dialog.
+
+To eliminate any further concerns about security of the PRNG Revealer will
+upgrade to the provable secure HMAC_DRBG (SHA-512). The code is already patched
+in the Electrum master repository and will be available from the next release.
+An attack in the current implementation has not been demonstrated.
+
+
+What's the problem with the Pseudo Random Number Generator?
+-----------------------------------------------------------
+
+Observing a sufficient number of outputs from a Mersenne Twister (MT) allows a
+attacker to reconstruct the internal state and predict all future outputs. A
+secret encrypted with Revealer does not leak enough information to be able to
+recover the internal state of MT. A few leaked single bit states won’t help much
+in well known attack vectors. We are not aware of any possible attack in the
+current implementation. Nevertheless, MT is not recommended for cryptographic
+use, and it could become a problem for larger or different versions. From the
+next release, the noise will be generated using the Deterministic Random Bit
+Generator HMAC_DRBG (SHA-512). It will continue to be seeded with 128bit entropy
+from cryptographic secure /dev/urandom.
+
+
+What’s the problem with using a Revealer to encrypt multiple secrets?
+---------------------------------------------------------------------
+
+Revealer is based on a One Time Pad and should be used to encrypt one single
+secret. In possession of multiple secrets encrypted for the same Revealer it can
+be attacked. We have included a explicit warning in the software to avoid user
+mistake. Encrypting more than one secret is still possible, and might be
+desirable for some threat models. See more information on our :doc:`faq`.
+
+
+What should users do?
+---------------------
+
+It is recommended to upgrade your backups. The patched version of the software
+is merged into Electrum master repository and will be available in the next
+release. Only encrypt multiple secrets for the same Revealer if you know what
+you are doing and understand the risks involved.
+
+Published: 28.08.2018
+
+.. _Revealer.cc — Deepdive and warning: https://medium.com/@_west_on/revealer-cc-deepdive-and-warning-77892b3a24a1