Fix code blocks and update subkey section

SplitGpg.md

@@ -19,17 +19,18 @@ The diagram below presents the big picture of Split GPG architecture.
 
 ![split-gpg-diagram.png](/attachment/wiki/SplitGpg/split-gpg-diagram.png)
 
-### Advantages of Split GPG vs. traditional GPG with a smart card
+### Advantages of Split GPG vs. traditional GPG with a smart card ###
 
 It is often thought that the use of smart cards for private key storage guarantees ultimate safety. While this might be true (unless the attacker can find a usually-very-expensive-and-requiring-physical-presence way to extract the key from the smart card) but only with regards to the safety of the private key itself. However, there is usually nothing that could stop the attacker from requesting the smart card to perform decryption of all the user documents the attacker has found or need to decrypt. In other words, while protecting the user's private key is an important task, we should not forget that ultimately it is the user data that are to be protected and that the smart card chip has no way of knowing the requests to decrypt documents are now coming from the attacker's script and not from the user sitting in front of the monitor. (Similarly the smart card doesn't make the process of digitally signing a document or a transaction in any way more secure -- the user cannot know what the chip is really signing. Unfortunately this problem of signing reliability is not solvable by Split GPG)
 
 With Qubes Split GPG this problem is drastically minimized, because each time the key is to be used the user is asked for consent (with a definable time out, 5 minutes by default), plus is always notified each time the key is used via a tray notification from the domain where GPG backend is running. This way it would be easy to spot unexpected requests to decrypt documents.
 
-![r2-split-gpg-1.png](/attachment/wiki/SplitGpg/r2-split-gpg-1.png) ![r2-split-gpg-3.png](/attachment/wiki/SplitGpg/r2-split-gpg-3.png)
+![r2-split-gpg-1.png](/attachment/wiki/SplitGpg/r2-split-gpg-1.png)
+![r2-split-gpg-3.png](/attachment/wiki/SplitGpg/r2-split-gpg-3.png)
 
-### Current limitations
+### Current limitations ###
 
--   Current implementation requires importing of public keys to the vault domain. This opens up an avenue to attack the gpg running in the backend domain via a hypothetical bug in public key importing code. See ticket \#474 for more details and plans how to get around this problem, as well as the section on [using split GPG with subkeys](/doc/SplitGpg#Advanced:UsingSplitGPGwithSubkeys) below.
+-   Current implementation requires importing of public keys to the vault domain. This opens up an avenue to attack the gpg running in the backend domain via a hypothetical bug in public key importing code. See ticket \#474 for more details and plans how to get around this problem, as well as the section on [using split GPG with subkeys](#advanced-using-split-gpg-with-subkeys) below.
 
 -   It doesn't solve the problem of allowing the user to know what is to be signed before the operation gets approved. Perhaps the GPG backend domain could start a Disposable VM and have the to-be-signed document displayed there? To Be Determined.
 
@@ -40,11 +41,10 @@ Configuring and using Split GPG
 
 Start with creating a dedicated AppVM for storing your keys (the GPG backend domain). It is recommended that this domain be network disconnected (set its netvm to `none`) and only used for this one purpose. In later examples this AppVM is named `work-gpg`, but of course it might have any other name.
 
-### Setting up the GPG backend domain
+### Setting up the GPG backend domain ###
 
 Make sure the gpg is installed there and there are some private keys in the keyring, e.g.:
 
-```
     [user@work-gpg ~]$ gpg -K
     /home/user/.gnupg/secring.gpg
     -----------------------------
@@ -52,19 +52,15 @@ sec   4096R/3F48CB21 2012-11-15
     uid                  Qubes OS Security Team <security@qubes-os.org>
     ssb   4096R/30498E2A 2012-11-15
     (...)
-```
 
 This is pretty much all that is required. However one might also want to modify the default timeout which tells the backend for how long the user's approval for key access should be valid (default 5 minutes). This is adjustable via `QUBES_GPG_AUTOACCEPT` variable. One can override it e.g. in `~/.bash_profile`:
 
-```
     [user@work-gpg ~]$ echo "export QUBES_GPG_AUTOACCEPT=86400" >> ~/.bash_profile
-```
 
-### Configuring the client apps to use split GPG backend
+### Configuring the client apps to use split GPG backend ###
 
 Normally it should be enough to set the `QUBES_GPG_DOMAIN` to the GPG backend domain name and use `qubes-gpg-client` in place of `gpg`, e.g.:
 
-```
     [user@work ~]$ export QUBES_GPG_DOMAIN=work-gpg
     [user@work ~]$ gpg -K
     [user@work ~]$ qubes-gpg-client -K
@@ -77,11 +73,10 @@ ssb   4096R/30498E2A 2012-11-15
     
     [user@work ~]$ qubes-gpg-client secret_message.txt.asc 
     (...)
-```
 
 Note that running normal `gpg -K` in the demo above shows no private keys stored in this AppVM.
 
-### Configuring Thunderbird/Enigmail for use with Split GPG
+### Configuring Thunderbird/Enigmail for use with Split GPG ###
 
 However, when using Thunderbird with Enigmail extension it is not enough, because Thunderbird doesn't preserve the environment variables. Instead it is recommended to use a simple script provided by `/usr/bin/qubes-gpg-client-wrapper` file by pointing Enigmail to use this script instead of the standard GnuPG binary:
 
@@ -89,14 +84,12 @@ However, when using Thunderbird with Enigmail extension it is not enough, becaus
 
 The script also sets the QUBES\_GPG\_DOMAIN variable automatically based on the content of the file `/rw/config/gpg-split-domain`, which should be set to the name of the GPG backend VM. This file survives the AppVM reboot, of course.
 
-```
     [user@work ~]$ sudo bash
     [user@work ~]$ echo "work-gpg" > /rw/config/gpg-split-domain
-```
 
 *NOTE*: A recent engimail update, version `thunderbird-enigmail-1.7-1`, introduced changes in how Enigmail expects to execute GPG binary and so requires an updated split-gpg package with version \>= `qubes-gpg-split-2.0.7-1`. Please make sure you have all the latest qubes packages installed in your template.
 
-### How to use `gpg2` instead of `gpg`
+### How to use `gpg2` instead of `gpg` ###
 
 In your GPG backend domain's TemplateVM:
 
@@ -105,59 +98,63 @@ In your GPG backend domain's TemplateVM:
 3. Ensure that your key has a **blank passphrase**. If not, you will encounter an error.
 4. Shut down the TemplateVM and restart the GPG backend domain.
 
-### Importing public keys
+### Importing public keys ###
 
 Use `qubes-gpg-import-key` in the client AppVM to import the key into the GPG backend VM. Of course a (safe, unspoofable) user consent dialog box is displayed to accept this.
 
-```
     [user@work ~]$ export QUBES_GPG_DOMAIN=work-gpg
     [user@work ~]$ qubes-gpg-import-key ~/Downloads/marmarek.asc
-```
 
 ![r2-split-gpg-5.png](/attachment/wiki/SplitGpg/r2-split-gpg-5.png)
 
 Advanced: Using Split GPG with Subkeys
 --------------------------------------
 
-Users with particularly high security requirements may wish to use split GPG with [​subkeys](https://wiki.debian.org/Subkeys). However, this setup comes at a significant cost: It will be impossible to sign other people's keys with the master secret key without breaking this security model. Nonetheless, if signing others' keys is not required, then split GPG with subkeys offers unparalleled security for one's master secret key.
+Users with particularly high security requirements may wish to use Split GPG with [​subkeys](https://wiki.debian.org/Subkeys). However, this setup comes at a significant cost: It will be impossible to sign other people's keys with the master secret key without breaking this security model. Nonetheless, if signing others' keys is not required, then Split GPG with subkeys offers unparalleled security for one's master secret key.
 
-### Setup Description
+### Setup Description ###
 
-In this example, the following keys are stored in the following locations:
+In this example, the following keys are stored in the following locations (see below for defintions of these terms):
 
-||
+| PGP Key(s) | VM Name      |
-|**PGP Key(s)**|**VM Name**|
+| ---------- | ------------ |
-|master secret key|vault|
+| `sec`      | `vault`      |
-|secret subkeys|work-gpg|
+| `ssb`      | `work-gpg`   |
-|public key|work-email|
+| `pub`      | `work-email` |
 
-master secret key (sec)  
+**Master secret key** (`sec`)  
-It is recommended that this key be created as a **certify-only (C)** key, i.e., a key which is capable only of signing other keys. This key may be created *without* an expiration date. This is for two reasons. First, the master secret key is never to leave the vault VM, so it is extremely unlikely ever to be obtained by an adversary (see below). Second, an adversary who *does* manage to obtain the master secret key either possesses the passphrase to unlock the key, or he does not. If he does, then he can simply use the passphrase in order to legally extend the expiration date of the key (or remove it entirely). If he does not, then he cannot use the key. In either case, an expiration date provides no additional benefit. It is, however, recommended that a **revocation certificate** be created so that the master keypair may be revoked in the (exceedingly unlikely) event that an adversary obtains both the master secret key *and* the passphrase. It is recommended that the master secret key passphrase only ever be input in the vault VM. (Subkeys should use a different passphrase; see below).
+Depending on your needs, you may wish to create this as a **certify-only (C)** key, i.e., a key which is capable only of signing (a.k.a., "certifying") other keys. This key may be created *without* an expiration date. This is for two reasons. First, the master secret key is never to leave the `vault` VM, so it is extremely unlikely ever to be obtained by an adversary (see below). Second, an adversary who *does* manage to obtain the master secret key either possesses the passphrase to unlock the key (if one is used), or he does not. If he does, then he can simply use the passphrase in order to legally extend the expiration date of the key (or remove it entirely). If he does not, then he cannot use the key at all. In either case, an expiration date provides no additional benefit.
 
-secret subkeys (ssb)  
+By the same token, however, having a passphrase on the key is of little value. An adversary who is capable of stealing the key from your `vault` would almost certainly also be capable of stealing the passphrase as you enter it. An adversary who obtains the passphrase can then use it in order to change or remove the passphrase from the key. Therefore, using a passphrase at all should be considered optional. It is, however, recommended that a **revocation certificate** be created and safely stored in multiple locations so that the master keypair can be revoked in the (exceedingly unlikely) event that it is ever compromised.
-It is recommended that two subkeys be created: one for **signing (S)**, and one for **encryption (E)**. It is further recommended that a *different* passphrase be used for these subkeys than for the master secret key. Finally, it is recommended that each of these subkeys be created with a reasonable expiration date (e.g., one year), and that a *new* set of subkeys be created whenever the existing set expires, rather than the expiration date of the existing keys being extended. This is because an adversary who obtains any existing encryption subkey (for example) will be able to use it in order to decrypt all emails (for example) which were encrypted with that subkey. If the same subkey were to continue to be used--and its expiration date continually extended--only that one key would need to be stolen (e.g., as a result of the work-gpg VM being compromised; see below) in order to decrypt *all* of the user's emails. If, on the other hand, each encryption subkey is used for at most approximately one year, then an adversary who obtains the secret subkey will be capable of decrypting at most approximately one year's worth of emails.
 
-public key (pub)  
+**Secret subkeys** (`ssb`)  
-This is the complement of the master secret key. It should be uploaded to keyservers and may be signed by others.
+Depending on your needs, you may wish to create two different subkeys: one for **signing (S)** and one for **encryption (E)**. You may also wish to give these subkeys reasonable expiration dates (e.g., one year). Once these keys expire, it is up to you whether to *renew* these keys by extending the expiration dates or to create *new* subkeys when the existing set expires.
 
-vault  
+On the one hand, an adversary who obtains any existing encryption subkey (for example) will be able to use it in order to decrypt all emails (for example) which were encrypted to that subkey. If the same subkey were to continue to be used--and its expiration date continually extended--only that one key would need to be stolen (e.g., as a result of the `work-gpg` VM being compromised; see below) in order to decrypt *all* of the user's emails. If, on the other hand, each encryption subkey is used for at most approximately one year, then an adversary who obtains the secret subkey will be capable of decrypting at most approximately one year's worth of emails.
-This is a network-isolated VM. The initial master keypair and subkeys are generated in this VM. The master secret key *never* leaves this VM under *any* circumstances. No files or text is *ever* [copied](/wiki/CopyingFiles#Oninter-domainfilecopysecurity) or [pasted](/wiki/CopyPaste#Clipboardautomaticpolicyenforcement) into this VM under *any* circumstances.
 
-work-gpg  
+On the other hand, creating a new signing subkey each year without renewing (i.e., extending the expiration dates of) existing signing subkeys would mean that all of your old signatures would eventually read as "EXPIRED" whenever someone attempts to verify them. This can be problematic, since there is no consensus on how expired signatures should be handled. Generally, digital signatures are intended to last forever, so this is a strong reason against regularly retiring one's signing subkeys.
-This is a network-isolated VM. This VM is used *only* as the GPG backend for work-email. The secret subkeys (but *not* the master secret key) are [copied](/wiki/CopyingFiles) from the vault VM to this VM. Files from less trusted VMs are *never* copied into this VM under *any* circumstances.
 
-work-email  
+**Public key** (`pub`)  
-This VM has access to the mail server. It accesses the work-gpg VM via the split GPG protocol. The public key may be stored in this VM so that it can be attached to emails and for other such purposes.
+This is the complement of the master secret key. It can be uploaded to keyservers (or otherwise publicly distributed) and may be signed by others.
 
-### Security Benefits
+`vault`  
+This is a network-isolated VM. The initial master keypair and subkeys are generated in this VM. The master secret key *never* leaves this VM under *any* circumstances. No files or text is *ever* [copied](/doc/CopyingFiles#on-inter-domain-file-copy-security) or [pasted](/doc/CopyPaste#on-copypaste-security) into this VM under *any* circumstances.
 
-In the standard split GPG setup, there are at least two ways in which the work-gpg VM might be compromised. First, an attacker who is capable of exploiting a hypothetical bug in work-email's [​MUA](https://en.wikipedia.org/wiki/Mail_user_agent) could gain control of the work-email VM and send a malformed request which exploits a hypothetical bug in the GPG backend (running in the work-gpg VM), giving the attacker control of the work-gpg VM. Second, a malicious public key file which is imported to the work-gpg VM might exploit a hypothetical bug in the GPG backend which is running there, again giving the attacker control of the work-gpg VM. In either case, such an attacker might then be able to leak both the master secret key and its passphrase (which is regularly input in the work-gpg VM and is therefore easily obtained by an attacker who controls this VM) back to the work-email VM or to another VM (e.g., the netvm, which is always untrusted by default) via the split GPG protocol or other [covert channels](/wiki/DataLeaks).
+`work-gpg`  
+This is a network-isolated VM. This VM is used *only* as the GPG backend for `work-email`. The secret subkeys (but *not* the master secret key) are [copied](/doc/CopyingFiles) from the `vault` VM to this VM. Files from less trusted VMs are *never* [copied](/doc/CopyingFiles#on-inter-domain-file-copy-security) into this VM under *any* circumstances.
 
-In the alternative setup described in this section (i.e., the subkey setup), even an attacker who manages to gain access to the work-gpg VM will not be able to obtain the user's master secret key since it is simply not there. Rather, the master secret key remains in the vault VM, which is extremely unlikely to be compromised, since nothing is ever copied or transferred into it.<sup>\*</sup> The attacker might nonetheless be able to leak the secret subkeys from the work-gpg VM in the manner described above, but even if this is successful, the secure master secret key can simply be used to revoke the compromised subkeys and to issue new subkeys in their place.
+`work-email`  
+This VM has access to the mail server. It accesses the `work-gpg` VM via the Split GPG protocol. The public key may be stored in this VM so that it can be attached to emails and for other such purposes.
 
-<sup>\*</sup>In order to gain access to the vault VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a [signed, compromised package which is already installed in the TemplateVM](/wiki/SoftwareUpdateVM#NotesontrustingyourTemplateVMs) upon which the vault VM is based.
+### Security Benefits ###
 
-### Subkey Tutorials and Discussions
+In the standard Split GPG setup, there are at least two ways in which the `work-gpg` VM might be compromised. First, an attacker who is capable of exploiting a hypothetical bug in `work-email`'s [​MUA](https://en.wikipedia.org/wiki/Mail_user_agent) could gain control of the `work-email` VM and send a malformed request which exploits a hypothetical bug in the GPG backend (running in the `work-gpg` VM), giving the attacker control of the `work-gpg` VM. Second, a malicious public key file which is imported into the `work-gpg` VM might exploit a hypothetical bug in the GPG backend which is running there, again giving the attacker control of the `work-gpg` VM. In either case, such an attacker might then be able to leak both the master secret key and its passphrase (if any is used, it would regularly be input in the work-gpg VM and therefore easily obtained by an attacker who controls this VM) back to the `work-email` VM or to another VM (e.g., the `netvm`, which is always untrusted by default) via the Split GPG protocol or other [covert channels](/doc/DataLeaks). Once the master secret key is in the `work-email` VM, the attacker could simply email it to himself (or to the world).
+
+In the alternative setup described in this section (i.e., the subkey setup), even an attacker who manages to gain access to the `work-gpg` VM will not be able to obtain the user's master secret key since it is simply not there. Rather, the master secret key remains in the `vault` VM, which is extremely unlikely to be compromised, since nothing is ever copied or transferred into it.<sup>\*</sup> The attacker might nonetheless be able to leak the secret subkeys from the `work-gpg` VM in the manner described above, but even if this is successful, the secure master secret key can simply be used to revoke the compromised subkeys and to issue new subkeys in their place. (This is significantly less devastating than having to create a new *master* keypair.)
+
+<sup>\*</sup>In order to gain access to the `vault` VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a [signed, compromised package which is already installed in the TemplateVM](/doc/SoftwareUpdateVM#notes-on-trusting-your-template-vms) upon which the `vault` VM is based.
+
+### Subkey Tutorials and Discussions ###
 
 (Note: Although the tutorials below were not written with Qubes Split GPG in mind, they can be adapted with a few commonsense adjustments. As always, exercise caution and use your good judgment.)