Merge branch 'neal/copyedit' into 'main'

Copy edit the text.

See merge request sequoia-pgp/sq-user-guide!6

1 files changed, 80 insertions, 79 deletions

diff --git a/sq-guide.md b/sq-guide.md
index 8d22440..d8d2ad4 100644
--- a/sq-guide.md
+++ b/sq-guide.md
@@ -10,7 +10,7 @@ documentclass: report
 This document is very much a work in progress. Nothing is finished and
 final. Parts haven't been
 written yet. That said, feedback on what is written, or the structure
-of the document, is very much welcome. The source code for this
+of the document is very much welcome. The source code for this
 document is in version control on the `gitlab.com` site at:
 
 ```
@@ -100,23 +100,24 @@ is aimed at users of the `sq` tool.
 
 ## Why use OpenPGP?
 
-Cryptography is used for several reasons:
+The cryptography in OpenPGP helps with three main problems:
 
-* to keep private things private
-* to make sure data hasn't been changed
-* to make sure from whom communication comes from
+* keeping private things private
+* identifying if data has changed
+* authenticating communication
 
-The OpenPGP standard provides for all these use cases, as well as
-providing protocols and data formats for managing the ecosystem of
+The OpenPGP standard also
+specifies protocols and data formats for managing the ecosystem of
 OpenPGP users. The standard specifies, for example, what form
 cryptographic messages take. This allows different parties in a
-communication can use different programs. One correspondent might be
-using a laptop computer, and while another uses a mobile phone. The
+communication to use different programs. One correspondent might
+use a laptop computer, while another may uses a mobile phone. The
 software running on those will be radically different, but as long as
-they follow the same standard, secure communication is no problem.
+they follow the same standard, secure communication using OpenPGP is
+possible.
 
 
-## Who this guide is aimed for?
+## Who is this guide aimed for?
 
 This guide is aimed at those who want to
 communicate privately, and receive and send messages and data safely with other
@@ -124,14 +125,14 @@ people. The guide does not require any background in cryptography,
 mathematics, or programming, but does require using a computer via the
 command line.
 
-However, note that this guide aims to getting the reader to a point
+However, note that this guide aims to get the reader to a point
 where they can use cryptography at all. It does not aim to teach the
 reader how to protect against motivated, targeted attacks from
-organized crime or intelligence organizations. Such protection will
-probably build on top of cryptography, but is outside the scope of
+organized crime, or intelligence organizations. Such protection will
+probably build on top of cryptography, but it is outside the scope of
 this guide.
 
-You can think of this guide giving you a way for the first turn of the
+You can think of this guide as giving you the first turn of the
 _security rachet_. Every turn of the ratchet improves security a
 little bit, but achieving protection against targeted attacks will
 require a great many turns.
@@ -142,8 +143,8 @@ require a great many turns.
 This guide covers the important concepts in using cryptography as
 specified by the OpenPGP standard:
 
-* keys, certificates, and managing them
-* certifying names attached to keys
+* keys, certificates, and their management
+* certifying that a name or email address should be associated with a key
 * signing files and verifying signatures
 * encrypting and decrypting data
 
@@ -162,11 +163,11 @@ This guide has the following structure:
   want to see how to do a few basic things. That chapter provides no
   explanation, just shows the commands. You can safely skip it if you
   want to.
-* The appendixes show how to perform tasks to achieve specific goals.
+* The appendices show how to perform tasks to achieve specific goals.
   These are expanded versions of the prelude
   examples, but with detailed, step-by-step explanations of
-  everything. These "how to" guides are useful for getting things
-  done, without having to wade through long discussions about
+  everything. These "how-to" guides are useful for getting things
+  done without having to wade through long discussions about
   underlying concepts.
 * There is also an appendix with a glossary, which can be helpful for
   looking up unknown terminology, and another appendix with links to
@@ -197,7 +198,7 @@ apt install sq
 ```
 
 Note that on Debian 11 (bullseye), the version of `sq` is rather old.
-You may want to install a back-ported version, from the usual Debian
+You may want to install a back-ported version from the usual Debian
 location for them.
 
 ### Fedora
@@ -232,7 +233,7 @@ FIXME.
 To build and install `sq` from source, you need to have the [Rust][]
 toolchain installed, in particular `cargo` and `rustc`. You also need
 a number of non-Rust build dependencies installed; see the
-[README.md][] for an up to date list.
+[README.md][] for an up-to-date list.
 
 To build and install the latest released version of `sq`, run the
 following command:
