diff --git a/index.rst b/index.rst index 4f2e0fc..8022263 100644 --- a/index.rst +++ b/index.rst @@ -19,7 +19,7 @@ Electrum is a lightweight Bitcoin wallet. coldstorage hardware-linux tails - plugins + plugins/index .. toctree:: diff --git a/plugins.rst b/plugins/index.rst similarity index 89% rename from plugins.rst rename to plugins/index.rst index 4280e7e..587f9d7 100644 --- a/plugins.rst +++ b/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. - - diff --git a/plugins/revealer/faq.rst b/plugins/revealer/faq.rst new file mode 100644 index 0000000..2a40315 --- /dev/null +++ b/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. diff --git a/plugins/revealer/how_it_works.rst b/plugins/revealer/how_it_works.rst new file mode 100644 index 0000000..12f71b2 --- /dev/null +++ b/plugins/revealer/how_it_works.rst @@ -0,0 +1,80 @@ +How It Works +============ + +.. raw:: html + +

+ +

+ +Technical Details +----------------- + +Below is a technical description of the principles behind Revealer, there are +also :doc:`instructions for encrypting your secrets `. + +The plugin uses the Revealer to encrypt your secret following +`this scheme `_ +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 ` and the Secret is the encoded +:ref:`encrypted secret `. When they are overlayed, a visual XOR operation +happens and the secret is revealed. diff --git a/plugins/revealer/how_to_use.rst b/plugins/revealer/how_to_use.rst new file mode 100644 index 0000000..2acfab0 --- /dev/null +++ b/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 diff --git a/plugins/revealer/warning_upgrade.rst b/plugins/revealer/warning_upgrade.rst new file mode 100644 index 0000000..48b1e93 --- /dev/null +++ b/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 diff --git a/png/revealer/code.png b/png/revealer/code.png new file mode 100644 index 0000000..1e796ba Binary files /dev/null and b/png/revealer/code.png differ diff --git a/png/revealer/electrum-gui-with-revealer.png b/png/revealer/electrum-gui-with-revealer.png new file mode 100644 index 0000000..d1d9210 Binary files /dev/null and b/png/revealer/electrum-gui-with-revealer.png differ diff --git a/png/revealer/enable-plugin.png b/png/revealer/enable-plugin.png new file mode 100644 index 0000000..d431f16 Binary files /dev/null and b/png/revealer/enable-plugin.png differ diff --git a/png/revealer/encrypt.png b/png/revealer/encrypt.png new file mode 100644 index 0000000..9993160 Binary files /dev/null and b/png/revealer/encrypt.png differ diff --git a/png/revealer/encrypted_secret.png b/png/revealer/encrypted_secret.png new file mode 100644 index 0000000..c9743b0 Binary files /dev/null and b/png/revealer/encrypted_secret.png differ diff --git a/png/revealer/noise.png b/png/revealer/noise.png new file mode 100644 index 0000000..f332e58 Binary files /dev/null and b/png/revealer/noise.png differ diff --git a/png/revealer/one_card_revealer_zero_perspective_transparent.png b/png/revealer/one_card_revealer_zero_perspective_transparent.png new file mode 100644 index 0000000..fe262c2 Binary files /dev/null and b/png/revealer/one_card_revealer_zero_perspective_transparent.png differ diff --git a/png/revealer/print.png b/png/revealer/print.png new file mode 100644 index 0000000..b659608 Binary files /dev/null and b/png/revealer/print.png differ diff --git a/png/revealer/revealer-0_11b.png b/png/revealer/revealer-0_11b.png new file mode 100644 index 0000000..0857139 Binary files /dev/null and b/png/revealer/revealer-0_11b.png differ diff --git a/png/revealer/secret.png b/png/revealer/secret.png new file mode 100644 index 0000000..61c5058 Binary files /dev/null and b/png/revealer/secret.png differ diff --git a/png/revealer/setup.png b/png/revealer/setup.png new file mode 100644 index 0000000..2576df6 Binary files /dev/null and b/png/revealer/setup.png differ