diff --git a/_data/docs_toc.yml b/_data/docs_toc.yml
index b128d95..0f37005 100644
--- a/_data/docs_toc.yml
+++ b/_data/docs_toc.yml
@@ -1,9 +1,8 @@
- title: Glacier overview
docs:
- - overview
+ - overview/about
- overview/key-concepts
- overview/multi-signature-security
- - overview/attack-surface
- title: Before you start
docs:
- before-you-start/overview
@@ -12,8 +11,7 @@
- title: Setup
docs:
- setup/verify
- - setup/non-quarantined-hardware
- - setup/quarantined-hardware
+ - setup/prepare-hardware
- setup/create-boot-usb
- setup/create-app-usb
- setup/quarantined-workspace
@@ -33,6 +31,9 @@
docs:
- check-balance/overview
- check-balance/maintenance
+- title: Protocol vulnerabilities
+ docs:
+ - protocol-vulnerabilities/attack-surface
- title: Extend Glacier
docs:
- extend/security
diff --git a/_docs/before-you-start/hardware.md b/_docs/before-you-start/hardware.md
index c0979af..36ed0b4 100644
--- a/_docs/before-you-start/hardware.md
+++ b/_docs/before-you-start/hardware.md
@@ -6,76 +6,51 @@ description: Learn what hardware you need to acquire for using Glacier, the
Glacier has been written and tested around these specific equipment recommendations.
-### Eternally quarantined hardware: Set 1
-
-* Factory-sealed computer with 2 USB ports and a camera:
-[2016 Dell Inspiron 11.6"](http://a.co/1E6HEQA)
-* Two factory-sealed USB drives (2GB+) from the same manufacturer:
-[SanDisk Cruzer 8GB](http://a.co/1Us66ze).
-
-We'll be using two USB drives at the same time. If the computer has only one USB
-port, you'd need to use a USB hub, which is a separate piece of USB hardware subject
-to malware infection of its firmware.
-
-We'll use the camera for reading QR codes.
-
-### Eternally quarantined hardware: Set 2
-
-* Factory-sealed computer from a different manufacturer, also with 2 USB ports
-and a camera:
-[Acer Aspire One Cloudbook 11"](http://a.co/1ZMSB3Y)
-* Two factory-sealed USB drives (2GB+) from the same manufacturer, but a different
-manufacturer than the drives for Set 1:
-[Verbatim 2GB](http://a.co/jdzEf8O)
-
-
-### Used/existing computing equipment
-
-* Two computers with Internet connectivity, administrator access, and about
-2GB of free disk space. **Each computer must be running Windows 10, macOS, or
-Linux.**
-
- One of these two computers should be a computer that you do not own (unless
- purchased brand new), or that has spent much time on your home or office network.
-* Printer
-* Smartphone with a working camera
-
-
-### Other Equipment
-
-* Two factory-sealed USB drives (2GB+):
-[Verbatim 2GB](http://a.co/jieluaE)
-* [Precision screwdrivers](http://a.co/bbvj16a),
-for removing WiFi cards from laptops
-* [Electrical tape](http://a.co/gZZiEdA)
-* [Casino-grade six-sided dice](http://a.co/ghbdiak).
-Regular dice are insufficient.
-* [Faraday bag](http://a.co/3wiNPLT).
-Used to prevent smartphone malware from
-[stealing sensitive data using radio frequencies](https://www.usenix.org/legacy/event/sec09/tech/full_papers/vuagnoux.pdf).
-* [Table fan](http://a.co/98PrpMs).
-White noise can prevent malware on nearby devices from
-[stealing sensitive data using sound](https://www.wired.com/2016/06/clever-attack-uses-sound-computers-fan-steal-data/).
-* [Home safe](http://a.co/6sRoaPv).
-Consider bolting it to your floor to deter theft.
-* [TerraSlate paper](http://a.co/7pk5fJN).
-Waterproof, heat resistant, and tear-resistant.
-* [Cardboard envelopes](http://a.co/7jUPLMR), for opacity
-* [Tamper-resistant seals](http://a.co/96KlsAl)
-
-### Notes
-
-Standard software algorithms that generate random numbers, such as those used
-to generate Bitcoin private keys, are
-[vulnerable to exploitation](https://bitcoin.org/en/alert/2013-08-11-android),
-either due to malware or algorithmic weakness (i.e. they often provide numbers that
-are not truly random). Dice offer something closer to true randomness.
-
-Casino dice are created specifically to remove any potential dice bias
-(square corners, filled in pips, low manufacturing tolerance, etc.) That's why
-casinos use them!
-
-TerraSlate paper is extremely rugged, but you might also consider laminating the
-paper for additional protection. You'll need a
-[thermal laminator](http://a.co/cZBN1YU) and
-[laminating pouches](http://a.co/ifISzje).
+## Factory new hardware
+
+All items *must* be brand new and factory sealed. Manufacturers A and B *must* be
+different, and manufacturers C and D *must* be different.
+
+### Eternally quarantined
+
+* **Q1**: Computer from manufacturer A, with two USB ports and a camera: For example,
+[2016 Dell Inspiron 11.6"](https://a.co/1E6HEQA)
+* **Q1 BOOT**: USB drive from manufacturer C, minimum 2GB: For example, [SanDisk Cruzer 8GB](https://a.co/1Us66ze)
+* **Q1 APP**: USB drive from manufacturer C, minimum 2GB: For example, [SanDisk Cruzer 8GB](https://a.co/1Us66ze)
+
+* **Q2**: Computer from manufacturer B, with two USB ports and a camera: For example,
+[Acer Aspire One Cloudbook 11"](https://a.co/1ZMSB3Y)
+* **Q2 BOOT**: USB drive from manufacturer D, minimum 2GB: For example, [Verbatim 2GB](https://a.co/jdzEf8O)
+* **Q2 APP**: USB drive from manufacturer D, minimum 2GB: For example, [Verbatim 2GB](https://a.co/jdzEf8O)
+
+The computers require two USB ports for simultaneous usage of the USB drives. Cameras are
+required for reading QR codes.
+
+### Non-quarantined
+
+* **SETUP BOOT 1**: USB drive from manufacturer C, D or other (2GB+): For example, [Verbatim 2GB](https://a.co/jieluaE)
+* **SETUP BOOT 2**: USB drive from manufacturer C, D or other (2GB+): For example, [Verbatim 2GB](https://a.co/jieluaE)
+
+## Used/existing hardware
+
+* **SETUP 1**: Computer, either brand new or has not spent much time connected to the internet,
+with internet connectivity, administrator access, and 2GB of free disk space. *Must*
+be running Windows 10, MacOS, or Linux.
+* **SETUP 2**: Computer with internet connectivity, administrator access, and about
+2GB of free disk space. *Must* be running Windows 10, MacOS, or Linux.
+* **Printer**
+* **Smartphone**: Must have a working camera
+
+### Other equipment
+
+* **Precision screwdrivers**: To dismantle hardware. For example, [Tekton 2977](https://a.co/bbvj16a)
+* **Electrical tape**: To insulate loose connection. For example, [Duck](https://a.co/gZZiEdA)
+* **Casino-grade six-sided dice**: To provide entropy. Casino dice offer number generation which is closer to true randomness than a computer can provide.
+The square corners, filled in pips and low manufacturing tolerances mean casino dice remove
+any potential dice bias present in regular dice. For example, [Trademark Poker](https://a.co/ghbdiak)
+* **Faraday bag**: To prevent smartphone data exfiltration via radio side channel. For example, [Stealth Anti Signal Forensic Faraday Bag](https://a.co/3wiNPLT)
+* **Table fan**: To provide white noise. For example, [Holmes Lil' Blizzard](https://a.co/98PrpMs)
+* **Home safe**: To secure keys, bolted to the floor. For example, [AmazonBasics Security Safe](https://a.co/6sRoaPv)
+* **TerraSlate paper**: To write private keys on. For example, [TerraSlate paper](https://a.co/7pk5fJN)
+* **Cardboard envelopes**: To opaquely store private keys. For example, [Quality Park Extra-Rigid Fiberboard](https://a.co/7jUPLMR)
+* **Tamper-resistant seals**: To highlight tampering. For example, [BoxSilver Security Holograms](https://a.co/96KlsAl)
\ No newline at end of file
diff --git a/_docs/before-you-start/overview.md b/_docs/before-you-start/overview.md
index 29e31d7..06ad2ad 100644
--- a/_docs/before-you-start/overview.md
+++ b/_docs/before-you-start/overview.md
@@ -8,180 +8,132 @@ redirect_from: /docs/before-you-start/
This section
establishes a basic understanding of the Glacier protocol in order to
facilitate its execution. For more background on the protocol's design, see
-the Glacier [design document](../design-doc/overview.md).
+the [design document](/docs/design-doc/overview).
As described previously, the Glacier
-protocol involves putting bitcoins in cold storage, using multisignature
+protocol involves securing bitcoins in cold storage, using multisignature
security, with the keys stored only on paper.
-## Eternally Quarantined Hardware
+## Eternally quarantined hardware
-This bulk of the Glacier protocol consists of ways to safeguard
-against theft of private keys due to malware infection. To accomplish this,
-Glacier uses eternally quarantined hardware.
+The central concept the Glacier protocol uses to safeguard against theft
+of private keys due to malware infection, is eternally quarantined hardware.
-Quarantined hardware means
-we drastically limit the ways in which a piece of hardware interfaces with
-the outside world in order to prevent the transmission of sensitive data
-(e.g. private keys) or harmful data (e.g. malware). We consider all
-interfaces -- network, USB, printer, and so on -- because any of them
-might be used to transmit malware or private keys.
+Eternally quarantined hardware is hardware with drastically limited
+interfaces with the outside world. This prevents the transmission of
+sensitive or harmful data, for example, private keys or malware. All
+interfaces are considered, including network, USB and printer, because
+all may be used to transmit data.
-Eternally quarantined
-hardware means we use factory-new hardware for this purpose (to minimize
-risk of prior malware infection), and never lift the quarantine. The
-quarantine is permanent because any malware infection which does somehow
-get through the quarantine might wait indefinitely for an opportunity to use
-an available interface (e.g. the Internet, if a quarantined laptop is later
-used to access the web). Eternal quarantining renders the hardware
-essentially useless for anything else but executing this protocol.
+To ensure hardware is eternally quarantined, factory-new hardware is used to
+minimize the risk of prior malware infection. This hardware must be
+permanantly quarantined, effectively rendering it useless for anything other
+than executing the protocol. The quarantine is *strictly* permanent because
+any malware infection which gets through the quarantine may wait
+indefinitely for an opportunity to use an available interface, for example,
+if a quarantined laptop is later used to access the web.
-## Parallel Hardware Stacks
+## Parallel hardware stacks
-There is a class of attacks which rely not on stealing
+"Flawed data" is a class of attack which relies not on stealing
your sensitive data (e.g. private keys), but in subverting the process of
-generating your sensitive data so it can be more easily guessed by a third
-party. We call this "flawed data."
-
-For example, a variant of the Trojan.Bitclip attack which replaces keys
-displayed on your screen (or keys stored in your clipboard) with insecure keys.
-
-Because we are generating our data in
-eternally quarantined environments, any malware infection attempting this is
-unlikely to have come from your other computers -- it would likely have
-already been present when the quarantined system arrived from the
-manufacturer. For example, the Lenovo rootkit or this Dell firmware malware
-infection.
-
-The way to defeat these attacks is to detect them before
-we actually use the flawed data. We can detect such an attack by
-replicating the entire data generation process on two sets of eternally
-quarantined hardware, from different manufacturers. If the process
-generates identical data on both sets of hardware, we can be highly
-confident the data is not flawed because it would have to be an identical
-attack present on both sets of hardware, factory-new from different
-manufacturers. This is exceptionally unlikely.
-
+generating the sensitive data, with the intention of making it more easily
+guessed by a third party. For example, a variant of the Trojan.Bitclip
+attack replaces keys displayed on your screen, or stored in your clipboard,
+with insecure keys.
+
+By using eternally quarantined hardware, any malware attempting to take advantage
+of flawed data would likely have already been present when the system arrived
+from the manufacturer. For example, [the Lenovo Service Engine rootkit](https://thehackernews.com/2015/08/lenovo-rootkit-malware.html)
+or [the Dell W32.Spybot worm](https://www.theregister.co.uk/2010/07/23/dell_malware_update/).
+
+These attacks are defeated by detecting them before the flawed data is used.
+This is done by replicating the entire data generation process on two
+sets of eternally quarantined hardware from different manufacturers. If the
+process generates identical data on both sets of hardware, it is exceptionally
+unlikely that the data is flawed. Identical attacks would have to be present on
+both sets of hardware, both of which are factory-new and both of which are from
+different manufacturers.
## Bitcoin Core and GlacierScript
-Glacier uses the [Bitcoin Core](https://bitcoincore.org/)
-software for all cryptographic and financial operations, as its open source code
-is the most trustworthy. This is due to its track record of securing large amounts
-of money for many years, and the high degree of code review scrutiny it has
-received.
+Glacier uses [Bitcoin Core](https://bitcoincore.org/) for all cryptographic and
+financial operations. Its open source code has proven to be the most trustworthy,
+most secure, and has had the highest degree of code review scrutiny over many years.
-Glacier also utilizes GlacierScript, a software program that
-automates much of the manual work involved in executing the protocol.
-GlacierScript's [open source code](https://github.com/GlacierProtocol/GlacierProtocol) is straightforward and extensively
-commented to facilitate easy review for flaws or vulnerabilities.
+Glacier also utilizes GlacierScript to automate much of the manual work involved
+in executing the protocol. GlacierScript's [open source code](https://github.com/GlacierProtocol/GlacierProtocol)
+is straightforward, and extensively commented, to facilitate easy review for flaws
+or vulnerabilities.
-## Protocol Output
+## Protocol output
The end result of the Glacier protocol is a set of paper information
packets, one for each private key needed for the multisignature withdrawal
policy. Each packet includes the following information:
-* One **private key** -- an alphanumeric string used to secure the funds
-* The **cold storage address** -- an alphanumeric string designating the virtual "location" of the funds
-* The **"redemption script"** -- an additional code needed to access funds, shared
+* **One private key**: an alphanumeric string used to secure the funds
+* **One cold storage address**: an alphanumeric string designating the virtual
+"location" of the funds
+* **One redeem script**: an additional code needed to access funds, shared
by all private keys.
-Technical details: The Glacier protocol reuses Bitcoin addresses. See the
-[design document](../design-doc/overview.md) for a detailed analysis.
+Technical detail: The Glacier protocol reuses Bitcoin addresses. See the
+[design document](/docs/design-doc/overview) for a detailed analysis.
-## Protocol Cost
+## Protocol cost
-The Glacier protocol requires over $600 in equipment, and approximately 8 hours of work to perform an initial cold storage deposit. This excludes time for:
+Performing an initial cold storage deposit requires a not-insignificant investment
+in hardware (see [Hardware required](/docs/before-you-start/hardware)), along with
+approximately 8 hours of work. This excludes time for:
* Obtaining equipment
* Printing documents
* Downloading files
-* Physically storing the resulting Bitcoin keys
+* Physically storing the private keys
Subsequent deposits and withdrawals re-use the same equipment and take a
fraction of the time.
-## No Formal Support
+## No formal support
As a free, volunteer-developed community project, there is no formal support
-channel for Glacier should you encounter any issues. However, you may be able to
-ask advice of community members on our [Gitter chat room](https://gitter.im/glacierprotocol/Lobby)
+channel for Glacier. However, advice may be available from community
+members on the Glacier [Gitter chat room](https://gitter.im/glacierprotocol/Lobby)
or other Bitcoin community forums.
-## Privacy Considerations
+## Privacy considerations
-Because the Bitcoin blockchain is public, the way you route and store funds has
-privacy implications. For example, any person to whom you give your cold storage
-address (because, for example, they're sending you funds which you want to keep
-in cold storage) can see your total cold storage balance. This is easy to do
-with many free services (e.g.
-[Blockr](https://www.coinbase.com/) ).
+Because the Bitcoin blockchain is public, the routing and storage of funds has
+privacy implications. For example, any person receiving a cold storage
+address for the purpose of sending funds, will be able to see the total cold
+storage balance. This is easy to do with many free services, for example,
+[BlockCypher](https://live.blockcypher.com).
This is true not just of individuals, but entities. That is, any online wallet
-service which you use to send funds to cold storage can see your cold storage
-balance, and may deduce that it belongs to you. They may, of course, also choose
+service used to send funds to cold storage can see the cold storage
+balance, and may deduce the owner. The online wallet may, of course, also choose
to share this information with others.
-If this is a concern for you, the easiest way to keep your
-cold storage balance private from a particular entity is to route the
-payment through one (or more) intermediary addresses before sending it to
-your cold storage address, with a few transactions going to each
+If privacy is a concern, the easiest way to keep a cold storage balance private is
+to route the payment through one (or more) intermediary addresses before sending
+it to the cold storage address, with a few transactions going to each
intermediate address. This does not provide perfect privacy, but each
intermediate address provides increasing levels of obfuscation and
uncertainty.
-If privacy is very important to you, you might consider using
-a service like
-[Shapeshift](https://shapeshift.io/#/coins)
-to exchange your Bitcoins for an more anonymous cryptocurrency, such as
-[Monero](http://monero.org/),
-and then exchange them back to Bitcoins.
-However, this will cost you fees, and importantly, it requires you trust the
-operator of the exchange service not to steal or lose your
-funds.
-
-[This guide](https://bitcoinnewsmagazine.com/how-to-use-monero-to-anonymize-bitcoin/)
-gives additional detail about how to increase Bitcoin anonymity using Monero &
-Tor.
-
-## Lower-security Protocol Variants
-
-If you are willing to accept lower security for lower cost, you can do so with only slight modifications:
-
-1. **Perform this protocol using only one quarantined computer**. Glacier protocol
-repeats all operations on two computers to detect defects or tampering in
-the key generation process. However, this is costly and adds significantly
-to the labor required to execute the protocol. The risks it mitigates are
-small: that malware conducting flawed key-generation attacks found its way
-onto the eternally quarantined systems, or that the computer firmware was
-tampered with at the manufacturer to include such malware. If you are
-willing to accept this risk, you could skip buying the parallel hardware
-stack (and needing the second setup computer) and skip the process of
-re-generating and verifying keys & transactions on the parallel hardware
-stack.
-
-2. **Use existing hardware**. An even lower-security variant is to use nothing
-but existing laptops you already possess, disabling all network
-connections during protocol execution, instead of purchasing new
-quarantined hardware. This fails to protect against some malware
-attacks, but provides additional savings in cost and effort.
-
-Such as an
-[existing infection of a laptop's firmware](https://www.youtube.com/watch?v=sNYsfUNegEA),
-malware which overrides
-OS settings to disable wireless connectivity, or certain undiscovered
-vulnerabilities in the software used by the protocol.
-
-These modifications are left as an exercise to the reader.
-
-## Out of scope
-
-There's always more one could do to increase security. While
-Glacier is designed to provide strong protection for almost everyone, some
-situations (e.g. being the focus of a targeted attack by a sophisticated,
-well-resourced criminal organization) are beyond its scope.
-
-For some
-additional security precautions beyond those provided in the standard
-protocol, see the [possible improvements to Glacier](/docs/extend/improvements/).
+If privacy is a *major* concern, consider exchanging bitcoin for a privacy coin,
+then exchanging the privacy coin back to bitcoin. Each exchange will incur a fee
+and, more importantly, will require trust that the exchange service will not
+steal/lose the funds, or reveal personal details. The exact details of this process
+is outside the scope of this document.
+
+## Scope limits
+
+Security can always be improved. While Glacier is designed to provide strong
+protection for most, some situations, for example, being the focus of a targeted
+attack by a sophisticated, well-resourced criminal organization, are beyond its scope.
+
+For some additional security precautions beyond those provided in the standard
+protocol, see the [possible improvements to Glacier](/docs/extend/improvements/)
+section.
\ No newline at end of file
diff --git a/_docs/before-you-start/structure.md b/_docs/before-you-start/structure.md
index 4993dcf..d862e54 100644
--- a/_docs/before-you-start/structure.md
+++ b/_docs/before-you-start/structure.md
@@ -4,102 +4,97 @@ description: This page explains the overall structure of Glacier, the
step-by-step protocol for storing bitcoins in a highly secure way
---
-The overall Glacier protocol consists of several distinct subprotocols:
+The Glacier protocol consists of several distinct sub-protocols:
-* **Setup**: Prepares hardware,
-and downloads and verifies needed software & documentation.
-* **Deposit**: For securely storing bitcoins.
-* **Withdrawal**: For transferring some or all of your stored funds to another
+* **Setup**: Preparing the hardware, downloading and verifying the software and
+documentation.
+* **Deposit**: Storing the bitcoin.
+* **Withdrawal**: Transferring some or all stored bitcoin to another
bitcoin address.
-* **Viewing**: For viewing the balance of your funds in secure storage.
-* **Maintenance**: For ensuring funds in cold storage remain accessible and
+* **Viewing**: Viewing the balance held in secure storage.
+* **Balance and maintenance**: Ensuring the bitcoin in cold storage remains accessible and
secure.
-## Sensitive Data
+## Sensitive data
*Critically-sensitive data* (e.g. private keys) will be highlighted in red,
like this: critically-sensitive-data-here.
-*Critically* sensitive data can be used by thieves to to steal your bitcoins. If
-you follow the protocol precisely, your critically sensitive data will remain
-secure.
+*Critically* sensitive data can be used by thieves to to steal bitcoin. Follow
+the protocol precisely to ensure critically sensitive data remains secure.
-Do *not* do anything with critically sensitive data that the protocol does not
-specifically instruct you to. In particular:
+Do *not* do anything with critically sensitive data that is not *specifically*
+outlined in the protocol. In particular:
-* Never send it over email or instant messenger
-* Never save it to disk (hard drive, USB drive,
-etc.)
-* Never paste or type it into any non-eternally-quarantined
+* *Never* send critically sensitive data over email or instant messenger
+* *Never* save critically sensitive data to disk (hard drive, USB drive, etc.)
+* *Never* paste or type critically sensitive data into any non-eternally-quarantined
device
-* Never take a picture of it
-* Never let any untrusted person see it
-
-*Moderately-sensitive data* (e.g. a cold storage address or redemption
-script) will be highlighted in yellow, like this:
-moderately-sensitive-data-here.
+* *Never* take a picture of critically sensitive data
+* *Never* allow critically sensitive data to be seen by any untrusted person
-*Moderately* sensitive data impacts
-privacy, but does not directly impact security. It cannot be used to
-steal your bitcoins, but it *can* be used to see how many bitcoins you own
-(if someone knows that the moderately sensitive data in question belongs
-to you).
+*Moderately-sensitive data* (e.g. a cold storage address or redeem script) will
+be highlighted in yellow, like this: moderately-sensitive-data-here.
-It does indirectly impact security, in that if someone knows you own a lot of
-difficult-to-trace money, they have some incentive to rob, extort, or attack you
-to get it.
+*Moderately* sensitive data impacts privacy, because it can be used to see the total
+amount of bitcoin in storage, but does not directly impact security since it cannot
+be used to withdraw the funds. However, it can indirectly impact security in
+that potential thieves, knowing the amount held, may have the incentive to rob or
+extort.
The protocol recommends storing copies of moderately-sensitive
-data electronically, in a "conventionally secure" manner (for example, in
-a password manager such as
-[1Password](https://1password.com/)). If you're particularly
-concerned about privacy, you *can* forego electronic storage, because the protocol
-also stores copies of moderately-sensitive data in cold storage with each private
-key. However, this is not recommended.
-
-This means that knowledge of your cold storage balance will be as secure as
-access to any accounts which have their credentials stored in your password
-manager. For most people, this is sufficient.
-
-If you use only hardcopies, you'll need to manually type in a large amount of
-gibberish data, by hand, with no errors, every time you withdraw funds from
-cold storage.
-
-### Terminal Usage
-
-Many protocol steps involve
-typing commands into a *terminal window*. Working in a terminal window is
-analogous to working under the hood of a car. It allows you to give the
-computer more precise commands than you can through the regular
+data electronically, in a "conventionally secure" manner, for example, in
+a password manager such as [1Password](https://1password.com/). This means that knowledge
+of the cold storage balance will be as secure as access to other credentials stored in
+the password manager. For most people, this is sufficient.
+
+Although not recommended, the electronic storage of moderately-sensitive data can be
+omitted to improve privacy, because the protocol also stores copies of
+moderately-sensitive data in cold storage with each private key. It should be considered,
+though, that moderately-sensitive data stored on paper will need to be typed by hand
+every time funds are to be withdrawn from cold storage. The lengthy, complex nature of
+this data makes errors likely.
+
+### Terminal usage
+
+Many protocol steps involve typing commands into a terminal window. Analogous to
+working under the hood of a car, this allows the user to give the
+computer more precise commands than can be given through the regular
interface.
Commands to be entered into a terminal window will be
displayed in a fixed-width font like this:
```
-$ echo "everything after the $ could be copy-pasted into a terminal window"
+$ echo "all text after the $, on both lines, should either be copy-pasted from
+this document or manually typed into a terminal window"
+```
+
+The `$` at the beginning of the line signifies that the text which follows is to be
+executed from the terminal. The actual prompt varies depending on the operating
+system and its configuration; it may be `$`, `>` , or something else. Usually,
+the terminal will show additional information preceding every prompt, such as
+a computer name, user ID and/or folder name.
+
+In the above example, the text splits across two lines because of document margins.
+Each line is *not* a separate command; it is one command to be entered in its
+entirety. This is clear because there is no `$` at the beginning of the second
+line. Proceed carefully.
+
+Commands requiring user-specific information will be highlighted like this:
+
+$ sudo dd if=ubuntu-16.04.1-desktop-amd64.img.dmg of=USB-device-identifier bs=1m
+
+
+This is because the USB device identifier will vary from installation to installation. In this example, the user is expected to replace the USB-device-identifier with the USB device identifier particular to the local machine:
+```
+$ sudo dd if=ubuntu-16.04.1-desktop-amd64.img.dmg of=/dev/disk2 bs=1m
```
-The `$` at the beginning
-of the line represents a *terminal prompt*, indicating readiness for user
-input. The actual prompt varies depending on your operating system and its
-configuration; it may be `$` , `>` , or something else. Usually the terminal
-will show additional information (such as a computer name, user ID and/or
-folder name) preceding every prompt.
-
-In the above example, the text
-splits across two lines because of the margins of this document. Each line
-is *not* a separate command; it is all one command, meant to be entered
-all at once. This is clear because there is no terminal prompt at the
-beginning of the second line.
-Proceed Carefully
-
-If you encounter
-**anything that is different** from what the protocol says you should
-expect, **the recommendation is that you stop and seek help** unless your
-expert opinion gives you high confidence that you understand all possible
-causes and implications of the discrepancy.
-
-**In general, follow the
-protocol carefully, keep track of what step you are on, and double-check
-your work**. Any errors or deviations can undermine your security.
+An explanation of how to provide the required information will always be given.
+
+**In general, follow the protocol carefully, keep track of the current step and
+double-check all work**. Any errors or deviations can undermine the security of the
+process. If the terminal response is in any way different to the expected response stated
+in the protocol, **stop and seek help**. Continue only if all possible causes and
+implications of the discrepancy are understood.
\ No newline at end of file
diff --git a/_docs/deposit/generate-cold-storage-data.md b/_docs/deposit/generate-cold-storage-data.md
index 926d4ec..48adce3 100644
--- a/_docs/deposit/generate-cold-storage-data.md
+++ b/_docs/deposit/generate-cold-storage-data.md
@@ -48,10 +48,10 @@ prepare your quarantined workspace.
1. Type "DICE ENTROPY" into both Quarantined Scratchpads.
2. Roll 62 six-sided dice, shaking the dice thoroughly each roll.
62 dice rolls corresponds to 160 bits of entropy. See the
- [design document](../design-doc/overview.md) for details.
+ [design document](/docs/design-doc/overview) for details.
3. If you are rolling multiple dice at the same time, read the
dice left-to-right. **This is important.** Humans are
- [horrible at generating random data](http://journals.plos.org/plosone/article?id=10.1371/journal.pone.0041531)
+ [horrible at generating random data](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0041531)
and great at noticing patterns. Without a consistent heuristic like
"read the dice left to right", you may subconsciously read them in a
non-random order (like tending to record lower numbers first).
@@ -77,9 +77,8 @@ prepare your quarantined workspace.
3. **On the Q1 computer** enter the following command. You'll need to supply
the number of keys required for your multisignature withdrawal policy
(4 by default).
-
- $ ./glacierscript.py entropy --num-keys number-of-keys-here
-
+ $ ./glacierscript.py entropy --num-keys number-of-keys-here
+
Example:
```
@@ -104,10 +103,9 @@ prepare your quarantined workspace.
In the command below, you'll need to specify the number of keys required
by your multisignature withdrawal policy.
-
- $ ./glacierscript.py create-deposit-data -m required-keys \
+ $ ./glacierscript.py create-deposit-data -m required-keys \
-n total-keys
-
+
For example, for a 2-of-4 withdrawal policy:
```
diff --git a/_docs/design-doc/overview.md b/_docs/design-doc/overview.md
index fecef35..cf40585 100644
--- a/_docs/design-doc/overview.md
+++ b/_docs/design-doc/overview.md
@@ -5,7 +5,7 @@ description: Here you can find the design documents behind Glacier, the
---
If you want to learn more about the security considerations for Glacier,
-check the Glacier design document:
+check the design document:
* [v0.9 Beta (latest version)]({{ site.baseurl}}/assets/design-doc-v0.9-beta.pdf)
* [v0.1 Alpha]({{ site.baseurl}}/assets/design-doc-v0.1-alpha.pdf)
diff --git a/_docs/extend/ecosystem.md b/_docs/extend/ecosystem.md
index d52e42d..4cabafa 100644
--- a/_docs/extend/ecosystem.md
+++ b/_docs/extend/ecosystem.md
@@ -4,11 +4,11 @@ description: Here's a list of how the Bitcoin ecosystem could be improved with
increased security.
---
-The Glacier protocol is lengthy and complex because the tools for high-security cold storage do not exist. This appendix briefly outlines some of the tool functionality that would address this gap. For additional technical details, see the Glacier [design document](../design-doc/overview.md).
+The Glacier protocol is lengthy and complex because the tools for high-security cold storage do not exist. This appendix briefly outlines some of the tool functionality that would address this gap. For additional technical details, see the [design document](/docs/design-doc/overview).
Ideally, the Bitcoin community (and other cryptocurrency communities) will create these tools as soon as possible and render Glacier obsolete. We invite inquiry and consultation by others interested in developing these tools.
-## Cold Storage Hardware Wallets
+## Cold storage hardware wallets
* Function like conventional hardware wallets, but
eternally quarantined (no wireless or wired connections)
diff --git a/_docs/extend/improvements.md b/_docs/extend/improvements.md
index 69fd274..c4d991e 100644
--- a/_docs/extend/improvements.md
+++ b/_docs/extend/improvements.md
@@ -17,10 +17,10 @@ Printing QR codes on the Cold Storage Information Page would be
another way to avoid the need to manually transcribe the deposits and
withdrawals
-## No Address Reuse
+## No address reuse
Currently, Glacier reuses addresses for
-both depositing and withdrawing funds. As discussed in the [protocol design
-document](../design-doc/overview.md), this has both privacy and security implications.
+both depositing and withdrawing funds. As discussed in the protocol [design
+document](/docs/design-doc/overview), this has both privacy and security implications.
This could be
implemented with HD wallets, which would allow one to generate one master
@@ -34,13 +34,13 @@ be given as to whether there is another way to safely test funds access,
perhaps using something like the signrawtransaction Bitcoin Core
RPC.
-## BIP39 Mnemonic Support
+## BIP39 mnemonic support
[BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) supports the creation of private keys
encoded as an English mnemonic for ease and reliability of transcription.
It's not yet supported by Glacier because it's not supported by Bitcoin
Core.
-## Sign Withdrawal Transactions With Individual Signatures
+## Sign withdrawal transactions with individual signatures
Bringing
multiple private keys together in the same physical location for the
Withdrawal Protocol entails risk (they could be physically stolen). It
@@ -49,7 +49,7 @@ a time, probably by bringing a QR-encoded physical hardcopy of the
partially-signed transaction to the storage location of each private
key.
-## Consider Shamir's Secret Sharing or Vanilla Multisig vs. P2SH Transactions
+## Consider Shamir's Secret Sharing or vanilla multisig vs. P2SH transactions
Glacier currently uses P2SH transactions. This allows all
signatories storing private keys to view the user's balance, because
a copy of the redeem script must be kept with each private key.
@@ -63,19 +63,19 @@ using [Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_
the number of keyholders, but would require additional cryptographic
software be integrated into Glacier.
-## Automate Quarantined USB creation
+## Automate quarantined USB creation
Many of the steps for creating the Quarantined USBs could be
automated in a simple script.
-## Security With Biased Dice
-Assess integration of this paper and/or [this algorithm](http://pit-claudel.fr/clement/blog/generating-uniformly-random-data-from-skewed-input-biased-coins-loaded-dice-skew-correction-and-the-von-neumann-extractor/) so that the quality of
+## Security with biased dice
+Assess integration of this paper and/or [this algorithm](https://pit-claudel.fr/clement/blog/generating-uniformly-random-data-from-skewed-input-biased-coins-loaded-dice-skew-correction-and-the-von-neumann-extractor/) so that the quality of
our randomness is not vulnerable to dice bias.
-## Entropy Quality Testing
-Use an entropy test suite such as [ent](http://www.fourmilab.ch/random/) to verify the quality of
+## Entropy quality testing
+Use an entropy test suite such as [ent](https://www.fourmilab.ch/random/) to verify the quality of
generated entropy before it's used.
-## Bitcoin Core Version
+## Bitcoin Core version
Pinning Currently, we download Bitcoin Core on to the Quarantined App
USBs via the Ubuntu Package archive. However, because Bitcoin is
a privately-managed archive, it only hosts the latest release, rather than
diff --git a/_docs/extend/security.md b/_docs/extend/security.md
index 3334827..2abea9e 100644
--- a/_docs/extend/security.md
+++ b/_docs/extend/security.md
@@ -44,7 +44,7 @@ software (including a non-Linux-derived OS and a different Bitcoin wallet),
different smartphones (and different smartphone software, i.e. QR code
readers). Different software stacks eliminate the risk that a software bug or
vulnerability may generate a flawed key. See the
-[design document](../design-doc/overview.md) for details on why this risk is
+[design document](/docs/design-doc/overview) for details on why this risk is
small enough to justify leaving it unaddressed in the formal protocol.
* **Dedicated pair of environments for each private key**: Use extra
environments such that each environment only touches one key both when
@@ -94,7 +94,7 @@ or
Examples include
[Kanguru drives](https://www.kanguru.com/secure-storage/defender-secure-flash-drives.shtml)
and
-[IronKey drives](http://www.ironkey.com/en-US/encrypted-storage-drives/250-basic.html).
+[IronKey drives](https://www.ironkey.com/en-US/encrypted-storage-drives/250-basic.html).
* **Purchase a factory-new printer**: Printers can have malware, which could
conceivably interfere with printing the hardcopy of the Glacier document. Use
a new printer for printing the Glacier document. Choose one without wireless
@@ -137,8 +137,8 @@ there should be a process for checking on them periodically to make sure they ar
not lost or damaged.
* **Durable storage medium**: TerraSlate paper is extremely rugged, but you
might also consider laminating the paper for additional protection. You'll
-need a [thermal laminator](http://a.co/cZBN1YU) and
-[laminating pouches](http://a.co/ifISzje). An
+need a [thermal laminator](https://a.co/cZBN1YU) and
+[laminating pouches](https://a.co/ifISzje). An
even more durable approach would be to engrave the private keys in
metal.
* **High-security vaults**: Store keys in high-security vaults that
diff --git a/_docs/overview.md b/_docs/overview.md
deleted file mode 100644
index 4f44007..0000000
--- a/_docs/overview.md
+++ /dev/null
@@ -1,162 +0,0 @@
----
-title: About Glacier
-description: Glacier is a step-by-step protocol for long-term storage of
- Bitcoins, in an offline and secure way.
-redirect_from:
- - /docs/
----
-
-Glacier is a step-by-step protocol for storing bitcoins in a highly secure
-manner. It is intended for:
-
-* **Personal storage**: Glacier does not address institutional security
-needs such as internal controls, transparent auditing, and preventing access
-to funds by a single individual.
-* **Large amounts of money ($100,000+)**: Glacier thoroughly considers corner
-cases such as obscure vectors for malware infection, personal estate
-planning, human error resulting in loss of funds, and so on.
-Even if your Bitcoin holdings are more modest, it's worth considering using
-Glacier. If Bitcoin proves successful as a global currency, it will appreciate
-10x (or much more) in the coming years. Security will become increasingly
-important if your holdings appreciate and Bitcoin becomes a more attractive
-target for thieves.
-The "Protocol Overview" section also describes some lower-security, lower-cost
-approaches to self-managed storage that may be more appropriate for smaller
-amounts of funds.
-* **Long-term storage**: Glacier not only considers the Bitcoin security
-landscape today, but also a future world where Bitcoin is much more valuable
-and attracts many more security threats.
-* **Infrequently-accessed funds**: Accessing highly secure bitcoins is
-cumbersome and introduces security risk through the possibility of human
-error, so it is best done infrequently.
-* **Technically unskilled users**: Although the Glacier protocol is long, it is
-clear and straightforward to follow. No technical expertise is required.
-
-The Glacier protocol covers bitcoin storage, not procurement. It assumes you
-already possess bitcoins and wish to store them more securely.
-
-If you are already familiar with Bitcoin security concepts and are certain that
-you want high security cold storage, you may prefer to read
-[Trusting This Protocol](#trusting-this-protocol) and then skip to the section
-[Choosing a Multisignature Withdrawal Policy](/docs/overview/multi-signature-security#choosing-a-multisignature-withdrawal-policy).
-
-## Trusting this protocol
-
-Funds secured using Glacier can only be as secure as its design.
-Here's what you can trust about this protocol:
-* **Expert advisors**: The development of Glacier was guided with input from
-Bitcoin technology and security experts. See our advisor list.
-* **Open source**: GlacierScript, the Glacier companion software, is open
-source. The code is straightforward and well-commented to facilitate easy review
-for flaws or vulnerabilities. [View it on Github](https://github.com/GlacierProtocol/GlacierProtocol).
-* **Community review**: The protocol has evolved in conjunction with the wider
-Bitcoin community. Early versions were circulated during development, and
-community feedback integrated. [See our list of contributors](/docs/contribute/acknowledgments/).
-* **Natural selection**: All documentation and code related to this protocol is
-under open licenses (Creative Commons for the document, MIT license for the
-code), enabling others to publish their own revisions. Inferior alternatives
-will tend to lose popularity over time.
-
-If you like, you may review the [design document](/docs/design-doc/overview)
-for details on the technical design.
-
-## Background
-
-### Self-Managed Storage vs. Online
-
-Let's start by assessing whether Glacier is right for you.
-
-There is no such thing as perfect security. There are only degrees of security,
-and those degrees come at a cost (in time, money, convenience, etc.) So the
-first question is: How much security are you willing to invest in?
-For most people, most of the time, the authors recommend storing Bitcoin using a
-high-quality online storage service. The pros and cons of the various online
-services are beyond the scope of this document, but most popular ones are fairly
-secure and easy to use. Some popular options are
-[Blockchain](https://blockchain.info/),
-[Coinbase](https://www.coinbase.com/),
-[Gemini](https://gemini.com/),
-and [Kraken](https://www.kraken.com/).
-
-However, all online storage services still come with some notable risks
-which self-managed storage does not have:
-
-1. **Identity spoofing**: Your account on the service could be hacked (including
-through methods such as identity theft, where someone convinces the service they
-are you).
-2. **Network exposure**: Online services still need to transmit security-critical
-information over the Internet, which creates an opportunity for that information
-to be stolen. In contrast, self-managed storage can be done with no network
-exposure.
-3. **Under constant attack**: Online services can be hacked by attackers from
-anywhere in the world. People know these services store lots of funds, which
-makes them much larger targets. If there's a flaw in their security, it's more
-likely to be found and exploited.
-4. **Internal theft**: They have to protect against internal theft from a large
-group of employees & contractors.
-5. **Intentional seizure**: They have the ability (whether of their own volition,
-or under pressure from governments) to seize your funds.
-There is historical precedent for this, even if funds are not suspected of
-criminal involvement. In 2010,
-[Cyprus unilaterally seized many bank depositors' funds ](https://www.theguardian.com/world/2013/mar/25/cyprus-bailout-deal-eu-closes-bank)
-to cope with an economic crisis. In 1933, the US abruptly
-[demanded citizens surrender almost all gold they owned to the government](https://en.wikipedia.org/wiki/Executive_Order_6102).
-Regardless of how one views the political desirability of these particular
-decisions, there is precedent for governments taking such an action, and one
-cannot necessarily predict the reasons they might do so in the future.
-Furthermore,Bitcoin still operates in a political and legal grey zone, which
-increases these political risks.
-
-Some online wallet services have insurance to cover losses, although that
-insurance doesn't protect against all of these scenarios, and often has limits
-on the amount insured.
-
-These risks are not theoretical. Many online services have lost customers' funds
-(and not reimbursed them), including
-[Mt. Gox](https://www.bloomberg.com/news/articles/2014-02-28/mt-gox-exchange-files-for-bankruptcy),
-[Bitfinex](http://www.bbc.com/news/technology-37009319),
-and many more.
-
-Recently, some providers are rolling out services which are a hybrid
-of an online service and self-managed storage. Examples include
-[Coinbase's multisig vault](https://www.coinbase.com/vault)
-and [Green Address](https://greenaddress.it/en/).
-The design of these services
-significantly reduces (though does not eliminate) the risks described above.
-
-However, they also require some care and technical competence to securely
-manage the electronic "keys" which provide access to funds.
-
-Many people do use online or hybrid solutions to store sizeable amounts of
-money. We recommend self-managed storage for large investments, but ultimately
-it's a personal decision based on your risk tolerance and costs you're willing
-to pay (in money and time) for security.
-
-Glacier focuses exclusively on self-managed storage.
-
-### Glacier vs. Hardware Wallets
-
-Many people who choose
-self-managed storage (as opposed to an online storage service) use "hardware
-wallets" such as the
-[Trezor](https://trezor.io/),
-[Ledger](https://www.ledgerwallet.com/),
-and [KeepKey](https://www.keepkey.com/)
-to store their bitcoins. While these are great products that provide strong security,
-Glacier is intended to offer an even higher level of protection than today's
-hardware wallets can provide.
-
-The primary security consideration is that
-all hardware wallets today operate via a physical USB link to a regular
-computer. While they employ extensive safeguards to prevent any sensitive
-data (such as private keys) from being transmitted over this connection,
-it's possible that an undiscovered vulnerability could be exploited by
-malware to steal private keys from the device.
-
-For details on this and other security considerations, see the
-"No Hardware Wallets" section of the [design document](/docs/design-doc/overview)
-As with online multisig
-vaults, many people do use hardware wallets to store sizeable amounts of
-money. We personally recommend Glacier for large investments, but ultimately
-it's a personal decision based on your risk tolerance and costs you're
-willing to pay (in money and time) for security.
diff --git a/_docs/overview/about.md b/_docs/overview/about.md
new file mode 100644
index 0000000..f5dbf9d
--- /dev/null
+++ b/_docs/overview/about.md
@@ -0,0 +1,111 @@
+---
+title: About Glacier
+description: Glacier is a step-by-step protocol for long-term storage of
+ Bitcoins, in an offline and secure way.
+redirect_from:
+ - /docs/
+---
+
+## A step-by-step, highly secure protocol for storing bitcoin
+
+It thoroughly considers corner cases such as obscure vectors for malware
+infection, personal estate planning and human error resulting in loss of funds, as
+well as the future Bitcoin landscape where bitcoin is much more valuable and
+attracting many more security threats.
+
+### Intended for
+
+* **Personal storage**: Bitcoin owned solely by a single individual.
+* **Investment-level value**: Bitcoin holdings around the level of a small
+property in the local economy. Consideration should also be given to potential
+future value appreciation.
+* **Long-term storage**: Several months to years.
+* **Technically unskilled users**: No technical expertise is required. Although
+the Glacier protocol is long, it is clear and straightforward to follow.
+
+### Not intended for
+
+* **Institutional storage**: Internal controls, transparent auditing, and
+preventing access to funds by a single individual are outside the scope of this
+document.
+* **Frequently-accessed funds**: Accessing highly secured bitcoin is cumbersome,
+introducing security risk through the possibility of human error with each
+interaction.
+* **Procurement**: This document covers bitcoin storage, not procurement. It assumes
+bitcoin has been procured and is ready to store.
+
+### Protocol credentials
+
+* **Expert advisors**: Development is guided with input from Bitcoin technology and
+security experts. See the [advisor list](https://glacierprotocol.org/contributors/) and [contributor list](/docs/contribute/acknowledgments/).
+* **Open source**: The [design document](/docs/design-doc/overview), the [protocol document](https://github.com/GlacierProtocol/glacierprotocol.github.io)
+and the [GlacierScript](https://github.com/GlacierProtocol/GlacierProtocol) companion
+software are all open source. This allows for continuous peer review and
+examination to eliminate flaws and vulnerabilities. The protocol has evolved in
+conjunction with the wider Bitcoin community, and the code is straightforward and
+well commented. Both are available on Github.
+
+## Alternatives
+There is no such thing as perfect security, only degrees of security with corresponding
+trade-offs in time, money, convenience, etc. Glacier focuses exclusively
+on self-managed storage, but there are cheaper, lower security and more convenient options.
+
+A reader familiar with Bitcoin security concepts may prefer to skip to the section
+[Choosing a Multisignature Withdrawal Policy](/docs/overview/multi-signature-security#choosing-a-multisignature-withdrawal-policy).
+
+### Online storage
+
+For most people, most of the time, storing Bitcoin using a high-quality online storage
+service is sufficient. The pros and cons of the various online services are beyond the
+scope of this document. However, all online storage services entail risks which are
+not present in a self-managed storage system:
+
+1. **Identity spoofing**: Online accounts can be compromised, allowing a hacker to
+assume the identity of a legitimate user.
+2. **Network exposure**: Online services need to transmit security-critical
+information over the Internet, which creates an opportunity for that information
+to be stolen. In contrast, self-managed storage can be done with no network
+exposure.
+3. **Under constant attack**: Online services can be hacked by attackers from anywhere in
+the world at any time of the day, week or year.
+4. **Vastly larger target**: Customer funds are a part of a considerably larger asset pool, making
+them much more attractive targets for hackers.
+5. **Internal theft**: A large group of employees & contractors are trusted with internal
+access to service funds.
+6. **Seizure by service**: The service has the ability to seize customer funds. There are
+examples where a hacked system has chosen to socialise its losses across all users. In 2016,
+[all users shared the total loss after Bitfinex was hacked](https://www.bbc.com/news/technology-37009319).
+There are also examples of withdrawals being closed before the company files for bankruptcy protection.
+In 2014, [Mt. Gox filed for bankruptcy after being hacked](https://www.bbc.co.uk/news/technology-25233230).
+Both scenarios lead to huge losses for customers.
+7. **Seizure by government decree**: Currently, in many countries, Bitcoin operates in a political
+and legal grey zone. There is historical precedence of citizen funds being seized without any
+suspicion of criminal activity. In 2010, [Cyprus unilaterally seized many bank depositors' funds](https://www.theguardian.com/world/2013/mar/25/cyprus-bailout-deal-eu-closes-bank)
+to cope with an economic crisis and, in 1933, [the US government demanded citizens surrender almost all gold](https://en.wikipedia.org/wiki/Executive_Order_6102). Similar action during a future financial
+crisis cannot be discounted.
+
+Some online wallet services have insurance to cover losses, although that
+insurance doesn't protect against all of these scenarios, and often has limits
+on the amount insured.
+
+Hybrid services, combining features of online and self-managed storage, are available. The design
+of these services reduce, without eliminating entirely, some of the risks described above. However,
+they still require care and technical competence to securely manage the electronic "keys" which
+provide access to funds.
+
+### Hardware wallets
+
+Hardware wallets can provide a form of self-managed storage with good security. Again, the pros
+and cons of the various hardware wallets are beyond the scope of this document. However, all
+hardware wallets entail risks which are not present in a system adhering to Glacier:
+
+1. **USB link**: All hardware wallets operate via a physical USB link to a regular computer. While
+they employ extensive safeguards to prevent any sensitive data (such as private keys) from being
+transmitted over this connection, it is possible that an undiscovered vulnerability could be
+exploited by malware to steal private keys from the device.
+2. **Potential tampering**: Verification that the hardware or software has not been tampered with is
+nearly impossible. An attacker could compromise the manufacturing processes, or ship a malicious
+device that looks like the hardware wallet you ordered.
+
+For details on this and other security considerations, see the "No Hardware Wallets" section of the
+[design document](/docs/design-doc/overview).
\ No newline at end of file
diff --git a/_docs/overview/attack-surface.md b/_docs/overview/attack-surface.md
deleted file mode 100644
index 1ebb0fd..0000000
--- a/_docs/overview/attack-surface.md
+++ /dev/null
@@ -1,107 +0,0 @@
----
-title: Attack surface and failure points
-description: Learn about the attack survace for Glacier, the
- step-by-step protocol for storing bitcoins in a highly secure way
----
-
-This list describes the attack surface and other failure points for Glacier. We
-include only attacks and failures limited in scope to specific coins.
-Attacks and failures related to the Bitcoin ecosystem as a whole (newly
-discovered cryptographic flaws, critical Bitcoin protocol security or
-scalability failures, etc.) are not included as most are equally likely to
-impact the value of all Bitcoins whether or not they are secured with Glacier.
-
-This list assumes no security measures from [Extend Glacier security](../extend/security.md) are implemented.
-
-Most attacks require the presence of malware, either in or near the quarantined environment. We'll therefore inventory two layers of Glacier's attack surface:
-
-* Ways in which a malware infection might occur
-* Ways in which a critical failure might happen (possibly, but not necessarily, due to a malware infection)
-
-## Malware infection vectors
-
-* Software
- * OS/App software has malware (i.e. malicious code) built into official distributions. In particular, Glacier relies on the following packages and their dependencies NOT to distribute malicious code:
- * Ubuntu desktop
- * Bitcoin Core
- * zbar-tools (via Ubuntu Package archive)
- * qrencode (via Ubuntu Package archive)
- * Malware on Setup Computer infects Setup USB software AND malware on Setup USB infects Quarantined USB software AND checksum verifications produces false positives
- * Checksum false positives could happen becuase:
- * Malware might interfere with the verification process (or the display of its results).
- * The checksum verification software could be compromised.
- * Verifying the integrity of GnuPG requires one have access to a trusted installation of GnuPG, but many Glacier users won't have that. Glacier currently recommends users simply trust the version of GnuPG they download.
- * Malware on Setup Computer infects OS/App USB software AFTER checksum verification produces a true positive (i.e. before/during copying of software to the USB, or during USB ejection)
-* Firmware
- * Malware on Setup Computer infects Setup Boot USB firmware AND malware on Setup Boot USB infects Quarantined Boot/App USB
- * Laptop or USB firmware has malware in the shrinkwrapped package
-* Hardware
- * Laptop or USB hardware has "malware" in the shrinkwrapped package
-
-e.g. a [USB JTAG exploit](http://www.itnews.com.au/news/intel-debugger-interface-open-to-hacking-via-usb-446889) or chip-level backdoors (such as
-[this rootkit](https://www.wired.com/2016/06/demonically-clever-backdoor-hides-inside-computer-chip/)). "Malware" usually refers to software, but we're using it here more broadly to mean "computing technology which undermines the integrity of the computing environment in which it resides."
-
-## Failure scenarios
-
-### Electronic failures
-
-* Exfiltration of critically sensitive data (e.g. private keys)
- * A Quarantined Computer leaks critically sensitive data over a
- [side channel](https://en.wikipedia.org/wiki/Side-channel_attack)
- (possibly due to malware) AND complementary malware on a (networked or attacker-controlled) device in range steals the data
- * Visual side channel (does not require malware on the quarantined computer, since sensitive data is displayed on the screen as part of the protocol).
- If the protocol is followed, the attack surface here should be narrow, as users are instructed to block all visual side channels. However, at a minimum, they are using their smartphone for reading QR codes, and that has a camera on it.
- * Acoustic side channel, if inadequately blocked (i.e. insufficient sound blockage or masking noise). [See example](https://www.wired.com/2016/06/clever-attack-uses-sound-computers-fan-steal-data/).
- * Radio side channel ( [example 1](https://www.usenix.org/legacy/event/sec09/tech/full_papers/vuagnoux.pdf) , [example 2](http://cyber.bgu.ac.il/content/how-leak-sensitive-data-isolated-computer-air-gap-near-mobile-phone-airhopper) , [example 3](https://www.wired.com/2015/06/radio-bug-can-steal-laptop-crypto-keys-fits-inside-pita/) )
- * Seismic side channel ( [example](https://www.cc.gatech.edu/fac/traynor/papers/traynor-ccs11.pdf))
- * Thermal side channel ( [example](http://cyber.bgu.ac.il/blog/bitwhisper-heat-air-gap))
- * Magnetic side channel ( [example](http://fc15.ifca.ai/preproceedings/paper_14.pdf) )
- * Malware on a Quarantined Computer exfiltrates critically sensitive data via QR codes AND cooperating malware on the QR reading device steals the data.
- The risk of this scenario is negligible; unless the attacker simultaneously compromised every major smartphone QR reader with cooperating malware, any manipulation of QR codes would be quickly detected by people using non-compromised QR reader software, leading to widespread awareness and isolation of the threat. This makes it a very unattractive attack vector.
- * Critically sensitive data is leaked (intentionally or otherwise) as part of the payload of valid data (e.g. if the nonce used for a transaction signature contains bits of the private key)
-* Undetected generation of flawed sensitive data.
-(Requires compatible malware present on BOTH quarantined environments)
- * Private key creation is compromised to make keys easily guessable
- * Transaction creation is compromised to use output addresses belonging to an attacker, AND cooperating malware on a networked computer sends the malicious transaction before the manual address verification is done)
-
-### Physical failures
-
-* Two paper keys are stolen by an attacker
-* All (or all but one) paper keys are lost or destroyed
-* An attacker with physical line-of-sight to the laptop takes a photo of the screen while sensitive data is displayed
-* Malware on the quarantined machines writes sensitive data to persistent media (USB or laptop hard drive) AND the hardware is physically stolen afterward
-
-### Glacier protocol failures
-* Glacier hosting (i.e. DNS, Github, website hosting, etc.) is compromised
-to inject weaknesses into the protocol documentation or GlacierScript
-* Protocol delivery is compromised (e.g. with
-a man-in-the-middle attack on the user's computer or network) to deliver
-or display a weakened version of the protocol documentation or
-software
-* Protocol hardcopy is compromised (e.g. by malware to alter the user's hardcopy as it is printed)
-* A flaw in GlacierScript causes sensitive data to be leaked or flawed
-* Human error during protocol execution
-* Design failure in the protocol misses or inadequately addresses a risk
-
-For potential man-in-the-middle vulnerabilities, we mitigate this by signing a
-checksum of the Glacier document itself, and including steps in the protocol for
-users to verify the signature and checksum. But this is not foolproof:
-
-
-An attacker could remove the self-verification procedure from the protocol document,
-and many users would not notice.
-* An attacker could compromise our keypair and create a fraudulent signature
-(although this is exceedingly unlikely, due to Keybase's key verification systems)
-* The protocol document does begin with document self-verification on one Setup
-Computer. However, it doesn't guide the user through self-verification on the second
-Setup Computer. Nor does it have them re-verify the document when they first boot
-into Ubuntu on the Setup Computers to create the Quarantined Boot USBs. If the
-portion of the protocol document related to creating the Quarantined Boot USBs were
-compromised between the initial self-validation & the later re-validation (when
-creating the Quarantined App USBs), the user would probably not notice, even without
-a forged signature.
-* Protocol hardcopy is compromised (e.g. by malware to alter the user's hardcopy as
-it is printed)
-* A flaw in GlacierScript causes sensitive data to be leaked or flawed
-* Human error during protocol execution
-* Design failure in the protocol misses or inadequately addresses a risk
diff --git a/_docs/overview/key-concepts.md b/_docs/overview/key-concepts.md
index b2359cb..81b2f54 100644
--- a/_docs/overview/key-concepts.md
+++ b/_docs/overview/key-concepts.md
@@ -1,52 +1,67 @@
---
title: Key concepts
-description: Overview of some of the key concepts leveraged by Glacier to make
- sure your Bitcoin keys are kept safe.
+description: Overview of key concepts leveraged by Glacier to provide
+ Bitcoin key security
---
-## Private Key
-
-Your currency balance is effectively stored in the Bitcoin
-blockchain -- the global decentralized ledger. You can imagine a locked box
-with all of your bitcoins sitting inside of it. This box is unlocked with
-a piece of information known as "private key". (Some boxes require multiple
-private keys to unlock; see the section "Multisignature Security"
-below.)
-
-Unlike a password, a private key is not meant for you to remember.
-It's a long string of gibberish.
-The private key is what you need to keep
-secure. If anyone gets it, they can take your money. Unlike traditional
-financial instruments, there is no recourse. There is no company that is
-liable, because Bitcoin is a decentralized system not run by any person or
-entity. And no law enforcement agency is likely to investigate your
-case.
-
-## Offline Key Storage ("Cold Storage")
-
-You don't want to store your
-private key on any computer that's connected to the Internet ("hot
-storage"), because that exposes it to more hacking attempts. There are
-viruses out there that search computers for private keys and steal them
-(thereby stealing your money).
-
-One way to protect against this is by
-encrypting your private key, so even if a thief steals it, they can't read
-it. This helps, but is not foolproof. For example, a thief might install
-[keylogger malware](https://en.wikipedia.org/wiki/Keystroke_logging)
-so that they steal your password too.
-
-Online keys are
-inherently exposed to hackers. You therefore need to make sure your private
-key stays offline ("cold storage") at all times.
-
-## Paper Key Storage
-
-Because
-the private key is a relatively small piece of information, it can be stored
-on paper as easily as it can be stored on a computer. And when it comes to
-key storage, paper has various advantages compared to computers: It's always
-offline (no chance of accidentally connecting it to the Internet!), it's
-easy & cheap to make multiple copies for backups (and different keys for
-multisignature security -- see below), and it's not susceptible to
-mechanical failure.
+## Signing
+
+The process of using a private key to access bitcoins, referred to as "signing
+a transaction".
+
+## Private key
+
+A 256-bit number, usually expressed as a 64-character string of numbers and letters,
+which can unlock bitcoin balances stored in the Bitcoin blockchain, a global
+decentralized ledger.
+
+Unlike a password, a private key is not meant to be memorized.
+It is important to understand that the holder of the private key is the
+holder of the bitcoin and, unlike traditional financial instruments,
+there is no legal recourse in the event of the key falling into the
+hands of someone else. Bitcoin is decentralized, meaning there is no
+company, person or entity that is liable.
+
+## Single signature security
+
+This is analogous to storing coins in a padlocked box, with a single key and padlock.
+
+## Multisignature, or multisig, security
+
+Utilizes multiple private keys to provide greater security, while also protecting
+against total loss in the event of the loss of some keys.
+
+This is analogous to storing coins in a padlocked box, with multiple keys and
+padlocks which open in different combinations. See the [Multisignature Security](/docs/overview/multi-signature-security)
+section for more detail.
+
+## Redeem script
+
+Multisignature requires each of the multiple private keys to be accompanied by a
+redeem script. These scripts, all of which are identical, define how the keys
+combine to release funds. Losing all redeem scripts, if the recommended test
+withdrawal is not performed, leads to the total loss of funds. Performing the
+recommended test withdrawal means the redeem script can be found on the blockchain,
+assuming the cold storage address is still known.
+
+## Offline key storage
+
+Private keys should only ever be offline, or in "cold storage". They should
+never be stored on any internet-connected computer, or "in hot storage",
+because it provides an opportunity for hacking attempts or virus infection
+via the internet. Viruses can attack in many ways, including searching the
+local system for private keys or keylogging data entry.
+
+A private key can be encrypted, meaning a private key in a hacker's
+possession is unreadable, but this would not protect against [keylogging malware](https://en.wikipedia.org/wiki/Keystroke_logging) where the encryption
+password was also stolen.
+
+## Paper key storage
+
+Private keys, being relatively small pieces of information, can be stored
+on paper as easily as they can in digital format. Paper has the following
+advantages:
+
+* **Always offline**: No chance of accidental network connection
+* **Easy & cheap**: Multiple copies of multiple keys can be made for backups
+* **Durable**: Robust against mechanical failure
\ No newline at end of file
diff --git a/_docs/overview/multi-signature-security.md b/_docs/overview/multi-signature-security.md
index 58b3b36..362ca92 100644
--- a/_docs/overview/multi-signature-security.md
+++ b/_docs/overview/multi-signature-security.md
@@ -1,156 +1,107 @@
---
title: Multi-signature security
-description: Glacier uses multiple keys to protect your Bitcoins. This makes it
- harder for someone to steal your Bitcoins, and allows you to still access them
- even if you lose one keys.
+description: Glacier uses multiple private keys. This provides greater security,
+ and protects against total loss in the event of the loss of a single key.
---
-Central to our security protocols is
-a technique called "multisignature security." You'll need a quick primer on
-this topic to understand the Glacier protocol.
-
-## Regular Private Keys are Risky
-
-Remember that anybody with access to your private key can access your
-funds. And if you lose your private key, you cannot access your money; it is
-lost forever. There is no mechanism for reversal, and nobody to appeal
-to.
-
-This makes it difficult to keep funds highly secure. For example, you
-might store a private key on paper in a safe deposit box at a bank, and feel
-fairly safe. But even this is not the most robust solution. The box could be
-destroyed in a disaster, or be robbed (perhaps via identity theft), or
-[intentionally seized](http://abcnews.go.com/GMA/story?id=4832471).
-
-You can try to mitigate these risks by storing the key yourself, perhaps in a
-fireproof home safe (as opposed to a bank). But this introduces new risks. A
-determined thief (perhaps a professional who brings safe-drilling tools on their
-burglary jobs, or who somehow got wind of the fact that you have a $100,000
-slip of paper sitting in a safe) might break into the safe and steal the wallet.
-
-Or a major natural disaster might prevent you from returning home for an
-extended period, during which time your safe is looted.
-
-## What is Multisignature Security?
-
-To address these
-issues, Bitcoin provides a way to secure funds with a set of private keys,
-such that some of the keys (but not necessarily all) are required to
-withdraw funds. For example, you might secure your bitcoins with 3 keys but
-only need any 2 of those keys to withdraw funds. (This example is known as
-a "2-of-3" withdrawal policy.)
-
-The keys are then stored in different
-locations, so someone who gets access to one key will not automatically
-have access to the others. Sometimes, a key is entrusted to the custody of
-another person, known as a "signatory."
-
-This approach of using multiple
-keys is known as "multisignature security." The "signature" part of
-"multisignature" comes from the process of using a private key to access
-bitcoins, which is referred to as "signing a transaction." Multisignature
-security is analogous to a bank requiring signatures from multiple people
-(for example, any 2 of a company's 3 designated officers) to access funds in
-an account.
-
-## How Does Multisignature Security Help?
-
-Multisignature security protects against the following scenarios:
-
-* **Theft**: Even if somebody physically breaks into a safe, any one key is not
-enough to steal the money.
-* **Loss**: If a key is destroyed or simply misplaced, you can recover your money
-using the remaining keys.
-* **Betrayal**:
-You may want to entrust one or more signatories with keys to facilitate
-access to your funds when you are dead or incapacitated. With multisignature
-security, entrusting them with a key will not enable them to steal your
-funds (unless they steal additional key(s), or collude with another
-signatory).
-
-## Choosing a Multisignature Withdrawal Policy
-
-Below are common options for withdrawal policies. You will need to select one
-before beginning the protocol.
+Multisignature security, or multisig, is central to Glacier.
+
+
+## Single private keys are risky
+
+The bearer asset nature of bitcoin makes it very difficult to secure. For example,
+a private key, on paper, in a safe deposit box at a bank may seem secure, but
+there are various eventualities that could lead to total loss. The box could be
+destroyed in a disaster, [seized](https://abcnews.go.com/GMA/story?id=4832471),
+accessed after identity theft, or the entire bank could be robbed.
+
+Self storage, perhaps in a fireproof safe at home, can mitigate some of these issues,
+but it also introduces new risks. A home safe is considerably easier to access and
+enter than a bank, as well as potentially introducing personal harm to home
+occupants.
+
+## What is multisignature security?
+
+Multisignature security is analogous to a bank requiring signatures from multiple
+people (for example, any two of a company's three designated officers) to access
+funds in a company account.
+
+Bitcoin provides a way to secure funds with a set of private keys, such that some
+of the keys, but not necessarily all, are required to sign a transaction. For
+example, a "2-of-3" withdrawal policy means that, of the three existing keys, two
+are required. In general, a multisignature policy is described as being "m-of-n",
+where n>=m.
+
+The keys can then be stored in different locations to reduce the chance of any single
+third party gaining access to the minimum required number of keys. Keys can also be
+entrusted to the custody of another person, known as a "signatory."
+
+## How does multisignature security help?
+
+Multisignature security mitigates risk in the following scenarios:
+
+* **Theft**: Control of a single key does not give access to the bitcoin
+* **Loss**: Bitcoin can be recovered after the loss of a single key, if
+misplaced or if the owner is incapacitated, by using the remaining keys
+* **Betrayal**: In the event of death or incapacitation, multisignature security will
+give one or more signatories access to funds without enabling theft by any individual.
+This holds true unless a trusted individual steals additional keys, or colludes
+with another signatory.
+
+## Choosing a multisignature withdrawal policy
+
+Below are common options for withdrawal policies, with option 1 being The Glacier
+Protocol recommendation.
### Option 1: Self-custody of keys
-Our default
-recommendation is a 2-of-4 withdrawal policy where you manage all of your
-own keys (i.e. you do not entrust any to the custody of friends or family).
-2-of-4 means there are four keys, and any two of those keys can be combined
-to access your money, ensuring access even if two keys are lost or
-stolen.
+A 2-of-4 withdrawal policy, with all private keys in the custody of the bitcoin owner,
+where any two private keys can be combined to sign a transaction. This provides access
+even in a scenario where two keys are lost or stolen.
-The keys will be distributed as follows:
+The keys should be distributed as follows:
* One in a safe at home
-* The remaining three in safe deposit boxes or [private vaults](https://www.google.com/search?q=private+safe+deposit+box) at
-different locations
+* Three in safe deposit boxes, or private vaults, at different locations
-It's important to think about estate planning -- making
-arrangements for your designated agents to be able to access your funds when
-you are dead (e.g. for distribution to your heirs) or incapacitated (e.g. to
-pay medical bills). This usually requires significant legal arrangements to
-be made in advance.
+In a self-custody system, estate planning becomes critical. Arrangements must be made
+to provide third party access to funds in the event of death (e.g. for inheritance) or
+incapacitation (e.g. for medical bills). This usually requires significant legal
+arrangement to be made in advance.
-The most failsafe way to ensure your agents will have access to your safe
-deposit box is to check with the bank. Standard estate planning legal documents
-should allow your agent to access the box upon your incapacity, and to get into
-it upon your death. But banks can be fussy and sometimes prefer their own forms.
+The most failsafe way to ensure third party access to a safe deposit box is directly
+via the bank. Standard estate planning legal documents should allow access to each box
+upon personal incapacity or death, although banks may offer their own forms.
-If you have a living trust, one option may be to have your trust as the co-owner
-of your safe deposit box. That generally allows a successor trustee to access
-the box.
+Another option may be to arrange a living trust, or local equivalent, where the trust
+is the co-owner of the safe deposit box. A successor trustee could then access the box.
### Option 2: Distributed custody of keys
-Another option is to distribute some of your
-keys to individuals who you trust ("signatories"). This can offer some
-advantages:
-
-* **Availability**: If you live in a rural area, there may not be many vaults
-or safe deposit boxes that are practical to get to.
-* **Ease of setup**: It may be simpler to distribute keys to signatories than
-to find available vaults, travel to them, and set up accounts.
-* **Ease of estate planning**: You don't need to make complicated legal
-arrangements for your signatories to access your funds. They'll have the keys
-they need to do so.
-
-However, there are significant drawbacks:
-
-* **Privacy**: Other signatories will have the ability to see your balance.
-Technical details: Every private key needs to be packaged with the multisig
-redemption script (since losing all redemption scripts is just as bad as losing
-all keys). Redemption scripts, however, allow one to view funds. An alternate
-version of this protocol could be created using a different multisig approach
-besides P2SH transactions, which would eliminate the ability of signatories to
-view balances; see Appendix C for details.
-* **Signatory collusion**: Although possessing one key won't allow a signatory
-to access your funds, two signatories might collude with each other to steal
-your money.
-* **Signatory reliability**: A signatory may fail to store the key securely, or
-they may lose it.
-* **Signatory safety**: Giving your signatories custody of a valuable key may
-expose them to the risk of targeted physical theft.
-* **Kidnapping risk**: If you anticipate traveling in
-[high-crime areas with kidnapping risk](http://www.nytimes.com/2012/05/03/business/kidnapping-becomes-a-growing-travel-risk.html),
-your funds will be at greater risk because you'll
-have the ability to access them remotely (by contacting your signatories and
-asking for their keys).
-Financially-motivated kidnapping hinges on your ability to access funds to give
-to the kidnappers. If you are literally unable to access additional funds
-(because the keys are stored in remote vaults which you must be physically
-present to access, as opposed to held by friends or family who you can call),
-kidnappers will have no incentive to hold you.
-
-For distributed custody, we recommend a 2-of-5 withdrawal policy. The extra key
-(5 keys, rather than the recommended
-4 keys in Option 1) is recommended since you have less control over whether
-a signatory effectively protects their key against theft or loss
-
-If you have estate planning arrangements which you are confident will allow your
-agents to access the keys in your custody when needed, you should be fine with
-4 keys instead of 5 (two keys going to trusted signatories rather than three).
-Make sure your executors and signatories know to get in touch with each other
-when needed.
+A 2-of-5 withdrawal policy is recommended, with private keys distributed to a number
+of trusted individuals, or signatories. The extra key, five rather than the recommended
+four in Option 1, mitigates the extra risk of signatories not sufficiently protecting
+the key against loss or opportunistic theft. This has the following advantages:
+
+* **Availability**: Vaults or safe deposit boxes may not be available in the local area.
+* **Ease of setup**: It may be simpler to distribute keys to signatories than to travel
+to multiple available vaults and set up accounts.
+* **Ease of estate planning**: No complicated legal arrangements for signatories to
+access funds.
+
+Key distribution also has the following disadvantages:
+
+* **Privacy**: All signatories can see the balance either via the multisignature redeem
+script, or via the cold storage address. An alternate version of this protocol could be
+created using a different multisig approach besides P2SH transactions, which would
+eliminate the ability of signatories to view balances. See [Possible improvements to Glacier](/docs/extend/improvements#consider-shamirs-secret-sharing-or-vanilla-multisig-vs-p2sh-transactions) for details.
+* **Signatory collusion**: Two signatories may collude to gain access to funds.
+* **Signatory reliability**: A signatory may fail to store the key securely.
+* **Signatory safety**: Signatories may be exposed to the risk of targeted physical theft.
+
+Thorough estate planning arrangements, which allow executors to access the keys if
+necessary, will allow the policy to be reduced from 2-of-5 to 2-of-4. Two keys should
+be issued to trusted signatories rather than three.
+
+Whether 2-of-5 or 2-of-4, each signatory should be able to communicate with each other
+when needed.
\ No newline at end of file
diff --git a/_docs/protocol-vulnerabilities/attack-surface.md b/_docs/protocol-vulnerabilities/attack-surface.md
new file mode 100644
index 0000000..b211476
--- /dev/null
+++ b/_docs/protocol-vulnerabilities/attack-surface.md
@@ -0,0 +1,145 @@
+---
+title: Attack surface and failure points
+description: Learn about the attack survace for Glacier, the
+ step-by-step protocol for storing bitcoins in a highly secure way
+---
+
+This section describes the attack surface and failure points for The Glacier
+Protocol. Only attacks and failures related to The Glacier Protocol, as
+opposed to other methods, are included. Any attack or failure related
+to the Bitcoin system as a whole is ignored. A newly discovered cryptographic
+flaw, or a critical Bitcoin protocol security or scalability failure, would
+impact all bitcoins, regardless of whether they are secured with Glacier or
+some other method.
+
+It is assumed that no security measures from the [Extend Glacier security](/docs/extend/security)
+section are implemented.
+
+There are two layers to Glacier's attack surface, malware and critical failure.
+
+## Malware infection vectors
+
+Most attacks require the presence of malware, malicious code, either in or near the quarantined environment.
+
+### Software
+
+The operating system or application distributions could be compromised. In particular,
+Glacier relies on the following packages and their dependencies:
+* Ubuntu desktop
+* Bitcoin Core
+* zbar-tools (via Ubuntu Package Archive)
+* qrencode (via Ubuntu Package Archive)
+
+An infected Setup Computer could infect the Setup USB drive software, which could infect the
+Quarantined USB drive software. This could produce false positives during the checksum
+verification process or alter the display of the verification process results. Verifying
+the integrity of GnuPG requires access to a trusted installation of GnuPG, which many
+users won't have. The current recommendation is to trust the downloaded version of GnuPG.
+
+An infected Setup Computer could infect the operating system or application USB drive software
+AFTER checksum verification produces a true positive, either before/during copying of
+software to the USB drive, or during USB ejection.
+
+### Firmware
+
+An infected Setup Computer could infect the Setup Boot USB drive firmware, which could infect
+the Quarantined Boot/App USB drive.
+
+A laptop or USB drive firmware could have been infected at any point between manufacture and
+delivery, before being shrinkwrapped.
+
+### Hardware
+
+A laptop or USB drive hardware could have been infected at any point between manufacture and
+delivery, before being shrinkwrapped. "Malware" usually refers to software, but we're
+using it here more broadly to mean "computing technology which undermines the integrity
+of the computing environment in which it resides.", as in a
+[USB JTAG exploit](https://www.itnews.com.au/news/intel-debugger-interface-open-to-hacking-via-usb-446889)
+or [chip-level backdoor](https://www.wired.com/2016/06/demonically-clever-backdoor-hides-inside-computer-chip/).
+
+## Failure scenarios
+
+Scenarios in which a critical failure might happen. Possibly, but not necessarily, due
+to a malware infection.
+
+### Exfiltration of critically sensitive data
+A Quarantined Computer could leak critically sensitive data via a
+[side-channel attack](https://en.wikipedia.org/wiki/Side-channel_attack), which is a form
+of electronic threat based on the physical nature of computing hardware as
+opposed to algorithms or their software implementations. Complementary malware, on a
+networked or attacker-controlled device in range, is then used to steal data. Side channel
+attacks are rare, but most are relatively straightforward to defend against. Possibilities
+include:
+ * **Visual side channel**: Exploit of sensitive visual data. Data is displayed on the
+ screen as part of the protocol, so does not require malware on the quarantined computer.
+ If the protocol is followed, the attack surface here should be narrow, as users are
+ instructed to block all visual side channels. However, at a minimum, a smartphone with a
+ camera is used for reading QR codes.
+ * **Acoustic side channel**: [Exploit of sounds emitted by computer or other device](https://en.wikipedia.org/wiki/Acoustic_cryptanalysis), if
+ inadequately blocked by sound insulation or masking noise. [Data theft by fan noise](https://www.wired.com/2016/06/clever-attack-uses-sound-computers-fan-steal-data), for example.
+ * **Power side channel**: [Exploit using electrical outlets to identify webpages](https://sharps.org/wp-content/uploads/CLARK-ESORICS13.pdf), for example.
+ * **Radio side channel**: [Exploit of electromagnetic emanations from wired and wireless
+ keyboards](https://www.usenix.org/legacy/event/sec09/tech/full_papers/vuagnoux.pdf),
+ [transmission of radio signals from monitor to FM radio receiver](https://cyber.bgu.ac.il/content/how-leak-sensitive-data-isolated-computer-air-gap-near-mobile-phone-airhopper)
+ or [radio waves leaked by a processor's power use](https://www.wired.com/2015/06/radio-bug-can-steal-laptop-crypto-keys-fits-inside-pita/),
+ for example.
+ * **Seismic side channel**: Decoding vibrations from nearby keyboard using mobile phone accelerometer, for example.
+ * **Thermal side channel**: [Exploit using thermal sensors to detect heat emission](https://cyber.bgu.ac.il/blog/bitwhisper-heat-air-gap), for example.
+ * **Magnetic side channel**: [Exploit using smartphone magnetic field sensors to extract hard drive data](https://fc15.ifca.ai/preproceedings/paper_14.pdf), for example.
+ * **Rogue QR code**: Malware on a Quarantined Computer could exfiltrate critically
+ sensitive data via QR codes IF cooperating malware on the QR reading device is prepared
+ to steal the data. The risk of this scenario is negligible; unless the attacker
+ simultaneously compromised every major smartphone QR reader with cooperating malware,
+ any manipulation of QR codes would be quickly detected by users of non-compromised QR
+ reader software, leading to widespread awareness and isolation of the threat. This makes
+ it a very unattractive attack vector.
+ * **Data leak**: Critically sensitive data could be leaked, intentionally or otherwise, as part of the
+ payload of valid data. For example, the nonce used for a transaction signature could contain
+ bits of the private key.
+ * **Flawed data generation**: Undetected generation of flawed sensitive data IF compatible
+ malware is present on BOTH quarantined environments. For example, standard software algorithms that
+ generate random numbers, such as those used to generate Bitcoin private keys, are
+ [vulnerable to exploitation](https://bitcoin.org/en/alert/2013-08-11-android), either due to malware
+ or algorithmic weakness. This can often provide numbers that are not truly random.
+ * **Guessable private keys**: Private key creation could be compromised to make keys easily guessable.
+ * **Compromised addresses**: Transaction creation is compromised to use output addresses belonging to an attacker,
+ AND cooperating malware on a networked computer sends the malicious transaction before the
+ manual address verification is done.
+
+### Physical failures
+
+* Two paper keys are stolen by an attacker
+* All (or all but one) paper keys are lost or destroyed
+* An attacker with physical line-of-sight to the laptop takes a photo of the screen while sensitive data is displayed
+* Malware on the quarantined machines writes sensitive data to persistent media (USB drive or laptop hard drive) AND the hardware is physically stolen afterward
+
+### Glacier protocol failures
+
+* Glacier hosting (i.e. DNS, Github, website hosting, etc.) is compromised
+to inject weaknesses into the protocol documentation or GlacierScript
+* Protocol delivery is compromised (e.g. with
+a man-in-the-middle attack on the user's computer or network) to deliver
+or display a weakened version of the protocol documentation or
+software
+* Protocol hardcopy is compromised (e.g. by malware to alter the user's hardcopy as it is printed)
+* A flaw in GlacierScript causes sensitive data to be leaked or flawed
+* Human error during protocol execution
+* Design failure in the protocol misses or inadequately addresses a risk
+
+Potential man-in-the-middle vulnerabilities are mitigated by including steps in
+the protocol for verifying the signature and checksum of the Glacier document
+itself. Unfortunatley, vulnerabilities remain:
+
+* An attacker could remove the self-verification procedure from the protocol document.
+* An attacker could compromise the Glacier Protocol keypair and create a fraudulent
+signature. This is exceedingly unlikely, due to Keybase's key verification systems.
+* The protocol document is verified on the first Setup Computer. It is not
+verified on the second Setup Computer, nor when booting into the Setup Computers
+to create the Quarantined Boot USB drives. If the protocol document had been
+compromised between the initial validation and later re-validation, the user would
+probably not notice, even without a forged signature.
+* The protocol hardcopy could be compromised. For example, malware could alter the
+hardcopy as it is printed.
+* A flaw in GlacierScript could cause sensitive data to be leaked or flawed
+* Human error could occur during protocol execution
+* Design failure in the protocol could miss or inadequately address a risk
\ No newline at end of file
diff --git a/_docs/setup/create-app-usb.md b/_docs/setup/create-app-usb.md
index c7895b4..54547f1 100644
--- a/_docs/setup/create-app-usb.md
+++ b/_docs/setup/create-app-usb.md
@@ -1,90 +1,79 @@
---
-title: Create App USBs
-description: Learn how to prepare your USB drives for Glacier, the
+title: Create App USB drives
+description: Learn how to prepare the App USB drives for Glacier, the
step-by-step protocol for storing bitcoins in a highly secure way
---
-We will prepare two (2) "Quarantined App USB"
-drives with the software needed to execute the remainder of the protocol.
-These are the USB drives you labeled "Q1 APP" and "Q2 APP" in Section
-III.
-
-1. Boot the SETUP 1 computer off the SETUP 1 BOOT USB if it is not
-already. (See the instructions in Section III for details.)
-2. Insert the Q1 APP USB into the the SETUP 1 computer.
-
- 1. **The instruction to plug a Quarantined App USB into your Setup computer
- *should* raise a red flag for you, because you should never plug a quarantined
- USB into anything other than the quarantined computer it is designated for!**
-
- This setup process is the ONE exception.
-
-3. Press Ctrl-Alt-T to open a terminal window.
-4. Install the Glacier document and GlacierScript on the Q1 APP USB.
-
- 1. Download the latest full release of Glacier (*not* just the protocol
- document) at
- [https://github.com/GlacierProtocol/GlacierProtocol/releases](https://github.com/GlacierProtocol/GlacierProtocol/releases).
- 2. Unpack the Glacier ZIP file into a staging area.
-
- 1. When the download starts, Firefox will ask you if you want to open the
- ZIP file with Archive Manager. Click OK.
-
- When the ZIP file download completes, it will be opened with Archive Manager.
-
- 2. There will be a single entry in a list named
- "GlacierProtocol-version-here", where
- version-here is replaced with
- the current version number (like "v1.0"). Click on that and then click
- the "Extract" button.
- 3. The Archive Manager will ask you where you want to extract the ZIP
- file to. Select "Home" on the left panel and then press the extract button.
- 4. When the Archive Manager is finished extracting the ZIP archive it
- will ask you what to do next. Click "Show the Files".
- 5. Rename the unzipped folder from "GlacierProtocol-version-here" to
- "glacier".
-
- 3. Obtain the Glacier "public key," used to cryptographically verify the
- Glacier document and GlacierScript.
-
- **If you are ever using Glacier in the future and notice that this step
- has changed (or that this warning has been removed), there is a
- security risk.** Stop and seek assistance.
-
- 1. Access Glacier's Keybase profile at https://keybase.io/glacierprotocol.
- 2. Click the string of letters and numbers next to the key icon.
- 3. In the pop-up that appears, locate the link reading "this key".
- 4. Right-click the link and select "Save Link As..."
- 5. Name the file "glacier.asc".
-
- 4. Verify the integrity of the Glacier download.
-
- 1. Import the Glacier public key into your local GPG installation:
+This section will prepare the two Quarantined App USB drives, "Q1 APP" and "Q2 APP" in the
+[Hardware required](/docs/before-you-start/hardware/#eternally-quarantined) section, with
+the software needed to execute the remainder of the protocol.
+
+## On Setup Computer “SETUP 1”
+
+1. Boot the "SETUP 1" computer from the "SETUP 1 BOOT" USB drive, following step 1 of
+[Create the “Q1 BOOT” USB drive](/docs/setup/create-boot-usb/#create-the-q1-boot-usb-drive)
+in the Create boot USB drives section.
+2. Insert the "Q1 APP" USB drive into the the "SETUP 1" computer.
+
+ The instruction to plug a Quarantined App USB drive into the Setup Computer
+ should raise a red flag, because **a quarantined USB drive
+ should never be plugged into anything other than its designated quarantined computer!**.
+ This setup process is the **ONE** necessary exception.
+
+### Download Glacier and Glacierscript
+
+1. Press "Ctrl-Alt-T" to open a terminal window.
+2. Install the Glacier document and GlacierScript on the "Q1 APP" USB drive:
+ 1. Download the latest full release of Glacier, *not* just the protocol
+ document, from the "Source code (zip)" link at
+ [Glacier's Github repo](https://github.com/GlacierProtocol/GlacierProtocol/releases).
+ 2. Unpack the Glacier ZIP file into a staging area:
+ 1. When the download starts, Firefox will prompt for the action to take with the file
+ once downloaded. Click "OK" to open with Archive Manager.
+ 2. In the Archive Manager window, click on the single entry in the list named
+ "GlacierProtocol-version", where
+ version is replaced with
+ the current version number (for example, "v1.0"). Click "Extract".
+ 3. Select "Home" on the left panel of the file browser that appears and click "Extract" again.
+ 4. Click "Show the Files" once a popup declares the files are extracted.
+ 5. In the folder window that appears, rename the unzipped folder from "GlacierProtocol-version" to "glacier".
+ 3. Obtain the Glacier public key used to cryptographically verify the
+ Glacier document and GlacierScript:
+
+ **If this step changes in future uses of Glacier, or this warning is removed, there is a security risk.**
+ Stop and seek assistance.
+
+ 1. Navigate to Glacier's Keybase profile at [keybase.io/glacierprotocol](https://keybase.io/glacierprotocol).
+ 2. Click the string of 16 letters and numbers, formatted "XXXX XXXX XXXX XXXX", next to the key icon.
+ 3. In the pop-up that appears, right-click the link reading "this key" and select
+ "Save Link As..." or "Download Linked File As...".
+ 4. Name the file "glacier.asc".
+
+ 4. Verify the integrity of the Glacier download:
+ 1. Import the Glacier public key into the local GPG installation:
```
$ gpg --import ~/Downloads/glacier.asc
```
- 2. Switch to the glacier folder:
+ 2. Change the terminal’s current working folder to the Glacier folder:
```
$ cd ~/glacier
```
- 3. Use the public key to verify that the Glacier "fingerprint file" is
+ 3. Use the public key to verify that the Glacier fingerprint file is
legitimate:
```
$ gpg --verify SHA256SUMS.sig SHA256SUMS
```
- Expected output (timestamp will vary, but
- e-mail and fingerprint should match):
-
- gpg: Signature made Thu Jan 19 13:45:48 2017 PST using RSA key ID 4B43EAB0
+ Expected output (timestamp will vary, but e-mail and fingerprint should match):
+ gpg: Signature made Thu Jan 19 13:45:48 2017 PST using RSA key ID 4B43EAB0
gpg: Good signature from "Glacier Team "
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: E1AA EBB7 AC90 C1FE 80F0 1034 9D1B 7F53 4B43
-
+
- The warning message is expected, and is not cause for alarm.
-
- 4. Verify the fingerprints in the fingerprint file match the fingerprints
+ The warning message is expected, and is not cause for alarm. See technical detail
+ in [Verify and print protocol document](/docs/setup/verify/#document-verification), point 3 for explanation.
+ 4. Verify that the fingerprints in the fingerprint file match the fingerprints
of the downloaded Glacier files:
```
$ sha256sum -c SHA256SUMS 2>&1
@@ -96,113 +85,105 @@ already. (See the instructions in Section III for details.)
base58.py: OK
README.md: OK
```
-
- 5. Copy the glacier folder to the Q1 APP USB.
- 1. Click on the File Manager icon in the launching dock along the left
+ 5. Copy the glacier folder to the "Q1 APP" USB drive:
+ 1. Click on the "File Manager" icon in the launching dock along the left
side of the screen.
2. Find the "glacier" folder under "Home".
- 3. Click and drag the glacier folder to the icon representing the USB
- drive on the left. The USB drive will look like this, but may have a
- different name:
- 4. If you see an "Error while copying" pop-up, you may be suffering from
- [this Ubuntu bug](https://bugs.launchpad.net/ubuntu/+source/nautilus/+bug/1021375).
- To fix it, do the following and then retry copying the files:
-
- 1.
+ 3. Click and drag the "glacier" folder to the icon representing the USB
+ drive on the left.
+ 4. An "Error while copying" pop-up may appear in the event of
+ [bug #1021375](https://bugs.launchpad.net/ubuntu/+source/nautilus/+bug/1021375). Do the following before trying to copy the "glacier" folder again:
+ 1. Reset the Nautilus settings to default:
```
$ mv ~/.config/nautilus ~/.config/nautilus-bak
```
- 2. Log out of Ubuntu: Click the power icon in the top right of the
- screen and select "logout" from the drop-down menu.
+ 2. Clicking the power icon in the top right of the screen and click "logout" from the drop-down menu.
3. Login again with user "ubuntu" and leave the password blank.
-5. Open the Glacier protocol document so that it is available for copy-pasting terminal commands.
-6. Install the remaining application software on the Q1 APP USB.
- 1. Configure our system to enable access to the software we need in Ubuntu's
- "package repository".On Ubuntu 16.04.01 [there is a bug](https://bugs.launchpad.net/ubuntu/+source/appstream/+bug/1601971) in Ubuntu's package manager that affects systems
- running off a bootable Ubuntu USB. The commands in steps a and b are a
- workaround.
- 1. ```
- $ sudo mv /var/cache/app-info/xapian/default /var/cache/app-info/xapian/default_old
+### Prepare the system
+
+1. Open the Glacier protocol document for copy-pasting terminal commands.
+
+2. Implement workaround for [bug #1601971](https://bugs.launchpad.net/ubuntu/+source/appstream/+bug/1601971)
+which affects Ubuntu 16.04.01's package manager when running from a bootable USB drive:
+ ```
+ $ sudo mv /var/cache/app-info/xapian/default /var/cache/app-info/xapian/default_old
+ $ sudo mv /var/cache/app-info/xapian/default_old /var/cache/app-info/xapian/default
+ ```
+3. Configure the system to enable access to the required package repositories:
+ ```
+ $ sudo apt-add-repository universe
+ $ sudo apt-add-repository ppa:bitcoin/bitcoin
+ $ sudo apt-get update
+ ```
+
+### Download third-party apps
+
+1. Download [bitcoind](https://bitcoincore.org/)
+(cryptography & financial operations), qrencode (QR code creation for quarantined data
+export) and zbar-tools (QR code reading for quarantined data import) software:
+ ```
+ $ sudo apt-get install qrencode=3.4.4-1 zbar-tools=0.10+doc-10ubuntu1 bitcoind
+ ```
+2. Copy the downloaded software to the "Q1 APP" USB drive:
+ 1. Create a folder for the application files to be moved to the
+ USB drive:
```
- 2. ```
- $ sudo mv /var/cache/app-info/xapian/default_old /var/cache/app-info/xapian/default
+ $ mkdir ~/apps
```
- 3. ```
- $ sudo apt-add-repository universe
+ 2. Copy the application files into the newly created "apps" folder:
```
- 4. ```
- $ sudo apt-add-repository ppa:bitcoin/bitcoin
+ $ cp /var/cache/apt/archives/*.deb ~/apps
```
- 5. ```
- $ sudo apt-get update
+ 3. Copy the "apps" folder contents to the "Q1 APP" USB drive:
+ 1. Click on the "File Manager" icon in the launching dock.
+ 2. Navigate to the "Home" folder.
+ 3. Click and drag the "apps" folder to the icon representing
+ the USB drive on the left panel.
+3. Verify the correct files have been copied:
+ 1. Click on the USB drive icon to display the following contents:
```
- 2. Download and perform integrity verification59 of software available from Ubuntu's package repository:
- * **bitcoind**: [Bitcoin Core](https://bitcoincore.org/):
- , which we'll use for cryptography & financial operations
- * **qrencode**: Used for creating QR codes to move data off quarantined
- computers
- * **zbar-tools**: Used for reading QR codes to import data into quarantined
- computers
- ```
- $ sudo apt-get install qrencode=3.4.4-1 zbar-tools=0.10+doc-10ubuntu1 bitcoind
- ```
- 3. Copy that software to the Q1 APP USB.
- 1. Create a folder for the application files that will be moved to the
- USB:
- ```
- $ mkdir ~/apps
- ```
- 2. Copy the software into the apps folder:
- ```
- $ cp /var/cache/apt/archives/*.deb ~/apps
- ```
- 3. Copy the contents of the apps folder to the Q1 APP USB:
- 1. Click on the File Manager icon in the launching dock:
- 2. Navigate to the "Home" folder.
- 3. Click and drag "apps" folder to the icon representing
- the USB drive on the left panel. The USB drive will look like this,
- but may have a different name:
-7. Click on the USB drive icon to verify that it has the correct files. The
-contents should look like this
- ```
- apps
- glacier
- ```
+ apps
+ glacier
+ ```
+ 2. Click the "apps" folder to display the following contents:
+ ```
+ bitcoind_0.13.2-xenial1_amd64.deb
+ libboost-chrono1.58.0_1.58.0+dfsg-5ubuntu3.1_amd64.deb
+ libboost-program-options1.58.0_1.58.0+dfsg-5ubuntu3.1_amd64.deb
+ libboost-thread1.58.0_1.58.0+dfsg-5ubuntu3.1_amd64.deb
+ libdb4.8++_4.8.30-xenial2_amd64.deb
+ libevent-core-2.0-5_2.0.21-stable-2_amd64.deb
+ libevent-pthreads-2.0-5_2.0.21-stable-2_amd64.deb
+ libqrencode3_3.4.4-1_amd64.deb
+ libsodium18_1.0.8-5_amd64.deb
+ libzbar0_0.10+doc-10ubuntu1_amd64.deb libzmq5_4.1.4-7_amd64.deb
+ qrencode_3.4.4-1_amd64.deb zbar-tools_0.10+doc-10ubuntu1_amd64.deb
+ ```
+ Note that the version number of the Bitcoin package may change as new
+ versions are released.
- Click the apps folder. It will have the following content.
- Note that the version number of the Bitcoin package may change as new
- versions are released. Future versions of Glacier may pin to a specific
- version.
+ 3. Click "back" and click the "glacier" folder to display the following contents
+ ```
+ base58.py
+ Glacier.pdf
+ glacierscript.py
+ LICENSE README.md
+ SHA256SUMS
+ SHA256SUMS.sig
+ ```
+4. Immediately remove the "Q1 APP" USB drive from the “SETUP 1” computer:
+ 1. On the desktop, right-click the USB drive icon corresponding to the “Q1 APP” USB
+ drive, and select “Eject” from the pop-up menu.
+ 2. Remove the "Q1 APP" USB drive from the USB slot.
- ```
- bitcoind_0.13.2-xenial1_amd64.deb
- libboost-chrono1.58.0_1.58.0+dfsg-5ubuntu3.1_amd64.deb
- libboost-program-options1.58.0_1.58.0+dfsg-5ubuntu3.1_amd64.deb
- libboost-thread1.58.0_1.58.0+dfsg-5ubuntu3.1_amd64.deb
- libdb4.8++_4.8.30-xenial2_amd64.deb
- libevent-core-2.0-5_2.0.21-stable-2_amd64.deb
- libevent-pthreads-2.0-5_2.0.21-stable-2_amd64.deb
- libqrencode3_3.4.4-1_amd64.deb
- libsodium18_1.0.8-5_amd64.deb
- libzbar0_0.10+doc-10ubuntu1_amd64.deb libzmq5_4.1.4-7_amd64.deb
- qrencode_3.4.4-1_amd64.deb zbar-tools_0.10+doc-10ubuntu1_amd64.deb
- ```
- Click the glacier folder. It will have the following content:
- ```
- base58.py
- Glacier.pdf
- glacierscript.py
- LICENSE README.md
- SHA256SUMS
- SHA256SUMS.sig
- ```
-8. Eject and physically remove the Q1 APP USB from the SETUP 1 computer.
+ **The "Q1 APP" USB drive is now eternally quarantined. It should only ever be
+ plugged into the “Q1” computer.**
+
+## On Setup Computer “SETUP 2”
- **The Q1 APP USB is now eternally quarantined. It should never again be
- plugged into anything besides the Q1 computer.**
+Create the “Q2 APP” USB drive by repeating the [On Setup Computer “SETUP 1”](/docs/setup/create-app-usb/#on-setup-computer-setup-1) section above, replacing
+occurances of “SETUP 1”, "SETUP 1 BOOT" and “Q1 APP” with “SETUP 2”, "SETUP 2 BOOT"
+and “Q2 APP”, respectively.
-9. Repeat all above steps using the SETUP 2 computer, SETUP 2 BOOT USB, and Q2
-APP USB.
-10. Find a container in which to store all of your labeled hardware, along
-with the Glacier document hardcopy, when you are finished.
+**Safely store all labeled hardware, along with the Glacier document hardcopy.**
\ No newline at end of file
diff --git a/_docs/setup/create-boot-usb.md b/_docs/setup/create-boot-usb.md
index df20701..e564a78 100644
--- a/_docs/setup/create-boot-usb.md
+++ b/_docs/setup/create-boot-usb.md
@@ -1,323 +1,331 @@
---
-title: Create boot USBs
-description: Learn how to prepare your USB drives for Glacier, the
+title: Create boot USB drives
+description: Learn how to prepare the USB drives for Glacier, the
step-by-step protocol for storing bitcoins in a highly secure way
---
-Because the eternally quarantined computers cannot connect to a network, they
-cannot download software. We'll be using USB drives to transfer the necessary
-software to them.
+To ensure isolation from any network, USB drives will be used to transfer the necessary
+software to the eternally quarantined computers. Four bootable Linux USB drives will be
+used to directly boot to the [Ubuntu](https://en.wikipedia.org/wiki/Ubuntu_(operating_system))
+operating system, eliminating the use of the computer's hard drive in any way.
-We will prepare four bootable
-[Ubuntu](https://en.wikipedia.org/wiki/Ubuntu_(operating_system))
-USB drives. ("Bootable" means that the Ubuntu operating system will be booted
-directly from the USB drive, without using the computer's hard drive in any
-way.)
+In accordance with the [Prepare hardware](/docs/setup/prepare-hardware/#non-quarantined-hardware)
+section:
+* The Setup Boot USB drives, "SETUP 1 BOOT" and "SETUP 2 BOOT", will be prepared using
+the Setup Computers "SETUP 1" and "SETUP 2", respectively.
+* The Quarantined Boot USB drives, "Q1 BOOT" and "Q2 BOOT", will be prepared using
+the Setup Computers "SETUP 1" and "SETUP 2", *while booted from the Setup Boot USB drives*,
+“SETUP 1 BOOT” and “SETUP 2 BOOT”, respectively.
-The *first two* USB drives ("Setup Boot USBs") are the USB drives you labeled
-"SETUP 1 BOOT" and "SETUP 2 BOOT" in Section II. They will be prepared using
-your Setup Computers, which may be running Windows, macOS, or something else.
+Technical details: The non-quarantined Setup Boot USB drives serve two purposes:
-The *last two* USB drives ("Quarantined Boot USBs") are the USB drives you
-labeled "Q1 BOOT" and "Q2 BOOT" in Section II. They will be prepared using your
-Setup Computers *while booted off* a *Setup Boot USB*.
+* To greatly simplify the steps for creation of the Quarantined App USB drives in the next
+section, since only operations on an Ubuntu environment need outlined. The Quarantined Boot USB drives
+cannot be used for this since they are eternally quarantined and should be permanently
+unplugged from the Setup Computers the moment they are created.
+* To reduce the risk of malware spreading from the native operating system of a
+Setup Computer to a Quarantined USB drive. The malware would first have to propagate itself
+to a Non-Quarantined "SETUP 1 BOOT" or "SETUP 2 BOOT" USB drive.
-Technical details: The Non-Quarantined OS USBs serve two purposes:
+## On Setup Computer “SETUP 1”
+Open a copy of this document.
-* First, they are used for creating the Quarantined App USBs in the next
-section, which greatly simplifies the process of doing so because we know
-it'll always be done from an Ubuntu environment. (We can't use the
-Quarantined OS USBs for this -- they're eternally quarantined, so they need to
-be permanently unplugged from their Setup Computer the moment they are created.)
-* Second, it will be harder for any malware infections on a Setup Computer's
-default OS to undermine a Quarantined USB setup process (the malware would
-first have to propagate itself to the Non-Quarantined OS USB).
+### Download and verify Ubuntu
-1. Perform the following steps on your SETUP 1 computer.
-2. If you are not already reading this document on the SETUP 1 computer, open a
-copy there.
-3. Download Ubuntu by going to this link:
+1. Download [Ubuntu](http://old-releases.ubuntu.com/releases/xenial/ubuntu-16.04.1-desktop-amd64.iso).
- [http://old-releases.ubuntu.com/releases/xenial/ubuntu-16.04.1-desktop-amd64.iso](http://old-releases.ubuntu.com/releases/xenial/ubuntu-16.04.1-desktop-amd64.iso)
- Wait until the download is complete.
+2. Once the download is complete, open a terminal window:
-4. Open a terminal window.
+ * **Windows**: Press "Windows-R", type "powershell" and click "OK".
+ * **MacOS**: Click the Searchlight (magnifying glass) icon in the menu bar,
+ and type "terminal". Select the "Terminal" application from the search results.
+ * **Linux**: Varies; on Ubuntu, press "Ctrl-Alt-T".
- 1. **Windows**: Press Windows-R, type "powershell" and click OK.
- 2. **macOS**: Click the Searchlight (magnifying glass) icon in the menu bar,
- and type "terminal". Select the Terminal application from the search results.
- 3. **Linux**: Varies; on Ubuntu, press Ctrl-Alt-T. (On Ubuntu, press
- Ctrl-Alt-T.)
+3. Verify the Ubuntu download integrity:
-5. Verify the integrity of the Ubuntu download.
+ 1. Change the terminal’s current working folder to the download folder,
+ customizing the folder name if necessary:
- 1. Change the terminal window's active folder to the folder where you
- downloaded Ubuntu, customizing the folder name if necessary:
-
- 1. **Windows**: `> cd $HOME/Downloads`
- 2. **macOs**: `$ cd $HOME/Downloads`
- 3. **Linux**: `$ cd $HOME/Downloads`
+ * **Windows**:
+ ```
+ > cd $HOME/Downloads
+ ```
+ * **MacOS**:
+ ```
+ $ cd $HOME/Downloads
+ ```
+ * **Linux**:
+ ```
+ $ cd $HOME/Downloads
+ ```
2. View the fingerprint of the file:
- 1. **Windows**: `> Get-FileHash -a sha256 ubuntu-16.04.1-desktop-amd64.iso`
- 2. **macOs**: `$ shasum -a 256 ubuntu-16.04.1-desktop-amd64.iso`
- 3. **Linux**: `$ sha256sum ubuntu-16.04.1-desktop-amd64.iso`
+ * **Windows**:
+ ```
+ > Get-FileHash -a sha256 ubuntu-16.04.1-desktop-amd64.iso
+ ```
+ * **MacOS**:
+ ```
+ $ shasum -a 256 ubuntu-16.04.1-desktop-amd64.iso
+ ```
+ * **Linux**:
+ ```
+ $ sha256sum ubuntu-16.04.1-desktop-amd64.iso
+ ```
- 3. The following fingerprint should be displayed:
+ 3. The following fingerprint, further verified in
+ [the official Ubuntu fingerprint list](http://releases.ubuntu.com/16.04.1/SHA256SUMS)
+ against "*ubuntu-16.04.1-desktop-amd64.iso",
+ should be displayed:
```
dc7dee086faabc9553d5ff8ff1b490a7f85c379f49de20c076f11fb6ac7c0f34
```
- It's not important to check every single character when visually
- verifying a fingerprint. It's sufficient to check the **first 8
+ Alternatively, follow [Ubuntu's official full verification process](https://tutorials.ubuntu.com/tutorial/tutorial-how-to-verify-ubuntu#0).
+
+ It is not important to check every single character when visually
+ verifying a fingerprint. It is sufficient to check the **first 8
characters, last 8 characters, and a few somewhere in the middle.**
- Technical details: Because you verified the checksum & checksum
- signature for this document in Section I, we are omitting the GPG
- verification of some other fingerprints in the protocol. For a detailed
- security analysis, see the design document.
-
- You can verify this is the official Ubuntu fingerprint
- [here](http://releases.ubuntu.com/16.04/SHA256SUMS),
- or follow Ubuntu's full verification process using this guide.
-
-6. Create the SETUP 1 BOOT USB.
-
- 1. **Windows**
- 1. Download the
- [Rufus disk utility](https://rufus.akeo.ie/)
- and run it.
- 2. Insert the SETUP 1 BOOT USB in an empty USB slot.
- 3. In the "Device" dropdown at the top of the Rufus window, ensure the
- empty USB drive is selected.
- 4. Next to the text "Create a bootable disk using", select "ISO Image"
- in the dropdown.
- 5. Click the CD icon next to the "ISO Image" dropdown.
- 6. A file explorer will pop up. Select `ubuntu-16.04.1-desktop-amd64.iso`
- from your downloads folder and click Open.
- 7. Click Start.
- 8. If prompted to download Syslinux software, click "Yes".
- 9. When asked to write in "ISO Image Mode (Recommended)" or
- "DD Image Mode", select "ISO Image Mode" and press OK.
- 10. The program will take a few minutes to write the USB.
-
- 2. **macOS**
- 1. Prepare the Ubuntu download for copying to the USB.
- ```
- $ cd $HOME/Downloads
- $ hdiutil convert ubuntu-16.04.1-desktop-amd64.iso -format UDRW -o ubuntu-16.04.1-desktop-amd64.img
- ```
- 2. Determine the macOS "device identifier" for the Boot USB.
- 1. `$ diskutil list`
- 2. Insert the SETUP 1 BOOT USB in an empty USB slot.
- 3. Wait 10 seconds for the operating system to recognize the USB.
- 4. Once more: `$ diskutil list`
- 5. The output of the second command should include an additional
- section that was not present in the first command's output.
- 1. This section will have (external, physical) in the header.
- 2. The first line of the section's SIZE column should reflect
- the capacity of the USB drive.
- 6. Make a note of the device identifier.
- 1. The device identifier is the part of the new section header
- that comes before (external, physical) (for example /dev/disk2).
-
- 3. Put Ubuntu on the SETUP 1 BOOT USB.
- 1. First, unmount the usb
-
- $ diskutil unmountDisk USB-device-identifier-here
-
- 2. Enter the following command, **making sure to use the correct
- device identifier; using the wrong one could overwrite your hard
- drive!**
-
- $ sudo dd if=ubuntu-16.04.1-desktop-amd64.img.dmg \
- of=USB-device-identifier-here bs=1m
-
- Example:
- ```
- $ sudo dd if=ubuntu-16.04.1-desktop-amd64.img.dmg of=/dev/disk2 bs=1m
- ```
- 3. Enter your administrator password when requested.
- 4. Wait several minutes for the copying process to complete. When
- it does, you may see an error box pop up. This is expected; it's
- because the USB is written in a format readable by Ubuntu, but not
- readable by macOS.
- 5. Click Ignore.
-
- 4. Verify the integrity of the SETUP 1 BOOT USB (i.e. no errors or
- malware infection).
- 1. Remove the USB drive from the USB slot and immediately reinsert it.
- 2. Wait 10 seconds for the operating system to recognize the USB.
- 3. You may see the same error box pop up again. Select Ignore.
- 4. The USB's device identifier may have changed. Find it again:
- ```
- $ diskutil list
- ```
- 5.
- ```
- $ cd $HOME/Downloads
- ```
- 6.
- ```
- $ sudo cmp -n `stat -f '%z' ubuntu-16.04.1-desktop-amd64.img.dmg ubuntu-16.04.1-desktop-amd64.img.dmg` USB-device-identifier-here
- ```
- 7. Wait a few minutes for the verification process to complete.
- 8. If all goes well, the command will output no data, returning to
- your usual terminal prompt.
- 9. If there is a discrepancy, you’ll see a message like:
- ```
- ubuntu-16.04.1-desktop-amd64.img.dmg /dev/disk2
- differ: byte 1, line 1
- ```
- If you see a message like this, STOP -- this may be a security
- risk. Restart this section from the beginning. If the
- issue persists, try using a different USB drive or a different
- Setup Computer.
-
- 3. **Ubuntu**
- 1. If this is your first time using Ubuntu, note:
- 1. You can copy-paste text in most applications (e.g. Firefox) by
- pressing **Ctrl-C** or **Ctrl-V**.
- 2. You can copy-paste text in a *terminal window* by pressing
- **Ctrl-Shift-C** or **Ctrl-Shift-V**.
- 2. Put Ubuntu on the SETUP BOOT 1 USB.
- 1. Open the Ubuntu search console by clicking the purple
- circle/swirl icon in the upper-left corner of the screen.
- 2. Type "startup disk creator" in the text box that appears
- 3. Click on the "Startup Disk Creator" icon that appears.
- 4. The "Source disc image" panel should show the.iso file you
- downloaded. If it does not, click the "Other" button and find it
- in the folder you downloaded it to.
- 5. In the "Disk to use" panel, you should see two lines. They may
- vary from system to system, but each line will have a device
- identifier in it, highlighted in the example below.
-
- Generic Flash Disk (/dev/sda)
- Kanguru Flash Trust (/dev/sdb)
- 6. Select the line containing SETUP 1 BOOT USB.49 Make note of the
- disk identifier (e.g. /dev/sdb).
- 7. Click "Make Startup Disk" and then click "Yes".
- 8. Wait a few minutes for the copying process to complete.
-
- 3. Verify the integrity of the SETUP 1 BOOT USB (i.e. no errors or malware
- 1. On your desktop, right-click the corresponding USB drive icon in
- your dock and select Eject from the pop-up menu.
- 2. Remove the USB drive from the USB slot and immediately
- re-insert it.
- 3. Wait 10 seconds for the operating system to recognize the USB.
- 4.
- ```
- $ cd $HOME/Downloads
- ```
- 5.
-
- $ sudo cmp -n `stat -c '%s' ubuntu-16.04.1-desktop-amd64.iso` ubuntu-16.04.1-desktop-amd64.iso USB-device-identifier-here
- 6. If prompted for a password, enter the computer's root password.
- 7. Wait a few minutes for the verification process to complete.
- 8. If all goes well, the command will output no data, returning to
- your usual terminal prompt.
- 9. If there is an issue, you'll see a message like:
- ```
- ubuntu-16.04.1-desktop-amd64.iso /dev/sda differ:
- byte 1, line 1
- ```
- If you see a message like this, STOP -- this may be a security
- risk. Restart this section from the beginning. If the issue
- persists, try using a different USB drive or a different Setup
- Computer.
-
-7. Create the Q1 BOOT USB
- 1. Boot the SETUP 1 computer from the SETUP 1 BOOT USB.
- 1. Reboot the computer.
- 2. Press your laptop's key sequence to bring up the boot device
- selection menu. (Some PCs may offer a boot device selection menu;
- see below.)
- 1. **PC**: Varies by manufacturer, but is often **F12** or **Del**. The
- timing may vary as well; try pressing it when the boot logo appears.
- 1. On the recommended Dell laptop, press F12. You should see a
- horizontal blue bar appear underneath the Dell logo.
- 2. The recommended Acer laptop does not have a boot menu. See
- below for instructions.
- 2. **Mac**: When you hear the startup chime, **press and hold
- Option (⌥)**.
-
- 3. Select the proper device to boot from.
- 1. **PC**: Varies by manufacturer; option will often say "USB"
- and/or "UEFI".
- 1. On the recommended Dell laptop, select "USB1" under "UEFI
- OPTIONS".
- 2. The recommended Acer laptop does not have a boot menu. See below
- for instructions.
- 2. **Mac**: Click the "EFI Boot" option and then click the up
- arrow underneath it.
-
- You do not need to select a network at this time. If more than
- one identical "EFI boot" option is shown, you may need to guess
- and reboot if you pick the wrong one.
-
- 4. Some laptops don't have a boot device selection menu, and you need to go into the BIOS configuration and change the boot order so that the USB drive is first.
- 1. On the recommended Acer laptop:
- 1. Press F2 while booting to enter BIOS configuration.
- 2. Navigate to the Boot menu.
- 3. Select USB HDD, and press F6 until it is at the top of the list.
- 4. Press F10 to save and automatically reboot from the USB.
- 5. If the computer boots into its regular OS rather than presenting you
- with a boot device or BIOS configuration screen, you probably pressed
- the wrong button, or waited too long.
- 1. Hold down your laptop's power button for 10 seconds. (The
- screen may turn black sooner than that; keep holding it down.)
- 2. Turn the laptop back on and try again. Spam the appropriate
- button(s) repeatedly as it boots.
- 3. If the computer boots *immediately* to where it left off, you
- probably didn't hold down the power button long enough.
- 6. You'll see a menu that says "GNU GRUB" at the top of the screen.
- Select the option "Try Ubuntu without installing" and press Enter.
- 7. The computer should boot into the USB's Ubuntu desktop.
-
- 2. Enable WiFi connectivity.
- 1. Click the cone-shaped WiFi icon near the right side of the menu bar.
- 2. If the dropdown says "No network devices available" at the top, you need to enable your networking drivers:
- 1. Click on "System Settings". It's the gear-and-wrench icon along
- the left side of the screen.
- 2. A System Settings window will appear. Click the "Software &
- Updates" icon.
- 3. A Software & Updates window will appear. Click the "Additional
- Drivers" tab.
- 4. In the Additional Drivers tab, you'll see a section for a
- Wireless Network Adapter. In that section, "Do not use the device"
- will be selected. Select any other option besides "Do not use the
- device.""
- 5. Click "Apply Changes".
- 6. Click the cone-shaped WiFi icon near the right side of the menu
- bar again. There should be a list of WiFi networks this time.
- 3. Select your WiFi network from the list and enter the password.
- 3. Repeat steps 1-6 using the SETUP 1 computer to create the Q1 BOOT USB
- rather than the SETUP 1 BOOT USB.
- 1. **The instruction to plug a Quarantined Boot USB into your Setup
- computer should raise a red flag for you, because you should never
- plug a quarantined USB into anything other than the quarantined
- computer it is designated for!**
-
- This setup process is the ONE exception.
- 2. Because you have booted the SETUP 1 computer off the SETUP 1 BOOT
- USB, you will follow the instructions for Ubuntu, even if your computer
- normally runs Windows or macOS.
- 3. Immediately after you are finished executing steps 1-6 with the Q1
- BOOT USB, remove the Q1 BOOT USB from the SETUP 1 computer.
- 1. On your desktop, right-click the corresponding USB drive icon
- in your dock and select Eject from the pop-up menu.
- 2. Remove the USB drive from the USB slot.
- 4. **The Q1 BOOT USB is now eternally quarantined. It should never again
- be plugged into anything besides the Q1 computer.**
-8. Create the SETUP 2 BOOT USB and Q2 BOOT USB
- 1. Repeat steps 1-7 using the SETUP 2 computer, SETUP 2 BOOT USB, and Q2
- BOOT USB.
+ Technical details: The GPG verification of some fingerprints in the
+ protocol are omitted because the checksum & checksum
+ signatures for this document were verified in the [Verify and print protocol document](/docs/setup/verify/#document-verification) section. For a detailed
+ security analysis, see the [design document](/docs/design-doc/overview).
+
+### Create the "SETUP 1 BOOT" USB drive
+
+**Windows**:
+1. Download and run [Rufus disk utility](https://rufus.akeo.ie/).
+2. Insert the "SETUP 1 BOOT" USB drive into an empty USB slot.
+3. In the "Device" dropdown at the top of the Rufus window, ensure the
+empty USB drive is selected.
+4. Next to the text "Create a bootable disk using", select "ISO Image"
+in the dropdown.
+5. Click the CD icon next to the "ISO Image" dropdown.
+6. In the file explorer that pops up, select `ubuntu-16.04.1-desktop-amd64.iso`
+from the downloads folder and click "Open".
+7. Click "Start".
+8. If prompted to download Syslinux software, click "Yes".
+9. When asked to write in "ISO Image Mode (Recommended)" or
+"DD Image Mode", select "ISO Image Mode" and press "OK".
+
+The program will take a few minutes to write the USB drive.
+
+**MacOS**:
+1. Prepare the Ubuntu download for copying to the USB drive:
+ ```
+ $ cd $HOME/Downloads
+ $ hdiutil convert ubuntu-16.04.1-desktop-amd64.iso -format UDRW -o ubuntu-16.04.1-desktop-amd64.img
+ ```
+2. Determine the MacOS "device identifier" for the Boot USB drive:
+ 1. List all disks and partitions:
+ ```
+ $ diskutil list
+ ```
+ 2. Insert the "SETUP 1 BOOT" USB drive in an empty USB slot.
+ 3. Wait 10 seconds for the operating system to recognize the USB drive.
+ 4. List all disks and partitions again:
+ ```
+ $ diskutil list
+ ```
+ 5. The output from the second `diskutil list` should include an additional
+ "(external, physical)" heading that was not present in the first `diskutil list`.
+ The first line of the section's "SIZE" column should reflect the capacity of the USB drive.
+ 6. Make a note of the device identifier, which is the part of the section header
+ that comes before "(external, physical)", for example "/dev/disk2". This will be referred
+ to as USB-device-identifier in the coming steps.
+
+3. Copy the Ubuntu image onto the "SETUP 1 BOOT" USB drive:
+ 1. Unmount the USB drive:
+ $ diskutil unmountDisk USB-device-identifier
+ 2. Enter the following command, **making sure to use the correct
+ device identifier; using the wrong one could overwrite the hard
+ drive!**:
+ $ sudo dd if=ubuntu-16.04.1-desktop-amd64.img.dmg of=USB-device-identifier bs=1m
+ Example:
+ ```
+ $ sudo dd if=ubuntu-16.04.1-desktop-amd64.img.dmg of=/dev/disk2 bs=1m
+ ```
+ 3. Enter the administrator password when requested.
+ 4. Wait several minutes for the copying process to complete.
+ 5. The resulting USB drive will not be readable by MacOS, which may result in an
+ error box pop up. This is expected; click "Ignore".
+
+4. Verify the integrity of the "SETUP 1 BOOT" USB drive to prove the absence of errors or
+malware infection:
+ 1. Remove the "SETUP 1 BOOT" USB drive from the USB slot and immediately reinsert it.
+ 2. Wait 10 seconds for the operating system to recognize the USB drive.
+ 3. The USB drive will, again, not be readable by MacOS, which may result in an
+ error box pop up. This is expected; click "Ignore".
+ 4. The USB drive's device identifier may have changed. List all disks and partitions again:
+ ```
+ $ diskutil list
+ ```
+ 5. Change the terminal’s current working folder to the download folder,
+ customizing the folder name if necessary:
+ ```
+ $ cd $HOME/Downloads
+ ```
+ 6. Compare the "SETUP 1 BOOT" USB drive to the verified image:
+ $ sudo cmp -n `stat -f '%z' ubuntu-16.04.1-desktop-amd64.img.dmg ubuntu-16.04.1-desktop-amd64.img.dmg` USB-device-identifier
+ 7. Wait a few minutes for the verification process to complete.
+ 8. Successful verification will return to the terminal prompt, outputting no data.
+ Failure will return a message showing how the USB drive differs from the downloaded image, for example:
+ ```
+ ubuntu-16.04.1-desktop-amd64.img.dmg /dev/disk2
+ differ: byte 1, line 1
+ ```
+ If a message is returned, **STOP**. This may be a security
+ risk. Restart the [Create the "SETUP 1 BOOT" USB drive](/docs/setup/create-boot-usb/#create-the-setup-1-boot-usb-drive)
+ section from the beginning. If the issue persists, try repeating with a
+ different USB drive or a different Setup Computer.
+
+**Linux**:
+
+Note that, for most applications (e.g. Firefox), copy and paste keyboard shortcuts are
+"Ctrl-C" and "Ctrl-V" respectively, but, in a terminal window, the shortcuts are
+"Ctrl-Shift-C" and "Ctrl-Shift-V".
+
+1. Copy the Ubuntu image onto the “SETUP 1 BOOT” USB drive:
+ 1. Open the Ubuntu search console by clicking the purple
+ circle/swirl icon in the upper-left corner of the screen.
+ 2. Type "startup disk creator" in the text box.
+ 3. Click on the "Startup Disk Creator" icon.
+ 4. The "Source disc image" panel should show the downloaded iso image file. If not,
+ click "Other" and manually locate the download folder.
+ 5. The "Disk to use" panel should show two devices. The device descriptions may
+ vary from system to system, but each one will have a device
+ identifier, highlighted in the example below:
+ Generic Flash Disk (/dev/sda)
+ Kanguru Flash Trust (/dev/sdb)
+ 6. Select the "SETUP 1 BOOT" USB drive and make note of the disk identifier (e.g.
+ "/dev/sdb"). This will be referred to as
+ USB-device-identifier in the coming steps.
+ 7. Click "Make Startup Disk" and then click "Yes".
+ 8. Wait a few minutes for the copying process to complete.
+
+2. Verify the integrity of the “SETUP 1 BOOT” USB drive to prove the absence
+of errors or malware infection:
+ 1. On the desktop, right-click the USB drive icon corresponding to the
+ "SETUP 1 BOOT" USB drive, and select "Eject" from the pop-up menu.
+ 2. Remove the USB drive from the USB slot and immediately re-insert it.
+
+ Technical details: In order to avoid detection, malware
+ may wait until a USB drive is in the process of ejecting (i.e. once all
+ integrity checks are completed) before infecting the USB drive. Ejecting and
+ re-inserting the USB drive before checking integrity is a simple defence against this.
+
+ 3. Wait 10 seconds for the operating system to recognize the USB drive.
+ 4. Change the terminal’s current working folder to the download folder,
+ customizing the folder name if necessary:
+ ```
+ $ cd $HOME/Downloads
+ ```
+ 5. Compare the "SETUP 1 BOOT" USB drive to the verified image:
+ $ sudo cmp -n `stat -c '%s' ubuntu-16.04.1-desktop-amd64.iso` ubuntu-16.04.1-desktop-amd64.iso USB-device-identifier
+ 6. Enter the root password if requested.
+ 7. Wait a few minutes for the verification process to complete.
+ 8. Successful verification will return to the terminal prompt, outputting no data.
+ Failure will return a message showing how the USB drive differs from the downloaded image, for example:
+ ```
+ ubuntu-16.04.1-desktop-amd64.iso /dev/sda differ:
+ byte 1, line 1
+ ```
+ If a message is returned, **STOP**. This may be a security
+ risk. Restart the [Create the "SETUP 1 BOOT" USB drive](/docs/setup/create-boot-usb/#create-the-setup-1-boot-usb-drive)
+ section from the beginning. If the issue persists, try using a
+ different USB drive or a different Setup Computer.
+
+### Create the "Q1 BOOT" USB drive
+
+1. Boot the "SETUP 1" computer from the "SETUP 1 BOOT" USB drive:
+ 1. Reboot the computer.
+ 2. Alter the boot device:
+
+ If a boot device selection menu is not available, the boot device
+ must be set in the BIOS configuration by putting the USB drive
+ first in the boot order. Since specific menus vary from manufacturer
+ to manufacturer, details are only offered for the recommended Acer laptop.
+
+ * **PC with boot device selection menu**:
+ 1. Depending on manufacturer, tap "F12" or "Del". Timing
+ can also vary, try tapping when the boot logo appears. Pressing
+ "F12" on the recommended Dell laptop should produce a horizontal
+ blue bar below the Dell boot logo to indicate the selection menu
+ will appear.
+ 2. Depending on manufacturer, option may say "USB" and/or "UEFI".
+ On the recommended Dell laptop, select "USB1" under "UEFI
+ OPTIONS".
+ * **PC without boot device selection menu**:
+ 1. Press "F2" when the boot logo appears.
+ 2. Navigate to the boot menu.
+ 3. Select "USB HDD", and press "F6" until it moves to the top of the list.
+ 4. Press "F10" to save and automatically reboot from the USB drive.
+ * **Mac**:
+ 1. Press and hold "Option" (⌥) when the startup chime is heard.
+ 2. Click the "EFI Boot" option and then click the up arrow below. Do not
+ select a network at this time. If more than one identical
+ "EFI boot" option is shown, guess and repeat if boot is not
+ successful.
+
+ If, while trying to get into either the BIOS or boot device selection menu,
+ the computer boots into its factory-installed operating system, the wrong button may have
+ been pressed, or not pressed soon enough. Hold down the power button for a full
+ ten seconds, even if the screen turns black sooner, and turn the computer back on.
+ Repeat this step, tapping the appropriate button(s) repeatedly as it boots. If
+ the computer boots *immediately* to where it left off, the power button was not
+ held down long enough and should be held down again.
+ 3. On successful reboot, the "GNU GRUB" menu will appear. Select the option "Try
+ Ubuntu without installing" and press "Enter". The computer should boot into the USB drive's
+ Ubuntu desktop.
+
+2. Enable WiFi connectivity:
+ 1. Click the cone-shaped WiFi icon near the right side of the menu bar.
+ 2. If the dropdown says "No network devices available" at the top, networking drivers
+ need enabled:
+ 1. Click on the gear-and-wrench icon along the left side of the screen to open
+ the system settings window.
+ 2. Click the "Software & Updates" icon to open the "Software & Updates" window
+ 3. Click the "Additional Drivers" tab.
+ 4. Select any other option besides "Do not use the device" in the "Wireless
+ Network Adapter" section.
+ 5. Click "Apply Changes".
+ 6. Click the cone-shaped WiFi icon near the right side of the menu
+ bar again. There should be a list of WiFi networks this time.
+ 3. Select the relevant WiFi network from the list and enter the password.
+3. Create the "Q1 BOOT" USB drive by repeating the
+[Download and verify Ubuntu](/docs/setup/create-boot-usb/#download-and-verify-ubuntu) and
+[Create the “SETUP 1 BOOT” USB](/docs/setup/create-boot-usb/#create-the-setup-1-boot-usb-drive)
+sections, replacing each occurance of "SETUP 1 BOOT" with "Q1 BOOT". During the repeat,
+take note of the following:
+ * The instruction to plug a Quarantined Boot USB drive into the Setup
+ Computer should raise a red flag, because **a quarantined USB drive should never be plugged into anything other than its designated quarantined computer!**.
+ This setup process is the **ONE** necessary exception.
+ * The "SETUP 1" computer should boot from the "SETUP 1 BOOT" USB drive this time, meaning
+ the Linux instructions are to be followed, even if the computer
+ normally runs Windows or MacOS.
+4. Immediately remove the "Q1 BOOT" USB drive from the "SETUP 1" computer:
+ 1. On the desktop, right-click the USB drive icon corresponding to the
+ "SETUP 1 BOOT" USB drive, and select "Eject" from the pop-up menu.
+ 2. Remove the "Q1 BOOT" USB drive from the USB slot.
+
+**The "Q1 BOOT" USB drive is now eternally quarantined and should only ever be plugged into the "Q1" computer.**
+
+## On Setup Computer “SETUP 2”
+
+### Create the "SETUP 2 BOOT" USB drive
+
+Create the "SETUP 2 BOOT" USB drive by repeating the
+[Download and verify Ubuntu](/docs/setup/create-boot-usb/#download-and-verify-ubuntu) and
+[Create the "SETUP 1 BOOT" USB drive](/docs/setup/create-boot-usb/#create-the-setup-1-boot-usb-drive)
+sections, replacing occurances of "SETUP 1" and "SETUP 1 BOOT" with
+"SETUP 2" and "SETUP 2 BOOT", respectively.
+
+### Create the "Q2 BOOT" USB drive
+
+Create the "Q2 BOOT" USB drive by repeating the
+[Create the "Q1 BOOT" USB drive](/docs/setup/create-boot-usb/#create-the-q1-boot-usb-drive)
+section, replacing occurances of "SETUP 1", "SETUP 1 BOOT" and "Q1 BOOT" with
+"SETUP 2", "SETUP 2 BOOT" and "Q2 BOOT", respectively.
\ No newline at end of file
diff --git a/_docs/setup/non-quarantined-hardware.md b/_docs/setup/non-quarantined-hardware.md
deleted file mode 100644
index 3721f36..0000000
--- a/_docs/setup/non-quarantined-hardware.md
+++ /dev/null
@@ -1,37 +0,0 @@
----
-title: Prepare non-quarantined hardware
-description: Learn how to set up your non-quarantined hardware for Glacier, the
- step-by-step protocol for storing bitcoins in a highly secure way
----
-
-1. Select two (2) computers which will be used as "Setup Computers" to set up USB
-drives.
-
- 1. Both Setup Computers must have Internet access.
- 2. You should have administrator access to both Setup Computers.
- 3. Importantly, at least one computer should be a computer that you *do not*
- own, or that doesn't spend much time on your home or office network.
-
- It's not technically ownership that's important. But computers you own are
- more likely to run the same software, have visited the same websites, or have
- been exposed to the same USB drives or networks -- and therefore to have the
- same malware.
-
-2. Using sticky notes, label the two Setup Computers "SETUP 1" and "SETUP 2".
-3. With a permanent marker, label two USB drives "SETUP 1 BOOT" and "SETUP
-2 BOOT".
-
- 1. Remember that, per the equipment list, you should have 4 remaining USB
- drives -- two from one manufacturer, and two from a *different* manufacturer.
-
-4. Run a virus scan on the Setup Computers. If you don't have virus scanning
-software installed, here are some options:
-
- * Windows: [Kaspersky](https://usa.kaspersky.com/) ($39.99/yr),
- [Avira](https://www.avira.com) (Free)
- * macOS: [BitDefender](https://www.bitdefender.com/) ($59.95/yr),
- [Sophos](https://home.sophos.com/) (Free)
- * Linux: Unnecessary
-
-5. If the virus scan comes up with any viruses, take steps to remove them.
-6. Once you have a clean virus scan, your Setup Computers are ready.
diff --git a/_docs/setup/prepare-hardware.md b/_docs/setup/prepare-hardware.md
new file mode 100644
index 0000000..a4040b8
--- /dev/null
+++ b/_docs/setup/prepare-hardware.md
@@ -0,0 +1,67 @@
+---
+title: Prepare hardware
+description: Learn how to set up your hardware for Glacier, the
+ step-by-step protocol for storing bitcoins in a highly secure way
+---
+
+## Non-quarantined hardware
+
+According to the specifications in the [Hardware required](/docs/before-you-start/hardware) section:
+
+1. Label the two Setup Computers "SETUP 1" and "SETUP 2", using sticky notes
+2. Label two USB drives "SETUP 1 BOOT" and "SETUP 2 BOOT", using a permanent marker
+3. Run a virus scan on both Setup Computers. Options for virus scanning include:
+
+ * **Windows**: [Kaspersky](https://usa.kaspersky.com/) ($39.99/yr),
+ [Avira](https://www.avira.com) (Free)
+ * **MacOS**: [BitDefender](https://www.bitdefender.com/) ($59.95/yr),
+ [Sophos](https://home.sophos.com/) (Free)
+ * **Linux**: Unnecessary
+
+5. Take steps to remove any viruses found by the virus scanners
+
+The Setup Computers are ready once the virus scan shows a clean system.
+
+## Quarantined hardware
+
+According to the specifications in the [Hardware required](/docs/before-you-start/hardware) section,
+paying *particular* attention to manfacturer requirements:
+
+1. Separate your quarantined hardware into two parallel sets:
+
+ * **Set 1**: "Q1" computer, "Q1 BOOT" USB drive, "Q1 APP" USB drive
+ * **Set 2**: "Q2" computer, "Q2 BOOT" USB drive, "Q2 APP" USB drive
+
+ The USB drives labeled "Q1 BOOT" and "Q2 BOOT" will have the operating system to
+ boot the corresponding computer.
+
+ The USB drives labeled "Q1 APP" and "Q2 APP" will have the software applications
+ for use on the corresponding computer.
+
+2. In each set, label all hardware with a permanent marker, writing directly on
+the hardware.
+
+ **Labeled hardware should only be used with
+ hardware within the same set**, for example:
+
+ 1. **Only** plug **"Q1 BOOT"** and **"Q1 APP"** USB drives into the **"Q1"** laptop
+ 2. **Only** plug **"Q2 BOOT"** and **"Q2 APP"** USB drives into the **"Q2"** laptop
+ 3. **Don't** plug an **unlabeled**, **"SETUP 1"** or **"SETUP 2"** USB drive into the **"Q1"** or **"Q2"** laptops
+
+4. Quarantine "Q1" and "Q2" computers by removing the network and wireless interfaces:
+
+ 1. Unbox computers, but do **not** power on
+ 2. Place a tamper-resistant seal over the Ethernet port, if present
+ 3. Physically remove the wireless card:
+
+ 1. If using the recommended Dell laptop, follow [Dell's official instructions](https://topics-cdn.dell.com/pdf/inspiron-11-3162-laptop_Service%20Manual_en-us.pdf),
+ or [Parts-People.Com, Inc](https://www.youtube.com/watch?v=nFYXQQPoh90)'s YouTube tutorial
+ 2. If using the recommended Acer laptop, the process is similar to the Dell, but note
+ that there are two cover screws hidden underneath the rubber feet on the underside of the laptop
+
+ 4. After removing the wireless cards, cover the ends of the internal wi-fi antennae with electrical tape
+ 5. If not using the recommended laptops, and the computers have separate WiFi and Bluetooth cards,
+ ensure both are removed. Most modern computers, including the recommended Acer and Dell,
+ have a single wireless/bluetooth card.
+
+5. Fully charge both computers, if relevant.
\ No newline at end of file
diff --git a/_docs/setup/quarantined-hardware.md b/_docs/setup/quarantined-hardware.md
deleted file mode 100644
index bb60fab..0000000
--- a/_docs/setup/quarantined-hardware.md
+++ /dev/null
@@ -1,55 +0,0 @@
----
-title: Prepare quarantined hardware
-description: Learn how to prepare your quarantined hardware for Glacier, the
- step-by-step protocol for storing bitcoins in a highly secure way
----
-
-1. Separate your quarantined hardware into two parallel sets. Each set should contain:
- - One laptop
- - Two USB drives from the same manufacturer
-
- Each component should be supplied by *different* manufacturers from the other set.
- I.e. your two laptops should be from two different manufacturers, and the USB
- drives in one set should be from a different manufacturer than the USB drives in
- the other set.
-
-2. In each set, label all hardware with a permanent marker. Write directly on
-the hardware.
-
- 1. Label the laptops ("Quarantined Computers") "Q1" and "Q2".
- 2. Label one USB drive from each set with "Q1 BOOT" or "Q2 BOOT".
- These USBs will have the operating system you'll boot the computer
- with.
- 3. Label the other USB drive from each set with "Q1 APP" or "Q2 APP". These
- USBs will have the software applications you'll use.
-
-3. **Labeled hardware should only be used with
- hardware that shares the same label ("Q1", "Q2", or "SETUP 1", or
- "SETUP 2").** For example:
-
- 1. **Don't** plug a **"Q1"** USB drive into a **"Q2"** laptop.
- 2. **Don't** plug a **"SETUP 2"** USB drive into a **"Q1"** or **"Q2"** laptop.
- 3. **Don't** plug an **unlabeled** USB drive into a **"Q1"** or **"Q2"** laptop.
-
-4. Quarantine the network and wireless interfaces for both laptops:
-
- 1. Unbox laptop. Do **not** power it on.
- 2. Put a [tamper-resistant seal](https://www.amazon.com/Security-Warranty-Hologram-Sequential-Numbering/dp/B0051JNB6A/ref=sr_1_1?ie=UTF8&qid=1471760406&sr=8-1&keywords=tamper+resistant+stickers)
- over the Ethernet port, if it has one.
- 3. Physically remove the wireless card.
-
- 1. For the recommended Dell laptop, Dell's official instructions for
- doing so are [here](http://topics-cdn.dell.com/pdf/inspiron-11-3162-laptop_Service%20Manual_en-us.pdf).
- A YouTube video showing an abbreviated procedure is
- [here](https://www.youtube.com/watch?v=nFYXQQPoh90).
- 2. For the recommended Acer laptop, the process is similar to the Dell.
- Note there are two cover screws hidden underneath rubber feet on the
- bottom of the laptop.
-
- 4. After removing the wireless card, cover the ends of the internal wi-fi
- antennae with electrical tape.
- 5. If the computer has separate cards for WiFi and Bluetooth, be sure to
- remove both. (Most modern laptops, including the recommended Acer and Dell,
- have a single wireless card which handles both.)
-
-5. Fully charge both laptops.
diff --git a/_docs/setup/quarantined-workspace.md b/_docs/setup/quarantined-workspace.md
index 6cac45d..d39a200 100644
--- a/_docs/setup/quarantined-workspace.md
+++ b/_docs/setup/quarantined-workspace.md
@@ -1,82 +1,75 @@
---
title: Prepare quarantined workspaces
-description: Learn how to prepare your quarantined hardware for Glacier, the
+description: Learn how to prepare the quarantined hardware for Glacier, the
step-by-step protocol for storing bitcoins in a highly secure way
---
-This section is meant to be done immediately before executing the Deposit or
-Withdrawal protocols. If you are executing the Setup Protocol for the
-first time and do **not** plan on executing the Deposit or Withdrawal protocol now, you can stop here.
+This section is to be followed immediately before executing the Deposit or
+Withdrawal protocols. There is no need to continue if no deposits or withdrawals
+are being executed.
-1. Block side channels
+## Block side channels
- [Side-channel attacks](https://en.wikipedia.org/wiki/Side-channel_attack)
- are a form of electronic threat based on the physical nature of computing
- hardware (as opposed to algorithms or their software implementations).
- Side channel attacks are rare, but it's relatively straightforward to
- defend against most of them.
+1. Visual side channel:
+ 1. Ensure that no humans or cameras (e.g. home security cameras, which
+ can be hacked) have visual line-of-sight to the Quarantined Computers.
+ 2. Close doors and window shades.
+2. Acoustic side channel:
+ 1. Choose a room where sound will not travel easily outside.
+ 2. Shut down nearby devices with microphones (e.g. smartphones and
+ other laptops).
+ 3. Plug in and turn on a table fan to generate white noise.
+3. Power side channel:
+ 1. Ensure both computers are fully charged as running out of battery
+ will mean starting over. Computers should run **only on battery power**
+ throughout this protocol.
+ 2. Unplug both Quarantined Computers from the wall.
+4. Radio and other side channels, including seismic, thermal, and magnetic:
+ 1. Turn off all other computers and smartphones in the room.
+ 2. Seal portable computing devices in the Faraday bag.
+ 3. Unplug desktop computers.
- 1. Visual side channel
- 1. Ensure that no humans or cameras (e.g. home security cameras, which
- can be hacked) have visual line-of-sight to the Quarantined Computers.
- 2. Close doors and window shades.
- 2. [Acoustic side channel](https://en.wikipedia.org/wiki/Acoustic_cryptanalysis)
- 1. Choose a room where sound will not travel easily outside.
- 2. Shut down nearby devices with microphones (e.g. smartphones and
- other laptops).
- 3. Plug in and turn on a table fan to generate white noise.
- 3. [Power side channel](http://sharps.org/wp-content/uploads/CLARK-ESORICS13.pdf)
- 1. Unplug both Quarantined Computers from the wall.
- 2. Run them **only on battery power** throughout this protocol.
- 3. Make sure they are fully charged first! If you run out of battery,
- you'll need to start over.
- 4. [Radio](https://cyber.bgu.ac.il/how-leak-sensitive-data-isolated-computer-air-gap-near-mobile-phone-airhopper/)
- and other side channels. Including
- [seismic](https://www.cc.gatech.edu/fac/traynor/papers/traynor-ccs11.pdf),
- [thermal](https://cyber.bgu.ac.il/bitwhisper-heat-air-gap/),
- and [magnetic](http://fc15.ifca.ai/preproceedings/paper_14.pdf).
- 1. Turn off all other computers and smartphones in the room.
- 2. Put portable computing devices in the Faraday bag and seal the bag.
- 3. Unplug desktop computers.
-2. Put your Q1 BOOT USB into an open slot in your Q1 computer.
-3. Boot off the USB drive. If you've forgotten how, refer to the procedure in Section IV.
-4. Plug the Q1 APP USB into the Q1 computer
-5. Copy the software from the Q1 computer's RAM disk.
- 1. Click the File Manager icon from the launchpad on the left side of the
+## On Quarantined Computer “Q1”
+
+1. Boot the “Q1” computer from the “Q1 BOOT” USB drive, referring to steps 1 and 2
+from [Create the “Q1 BOOT” USB drive](/docs/setup/create-boot-usb/#create-the-q1-boot-usb-drive)
+in the Create boot USB drives section if necessary.
+2. Insert the "Q1 APP" USB into the "Q1" computer.
+3. Copy the "Q1 APP" software to the "Q1" computer's RAM disk:
+ 1. Click the "File Manager" icon from the launchpad on the left side of the
screen.
- 2. Click on the App USB on the left of the file manager. It will look like
- the image on the right, but may have a different name.
- 3. Drag the contents of the USB to the "Home" directory on the left side of
- file manager.
-6. Open a copy of this document on the Q1 computer.
- 1. In the File Manager find the glacier folder. The PDF file for this
- document should be visible with the name "Glacier.pdf." Open it.
+ 2. Click on the "App USB" on the left of the file manager.
+ 3. Drag the contents of the "App USB" to the "Home" folder on the left side of
+ the file manager.
+4. Open the "Glacier.pdf" file on the "Q1" computer. It will be in the "glacier"
+folder, a sub-folder of "Home".
- You won't be able to click any external links in the document, since you
- don't have a network connection. If you need to look something up on the
- internet, do so in a distant room. Do not remove devices from the Faraday
- bag before doing going to the other room.
+ External links in the document will not be available, since there is no
+ network connection. If necessary, accessing the internet should be done in
+ a distant room. Do not remove devices from the Faraday bag before doing so.
-7. Open a Terminal window by pressing Ctrl-Alt-T.
-8. Install the application software on the Q1 computer's RAM disk.
+5. Open a terminal window by pressing "Ctrl-Alt-T".
+6. Install the application software on the Q1 computer's RAM disk:
```
$ cd ~/apps
$ sudo dpkg -i *.deb
```
-9. Change into the glacier directory. You'll be using this directory to execute
-software for the protocol.
+7. Change the terminal’s current working folder to the "glacier" folder. This folder
+will be used to execute software for the protocol:
```
$ cd ~/glacier
```
-10. Prepare GlacierScript for execution.
+8. Prepare GlacierScript for execution:
```
$ chmod +x glacierscript.py
```
-11. Prepare the "Quarantined Scratchpad" -- an empty file you'll use as a place
-to jot notes.
+9. Prepare the "Quarantined Scratchpad" for jotting notes:
1. Click the "Search your computer" icon at the top of the launcher along
the left side of the screen.
2. Type "text editor".
- 3. Click the Text Editor icon.
- 4. A blank window should appear.
-12. Repeat the above steps using the Q2 computer, Q2 SETUP USB and Q2 APP USB.
+ 3. Click the "Text Editor" icon to bring up a blank text editor window.
+
+## On Quarantined Computer “Q2”
+
+Repeat the above steps, replacing each occurance of "Q1" with "Q2", to prepare
+a quarantined workspace on the "Q2" computer.
\ No newline at end of file
diff --git a/_docs/setup/verify.md b/_docs/setup/verify.md
index 34f0f02..c6d1681 100644
--- a/_docs/setup/verify.md
+++ b/_docs/setup/verify.md
@@ -5,117 +5,109 @@ description: Learn how to set up for Glacier, the step-by-step protocol for
redirect_from: /docs/setup/
---
-The Setup Protocol is used to prepare hardware, and download and verify needed
-software & documentation.
-
-The first thing we need to do is verify the integrity of
-the Glacier protocol document (the one you are reading) to ensure that it
-has not been tampered with. After verifying the document, we'll print
-a hardcopy.
-
-Printing is important, because a verified electronic copy will not be
-accessible at all times during protocol execution due to reboots and other
-changes to the computing environment. Printing a hardcopy ensures there is
-always a verified copy of the document available.
-
-1. Find a computer which has Internet access, printer access, and which you have
-permission to install new software on. We'll refer to this computer as the
-"SETUP 1" computer.
-2. Review the errata for the version of Glacier you are using at
-https://github.com/GlacierProtocol/GlacierProtocol/releases.
-3. Download the latest full release of Glacier (*not* just the protocol document)
-at https://github.com/GlacierProtocol/GlacierProtocol/releases.
-4. If your browser does not automatically extract the ZIP file contents into a
-folder within your downloads directory, do so.
-5. Rename the folder to "glacier."
-6. If you have used Glacier before, *and* you know you have the Glacier public key
-imported into a local GPG keyring, skip the next step. (If you don't know,
-that's fine; proceed as normal.)
-7. Obtain the Glacier "public key," used to cryptographically verify the
- protocol document.
-
- **If you are ever using Glacier in the future and notice that this step has
- changed (or that this warning has been removed), there is a security risk.**
- Stop and
- seek assistance.
-
- 1. Access Glacier's Keybase profile at .
- 2. Click the string of letters and numbers next to the key icon.
- 3. In the pop-up that appears, locate the link reading "this key".
- 3. Right-click the link and select "Save Link As..." or "Download Linked File
- As..."
- 5. Name the file "glacier.asc".
-
-8. Download and install [GnuPG](https://gnupg.org/), the
- software we'll use for doing the
- cryptographic verification.
- See tech details.
-
- 1. **Windows**: Download and install the latest available version of
+This section outlines the download, verification and printing of the
+protocol document. A verified electronic copy will not be accessible at all times
+during protocol execution, due to reboots and other changes to the computing
+environment. Working from a hardcopy ensures there is always a verified copy of
+the document available.
+
+## On the "SETUP 1" computer
+
+The "SETUP 1" computer must have printer access.
+
+### Software preparation
+
+1. Review the errata for the version of Glacier used at
+[https://github.com/GlacierProtocol/GlacierProtocol/releases.](https://github.com/GlacierProtocol/GlacierProtocol/releases)
+2. Download the latest full release of Glacier (*not* just the protocol document)
+at [https://github.com/GlacierProtocol/GlacierProtocol/releases.](https://github.com/GlacierProtocol/GlacierProtocol/releases)
+3. Extract the downloaded ZIP file within the downloads folder, if the browser has not done so automatically.
+4. Rename the folder containing the extracted files as "glacier".
+
+ If the user has used Glacier before, *and* has the Glacier public key imported into a local GPG keyring, skip the next step.
+
+5. Obtain the Glacier PGP public key, used to cryptographically verify the protocol document.
+
+ Technical detail: Glacier's GPG keys are handled with good security practices.
+ They were generated while booting from an Ubuntu Live USB drive on a factory-new laptop
+ with the wireless card removed, and transferred via USB drive to a MacBook. The private
+ key is not stored in the cloud. The public key is hosted separately from the
+ software distributions, on [Keybase](https://keybase.io/), and secured with separate credentials stored
+ in password managers.
+
+ **If this step changes in future uses of Glacier, or this warning is removed, there is a security risk.**
+ Stop and seek assistance.
+ Technical detail: There is a chicken-and-egg problem here, in that this document
+ is giving instructions for how to verify itself. Any attacker that compromised
+ this document could also compromise these instructions so that the verification
+ (erroneously) passes. There is no way to prevent this, unless the reader is familiar
+ with the document before the compromise and recognizes that the verification
+ instructions have changed. This is why a direct download link to the public key
+ is not provided. If an attacker changed the link, it could very easily go unnoticed.
+ In the unfortunate event of a legitimate need to change the verification
+ instructions (i.e. to publish a new public key, or change the means of obtaining
+ the existing key), the announcement will first be disseminated publicly, signed (at a
+ minimum) with contributer personal keys, and hopefully with the keys of well-known
+ individuals from the Bitcoin community.
+
+ 1. Navigate to Glacier's Keybase profile at [keybase.io/glacierprotocol](https://keybase.io/glacierprotocol).
+ 2. Click the string of 16 letters and numbers, formatted "XXXX XXXX XXXX XXXX", next to the key icon.
+ 3. In the pop-up that appears, right-click the link reading "this key" and select
+ "Save Link As..." or "Download Linked File As...".
+ 4. Name the file "glacier.asc".
+
+6. Download and install [GnuPG](https://gnupg.org/), the software used for cryptographic
+verification. GnuPG is the same software recommended by the Electronic Frontier
+Foundation's [Surveillance Self-Defense](https://ssd.eff.org/en/about-surveillance-self-defense)
+protocol.
+
+ Technical details: Verification of the integrity of GnuPG itself is omitted.
+ Although a trusted installation is encouraged where possible, this
+ would require having access to a pre-existing, trusted installation of GnuPG.
+ For many Glacier users, this will not be easy to come by. The risk of an
+ unverified PGP installation is relatively small, since an attacker would have
+ to compromise not just the hosting of GPG distributions, but also the hosting
+ of other software distributions used by Glacier. Such a breach would
+ quickly be detected by the global community.
+
+ * **Windows**: Download and install the latest available version of
[Gpg4win](https://www.gpg4win.org/). Use the default
options.
- 2. **macOS**: Download and install the latest available version of
+ * **MacOS**: Download and install the latest available version of
[GPG Suite](https://gpgtools.org/).
- 3. **Linux**: GnuPG comes pre-installed with Linux distributions.
-
-9. Open a terminal window:
-
- 1. **Windows**: Press Windows-R, type "powershell" and click OK.
- 2. **macOS**: Click the Searchlight (magnifying glass) icon in the menu bar, and
- type a terminal window. "terminal". Select the Terminal application from the
- search results.
- 3. **Linux**: Varies; on Ubuntu, press Ctrl-Alt-T.
-
-10. Change the terminal window's active folder to your downloads folder. The
-commands below are based on common default settings; if you put your downloads
-is in a different place, you will need to customize this command.
-
- 1. **Windows**: `> cd $HOME/Downloads/glacier`
- 2. **macOS**: `$ cd $HOME/Downloads/glacier`
- 3. **Linux**: `$ cd $HOME/Downloads/glacier`
-
-11. Verify the integrity of the
-downloaded document.
-
-
- 1. Import the Glacier public key into your local GPG installation:
+ * **Linux**: GnuPG is pre-installed in Linux distributions.
+
+### Document verification
+
+7. Open a terminal window:
+
+ * **Windows**: Press Windows-R, type "powershell" and click OK.
+ * **MacOS**: Click the Searchlight (magnifying glass) icon in the menu bar, and
+ type "terminal". Select the Terminal application from the search results.
+ * **Linux**: Varies; on Ubuntu, press Ctrl-Alt-T.
+
+8. Change the terminal's current working folder to the download folder. The
+commands below are based on default settings; if the defaults have been altered,
+these commands will need customized to match.
+
+ * **Windows**:
+ ```
+ > cd $HOME/Downloads/glacier
+ ```
+ * **MacOS**:
+ ```
+ $ cd $HOME/Downloads/glacier
+ ```
+ * **Linux**:
+ ```
+ $ cd $HOME/Downloads/glacier
+ ```
+
+9. Verify the integrity of the downloaded document. For technical background about
+this process, see Wikipedia's [Digital signature](https://en.wikipedia.org/wiki/Digital_signature)
+entry.
+
+ 1. Import the Glacier public key into the local GPG installation:
```
$ gpg --import $HOME/Downloads/glacier.asc
```
@@ -125,40 +117,38 @@ https://en.wikipedia.org/wiki/Digital_signature.
$ gpg --verify SHA256SUMS.sig SHA256SUMS
```
Expected output (timestamp will vary, but e-mail and fingerprint should match):
-
- gpg: Signature made Fri Feb 10 22:23:45 2017 PST using RSA key ID 4B43EAB0
+ gpg: Signature made Fri Feb 10 22:23:45 2017 PST using RSA key ID 4B43EAB0
gpg: Good signature from "Glacier Team "
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: E1AA EBB7 AC90 C1FE 80F0 1034 9D1B 7F53 4B43 EAB0
-
- The warning message is expected, and is not cause
- for alarm.
+
3. Verify the fingerprints in the fingerprint file match the fingerprints of the
downloaded Glacier files.
- 1. On Linux or Mac:
+ * **Linux or MacOS**:
- Linux: `$ sha256sum -c SHA256SUMS 2>&1`
+ **Linux**: `$ sha256sum -c SHA256SUMS 2>&1`
- Mac: `$ shasum -a 256 -c SHA256SUMS 2>&1`
+ **MacOS**: `$ shasum -a 256 -c SHA256SUMS 2>&1`
Expected output:
```
@@ -166,26 +156,27 @@ https://en.wikipedia.org/wiki/Digital_signature.
base58.py: OK README.md: OK
```
- 2. On Windows 10:
+ * **Windows**:
```
> Get-FileHash -a sha256 Glacier.pdf
> cat SHA256SUMS | select-string -pattern "Glacier.pdf"
```
- Ensure that the hash output from the first command matches the output by the
- second command. Upper/lower case doesn't matter.
+ Ensure that the hash output from the first command matches the hash output of the
+ second command, irrespective of case.
+
+ **If you do not see the expected output, your copy of the document has not been verified**.
+ Stop and seek assistance.
- 4. If you do not see the expected output, your copy of the document has not been verified. Stop and seek assistance.
+### Hardcopy
-12. Switch to use the new document.
+10. Switch to use the new document.
- 1. Open the version of the document that you just verified.
- 2. Close this window (of the unverified version of the document you had been
- using).
+ 1. Open the newly verified version of the document.
+ 2. Close the unverified version of the document used until this point.
3. Delete the old, unverified copy of the document.
-13. Print the verified document.
+11. Print the verified document.
-You are strongly encouraged to use the printed copy as a checklist, physically
-marking off each step as you complete it. This reduces the risk of execution
-error by ensuring you don't lose your place.
+ Use of the printed copy as a checklist is strongly encouraged. Steps can be physically
+ marked off once completed. This reduces the risk of execution error by repeating or skipping steps.
diff --git a/_docs/withdrawal/preparation.md b/_docs/withdrawal/preparation.md
index a1a54f8..6ef8788 100644
--- a/_docs/withdrawal/preparation.md
+++ b/_docs/withdrawal/preparation.md
@@ -65,13 +65,13 @@ to withdraw.
[https://blockchain.info/tx/transaction-id-here?format=hex](https://blockchain.info/tx/transaction-id-here?format=hex)
Example page contents:
- 01000000016847105309a8604c7e4f5773d0a16c45248acce057dab62e
+ 01000000016847105309a8604c7e4f5773d0a16c45248acce057dab62e
db0fedc2810d49a4010000006b48304502210093e6b4154d42c1bba27c
548a80488673967be32c8de2f11e01a1402a5500e13302203e20874e5d
0af516c902d3b600ee94571a7ce68a14a384dc05d4346e1009fe000121
039fd6f25c87f183260c1d4a3a3ae33a2c06414db4c40d0c2ab76a7192
1fef0939ffffffff01e0930400000000001976a914e770a7c13f977478
- 3e80607f40be4547780315b688ac00000000
+ 3e80607f40be4547780315b688ac00000000
2. This entire page be referred to as a
**raw unspent transaction**.
diff --git a/_docs/withdrawal/transaction-construction.md b/_docs/withdrawal/transaction-construction.md
index c5bd010..f154755 100644
--- a/_docs/withdrawal/transaction-construction.md
+++ b/_docs/withdrawal/transaction-construction.md
@@ -27,8 +27,7 @@ to prepare your quarantined workspace.
feed, it has been successfully read.
3. Verify the decoded QR code is shown in the terminal window.
Example:
-
- QR-Code:51410421167f7dac2a159bc3957e3498bb6a7c2f16874bf1fbbe5b523b3632d2c0c43f1b491f6f2f449ae45c9b0716329c0c2dbe09f3e5d4e9fb6843af083e222a70a441043704eafafd73f1c32fafe10837a69731b93c0179fa268fc325bdc08f3bb3056b002eac4fa58c520cc3f0041a097232afbe002037edd5ebdab2e493f18ef19e9052ae
+ QR-Code:51410421167f7dac2a159bc3957e3498bb6a7c2f16874bf1fbbe5b523b3632d2c0c43f1b491f6f2f449ae45c9b0716329c0c2dbe09f3e5d4e9fb6843af083e222a70a441043704eafafd73f1c32fafe10837a69731b93c0179fa268fc325bdc08f3bb3056b002eac4fa58c520cc3f0041a097232afbe002037edd5ebdab2e493f18ef19e9052ae
4. Copy-paste the decoded data (everything *after*, but not
including, "QR-code:") into the Quarantined Scratchpad.
5. Make a note of what the data is, based on your handwritten
@@ -84,8 +83,7 @@ to prepare your quarantined workspace.
9. The script will output a "raw signed transaction" and a *fingerprint* of the signed transaction for verification purposes.
Example output:
-
- Sufficient private keys to execute transaction?
+ Sufficient private keys to execute transaction?
True
Raw signed transaction (hex): 01000000013cd6b24735801ad3d04c40e6da3404278b0d38dbc896df6ae50bf11c3043a49600000000fda001004730440220199d247cd11c14fa4960a52467e69ca6b77596e94c14f27ba956315f2d1c852302201b6f41ecfc62a1a7c7a423425ab150301cfffc47c1a78a5bf13b8232f767e41301483045022100e7ae7e5a77da47d5e622f974683a43d312e72a1eed329d4fdbd8fba2c22f84b4022050358fb63cf182e81905417d6e38a2981563495dd00c3177ee650ff7cd2d511a014d0b01524104fe0fcd054a31130749467f07e272426f7dd7a3029ab5b076d7285a931bd131d34ed9f28b2cc2fe266aa62c4cada3e82b70a4416966902201c4d73759f7f0425e41044f2ec9f80ef2c4f385f3d27b6167f77236de63548723ba1c90a324f4ec46dfd14a2fba5a9c048a5ec310aedfe875d8a254f336e8f7d5d17338d9451dc6f2188c4104aefb86098442adc6c3dffd9b0e27fe8e918462469a5ec5363e26920f09facea70b63e4f4d2736089286d4dd2352ca65016e7d593f105009f9a35c03a2464aa20410451e7f31ea2f5cb14ba76ca20952c1d453fe3a85959ebbefee8912ad6f74c443a03e52ef8a842f890f1ab2d69c6bb418e6de0f15bef944be2883887be3bb75cc054aeffffffff0194960700000000001976a914c018da1cb43c5d7b9e7757805ee78709f8a61ede88ac00000000
@@ -93,7 +91,7 @@ to prepare your quarantined workspace.
Transaction fingerprint (md5):
c49c366908296ae12478539d29fb4146
- QR code for transaction in transaction.png
+ QR code for transaction in transaction.png
3. Verify transaction construction
1. **On the Q2 computer**, repeat step 2 above.
diff --git a/_includes/topbar.html b/_includes/topbar.html
index 506f355..fc2d380 100644
--- a/_includes/topbar.html
+++ b/_includes/topbar.html
@@ -14,7 +14,7 @@
diff --git a/dockerfiles/spellcheck/.spelling b/dockerfiles/spellcheck/.spelling
index 5615923..4e2a7b5 100644
--- a/dockerfiles/spellcheck/.spelling
+++ b/dockerfiles/spellcheck/.spelling
@@ -8,7 +8,7 @@ Kraken
Bitfinex
SanDisk
Cruzer
-macOS
+MacOS
TerraSlate
Inspiron
Bitclip
diff --git a/index.html b/index.html
index 5661823..deba056 100644
--- a/index.html
+++ b/index.html
@@ -6,7 +6,7 @@
Glacier
Glacier is the step-by-step protocol for storing Bitcoins in a highly secure way, offline.
-
Learn more
+
Learn more