Merge branch 'small-fixes' into 'main'

Various small fixes to the guide

Closes #14, #15, #16, #17, and #18

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

2 files changed, 32 insertions, 11 deletions

diff --git a/README.md b/README.md
index 5b21e80..4e331cb 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # User guide for sq
 
-This is a sketch a user guide for sq, the command line tool from
+This is a sketch of a user guide for sq, the command line tool from
 Sequoia-PGP.
 
 `sq` is a command line tool for encrypting and authenticating files
diff --git a/sq-guide.md b/sq-guide.md
index ce7e342..d53e6db 100644
--- a/sq-guide.md
+++ b/sq-guide.md
@@ -79,7 +79,11 @@ $ ls -l decrypted.md
 
 ## What are Sequoia-PGP and `sq`?
 
-The Sequoia-PGP project works to make use of cryptography for privacy
+[Sequoia-PGP project]: https://sequoia-pgp.org/
+[Rust programming language]: https://www.rust-lang.org/
+[sequoia-openpgp]: https://gitlab.com/sequoia-pgp/sequoia/-/tree/main/openpgp
+
+The [Sequoia-PGP project][] works to make use of cryptography for privacy
 and authentication in communication more commonplace. The project
 produces and maintains an implementation of the OpenPGP standard
 that's easy and uncomplicated to use.
@@ -89,7 +93,10 @@ projects to verify the authenticity of software packages, and for
 encrypting and authenticating messages.
 
 `sq` is the command line tool provided by Sequoia-PGP. It's easy and
-uncomplicated to use.
+uncomplicated to use. Sequoia-PGP also provides a library for the
+[Rust programming language][], called [sequoia-openpgp][]. However,
+the library is only of interest to software developers, and this guide
+is aimed at users of the `sq` tool.
 
 ## Why use OpenPGP?
 
@@ -263,7 +270,7 @@ 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
 something using the private part, only the public part can decrypt
 this. Since anyone can decrypt, this operation is called a _digital
-signature_.
+signature_. (This is a very rough simplification.)
 
 This allows some very interesting things:
 
@@ -300,12 +307,13 @@ for links to explanations.
 
 ## Symmetric cryptography
 
-The alternative to public key cryptography is _symmetric
-cryptography_. (Public key cryptography is also known as _asymmetric
-cryptography_.) In symmetric cryptography there is no public and
-private parts of an encryption key. There is only one part, and the
-same key is used both for encrypting and for decrypting data. This is
-in many ways easier to understand, but is usually more awkward to use.
+The complement to public key cryptography is _secret key
+cryptography_, which is also known as _symmetric cryptography_.
+(Public key cryptography is also known as _asymmetric cryptography_.)
+In symmetric cryptography there is no public and private parts of an
+encryption key. There is only one part, and the same key is used both
+for encrypting and for decrypting data. This is in many ways easier to
+understand, but is usually more awkward to use.
 
 Symmetric cryptography is best suited when only one person needs to
 know the key, or when everyone who needs the key can get it in person.
@@ -338,6 +346,11 @@ The benefit is that symmetric cryptography tends to run faster and
 have shorter keys compared to public key cryptography, for similar
 levels of resistance against attacks.
 
+OpenPGP actually uses both symmetric and public key cryptography: one
+for the bulk of encryption, for speed, and the other for easier key
+management. The user does not actually need to care, but understanding
+is always good.
+
 
 ## Limitations of cryptography
 
@@ -507,6 +520,8 @@ your certificate. This setup has several benefits:
 
 * you can have separate subkeys for encryption, signing, or
   authentication
+* it's harder to leak or misuse the primary key, as it's only used
+  rarely
 * you can use a smaller key when less security is OK in exchange for
   faster use
 * you can have a separate subkey for each device you have, or put
@@ -527,12 +542,18 @@ 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.
 
+Another, more subtle benefit of expiring keys is that a short
+expiration time (of, say, one year) forces everyone else to refresh
+their copy of your certificate. This routine means they will also get
+a revocation update for the key, if there's ever a need for that.
+
 You can also set subkeys to expire. This has the same benefits as
 expiring the primary key.
 
 Changing expiration times can be a chore. There's a security benefit
 to it, but if it's inconvenient for you, you may want to consider not
-expiring keys, or only expire subkeys.
+expiring keys, or only expire subkeys. Despite the benefits, it's
+better to have a non-expiring key than not have a key at all.
 
 
 ## Generating a key