@@ -264,19 +265,19 @@ to happen without rampant theft. It also allows journalists working on
 stories about the rich, powerful, or corrupt to communicate with their
 sources without fear of prematurely revealing what they're doing.
 
-Cryptography use mathematics to turn messages into on opaque form and
-back, using a secret key. The opaque form, also known as _ciphertext_,
+Cryptography uses mathematics to turn messages and a key into an opaque form and
+back. The opaque form, also known as _ciphertext_,
 is impossible for anyone to understand without the use of the key. As
-long as the secret remains secret, the contents of communication is
+long as the secret key remains secret, the content of the communication is
 kept secure.
 
 A key is a very large random number used for encryption and digital
 signatures. In public key cryptography a key consists of a private and
-a public part. In `sq`, the private part is called just  _key_, and
+a public part. In `sq`, the private part is just called the  _key_, and
 you keep it secret. The public part is called a _certificate_ and
-you're meant to share it with anyone who might use it.
+you're meant to share it with anyone you want to communicate with.
 
-The private and public parts (key and certificate) are tied together
+The private and public parts (the key and the certificate) are tied together
 with mathematics in such a way that they have a very useful feature:
 if you encrypt something using the public part, the result can only be
 decrypted with the private part. And also vice versa: if you encrypt
@@ -366,9 +367,9 @@ is always good.
 
 ## Limitations of cryptography
 
-Whenever thinking about cryptography it's important to remember that
+When thinking about cryptography it's important to remember that
 it has limitations. For example, no cryptography can prevent the
-intended recipient from wilfully sharing an encrypted a message they
+intended recipient from willfully sharing an encrypted message they
 receive. If you send a photo of your safe combination to someone,
 encrypted with their certificate, they can decrypt it, and share the
 picture with the highest bidder.
@@ -401,14 +402,14 @@ know.
 # General principles of the `sq` interface
 
 `sq` is a command line tool using subcommands and options. Global
-options come before subcommand on the command line, and options
+options come before the subcommand on the command line, and options
 specific to the subcommand come after.
 
 Some options have both long and short forms. Thus, for example,
-`--output` may be shortened to just `-o` if the user wants to. The
+`--output` may be shortened to just `-o`. The
 examples in this guide use the long form, as that's clearer and easier
 to understand without explanation. In practice, the short form is
-often more convenient to write.
+often more convenient to type.
 
 Some options are "flags", and the use of the option is enough. For
 example, to request binary output, the option` --binary` is enough.
@@ -417,7 +418,7 @@ the option `--recipient-key` to specify what key to use for a
 recipient when encrypting needs to be provided the name of the file in
 which the key is stored. Such option values can be specified as the
 command line argument after the option, or appended to the option
-itself using `=foo` syntax. Thus, the following are exactly
+itself using `=foo` syntax. Thus, the following are
 equivalent:
 
 ```
@@ -442,13 +443,13 @@ sq key generate --help
 
 Use the help feature liberally to find out all the subcommands and
 options, and whether an option is a flag or takes a value, and what
-other arguments the command takes.
+other arguments the command accepts.
 
 
 
 # Managing one's own key
 
-This chapter concentrates on creating and managing a key for oneself.
+This chapter concentrates on creating and managing a private key for oneself.
 Please see the [glossary](#glossary) for definitions of terms. Some of
 the terminology `sq` uses is specific to cryptography in general, or
 to OpenPGP, and some is specific to `sq` itself.
@@ -458,7 +459,7 @@ to OpenPGP, and some is specific to `sq` itself.
 Your key is, in the context of public key cryptography, you. It's a
 digital artifact that represents you to everyone else. Nobody else has
 your key. You and your key are inseparable, and to everyone else, your
-key is you and you are your key.
+key is you, and you are your key.
 
 That is, of course, romantic balderdash. A key is a large random
 number. It has no free will, it has no agency, it can't think, it
@@ -471,7 +472,7 @@ inalienably linked to your key. When you want to prove a message comes
 from you, you encrypt it with your key.
 
 You can have as many keys as you want. You can have one for work,
-another for school, a third for you family and friends, and fourth one
+another for school, a third for your family and friends, and a fourth one
 for publishing poetry online. These keys may be linked or kept
 separate, as you prefer.
 
@@ -500,20 +501,20 @@ beyond the scope of this guide, the list below gives a summary.
   developed from time to time, to provide more strength. With elliptic
   curves, the choice of curve also specifies the size of the key.
 
-* **Checksum** algorithms are one-way mathematical functions, where if
+* **Hash** algorithms are one-way mathematical functions, where if
   you have a file you can compute a result from its contents easily,
   but if you have the result, it's really hard to get back the file. A
-  _cryptographic checksum_ is one where it's really hard to find any
-  file with the given checksum result. As with encryption algorithms,
-  checksums need to be made stronger as time goes by. OpenPGP
-  originally mandated use of the MD5 algorithm, but that is no longer
-  suitable for use. Currently SHA256 is the preferred one.
+  _cryptographic hash_ is one where it's really hard to find any
+  file with the given hash value. As with encryption algorithms,
+  hashes need to be made stronger as time goes by. OpenPGP
+  originally mandated the use of the MD5 algorithm, but that is no longer
+  suitable. Currently SHA256 is the preferred hash algorithm.
 
 Because key types and algorithms need to be improved over time, the
 OpenPGP standard allows replacing them in newer versions of the
-standard, without fundamentally changing the structure of the OpenPGP
+standard without fundamentally changing the structure of the OpenPGP
 protocol. Each version of OpenPGP supports multiple key types and
-algorithms, allowing for a managed migration towards stronger
+algorithms, which allows for a managed migration towards stronger
 security, and without losing access to older files and messages.
 
 
@@ -548,11 +549,11 @@ software.
 
 ## Why would keys expire automatically?
 
-A key, whether primary or subkey, can be set to expire at a given
+A key, whether a primary key or a subkey, can be set to expire at a given
 time. This is a precaution against you losing access to the primary
 key: if the key expires, others won't use it anymore. You can extend
 the expiration as often as you wish, although that requires getting
-your update certificate to everyone who needs to use it.
+your updated certificate to everyone who needs to use it.
 
 Another, more subtle benefit of expiring keys is that a short
 expiration time (of, say, one year) forces everyone else to refresh
@@ -583,24 +584,24 @@ certificate for a recipient, it uses the email address to do so. If
 the user id does not include the email address, the lookup fails.
 
 A key can have several user ids, which is handy for people who have
-several email addresses, at once or over time.
+several email addresses at once or over time.
 
 You can set an expiration time at the time of creating a key, if you
 want. See the `--expires` and `--expires-in` options.
 
 Generating a key with `sq` results in two files. The key is put in the
-file you name as the argument to the `--export` option (or you can
-specify the name yourself, with the `--rev-cert` option). A _key
+file you name as the argument to the `--export` option. A _key
 revocation certificate_ is written to a file with that name and `.rev`
-appended to it. The revocation certificate tells others that your key
-is longer usable. If, for example, you lose the file with the key, you
-can share the revocation certificate with others, and they (or their
-OpenPGP software) will know to not use that key anymore. We'll cover
-key revocation in more detail later.
+appended to it (or you can specify the name yourself, with the
+`--rev-cert` option). The revocation certificate tells others that
+your key is longer usable. If, for example, you lose the file with the
+key, you can share the revocation certificate with others, and they
+(or their OpenPGP software) will know to not use that key
+anymore. We'll cover key revocation in more detail later.
 
 You can choose the cryptographic algorithm, and whether the key should
 have subkeys for signing or encrypting messages. See the `--help`
-output for the option names.
+output for a list of options.
 
 
 ## Extracting a certificate from a key
@@ -616,17 +617,17 @@ for it). You need to re-extract the certificate every time you make a
 change to the key that would shared with others: user ids, expiration
 times, subkeys.
 
-Note that while one can extract a certificate from a key, the other
+Note that while you can extract a certificate from a key, the other
 direction is not possible.
 
 
-## Sharing one's certificate with others
+## Sharing your certificate with others
 
-A certificate contains no secrets and you can safely share it with
+A certificate contains no secrets, and you can safely share it with
 anyone: include it as an attachment in every email you send; put it on
 your web home page; put it on your profile on social media sites such
 as Facebook, Twitter, Mastodon, or GitHub; publish a photo of it on
-photo sharing site; print it on business cards. We'll cover more
+a photo sharing site; print it on business cards. We'll cover more
 options later in the chapter on managing keys in a community.
 
 A caveat: a certificate does contain all the user ids on your key, so
@@ -662,13 +663,13 @@ but for any kind of data, including files and cryptographic keys.
   the package fails to match its signature, the package won't be
   installed.
 
-  This is done to protect the system installing software from
-  maliciously modified software. It can also be used as a mechanism
-  for preventing software to be installed that isn't approved by the
+  This is done to protect the system from installing software that has been
+  modified maliciously. It can also be used as a mechanism
+  for preventing software from being installed that isn't approved by the
   distributor. Linux distributions don't do that, but big corporations
   seeking a dominant market position tend to like it.
 
-* When you create a new key, any user ids attached to it are signed by
+* When you add a User ID to a key, any user ids attached to it are signed by
   the key. This prevents other people from adding their email address
   to your key. If they could do that, they would get your email. While
   they can't read it, if it's encrypted, they can at least make sure
@@ -700,13 +701,13 @@ want to prove your copy is identical.
 To make a detached signature:
 
 ```
-sq sign --detached --signer-key=key.pgp --output=foo-sig.pgp foo.md
+sq sign --detached --signer-key=key.pgp --output=foo.sig foo.md
 ```
 
 Note the `--detached` option. The signature, but none of the original
-data, is written to `foo-sig.pgp`. The detached signature is small,
+data, is written to `foo.sig`. The detached signature is small,
 and its size does not depend on the size of the signed data. That's
-because the detached signature contains the _cryptographic checksum_
+because the detached signature only contains the _cryptographic hash__
 of the original data.
 
 ## Verifying a signature
@@ -725,7 +726,7 @@ Good signature from 84B292ABCE27285B
 ```
 
 The mysterious number `84B292ABCE27285B` is the key identifier of the
-key who made the signature. It should match the certificate you've
+key that made the signature. It should match the certificate you've
 provided.
 
 If the signature doesn't verify correctly, the error message is clear
@@ -745,10 +746,10 @@ be a little more verbose and give the names of both the data file and
 the signature file:
 
 ```
-$ sq verify --detached --signer-cert=cert.pgp foo-sig.pgp foo.md
+$ sq verify --detached --signer-cert=cert.pgp foo.sig foo.md
 ```
 
-## Trusting a certificate
+## Authenticating a certificate
 
 If you have a suspicious mind set, you may have spotted a glaring
 error in the above discussion of verifying digital signatures: you
@@ -763,7 +764,7 @@ If you're downloading software directly from its publisher's website,
 they probably provide the certificate on their website as well. If
 you're downloading things over HTTPS (instead of the unencrypted,
 unprotected, un-lamented plain HTTP), you can _probably_ trust the
-certificate. It's possible to spoof that, if not easy.
+certificate. It's possible to spoof that, but it's not easy.
 
 You may gain more trust in the certificate by verifying that the one
 you have is one that a lot of other people have, and have had a long
@@ -775,9 +776,9 @@ topic later in the chapter on managing keys at a community level.
 
 ## Encrypting a file
 
-Encrypting things is how you keep your private things private. There's
-a large, global debate about privacy and who deserves to keep what
-private and how to still catch bad busy who harm others. We shan't get
+Encrypting things is how you keep your private data private. There's
+a large, global debate about privacy, and who deserves to keep what
+private, and how to still catch bad guys who harm others. We shan't get
 into that here.
 
 To encrypt a file using `sq`:
@@ -790,7 +791,7 @@ This encrypts the file `foo.md`, using the certificate in `cert.pgp`,
 and writes the result into `bar.pgp`.
 
 Note that the encryption is done only for the explicitly specified
-recipients. If you want to read the encrypted output yourself later,
+recipients. If you want to read the encrypted output later,
 you need to add yourself as a recipient.
 
 The output file has a name different from the input file so that the
@@ -836,7 +837,7 @@ discuss various ways of distributing certificates.
 
 # Appendix: How to...? {.unnumbered}
 
-This appendix has task oriented guides for achieving specific goals.
+This appendix has task-oriented guides for achieving specific goals.
 Each how-to guide will explain every step, giving command line
 examples, but will not go into detail about what is happening or why.
 These how-to guides are aimed at people who need to achieve a specific
@@ -861,9 +862,9 @@ the command line tool from GnuPG that roughly corresponds to `sq`. It
 shows how to do specific tasks using either `gpg` or `sq`. It will
 
 GnuPG stores keys and certificates in the `~/.gnupg` directory, or
-directory named in the `GNUPGHOME` environment variable. They're not
+the directory named in the `GNUPGHOME` environment variable. They're not
 easily accessed directly as files, and are referred to via the user id
-or using a hexadecimal key identifier or key finger print. The set of
+or using a hexadecimal key identifier or key fingerprint. The set of
 keys and certificates in that directory is called a _keyring_. possibly
 be a comparison table, for easy review.