openpgp: Provide guidance on how to use sequoia-openpgp.

  - Provide guidance for leaf crate and intermediate crates on how to
    use sequoia-openpgp, and how to handle the cryptographic backend
    features.

  - Fixes #987.

1 files changed, 86 insertions, 3 deletions

diff --git a/openpgp/README.md b/openpgp/README.md
index d850649a..b1a2447e 100644
--- a/openpgp/README.md
+++ b/openpgp/README.md
@@ -57,14 +57,18 @@ functionality.  You can tweak the features in your `Cargo.toml` file,
 like so:
 
 ```toml
-sequoia-openpgp = { version = "*", default-features = false, features = ["crypto-nettle", ...] }
+sequoia-openpgp = { version = "*", default-features = false, features = ["compression", ...] }
 ```
 
 By default, Sequoia is built using Nettle as cryptographic backend
-with all compression algorithms enabled.
+with all compression algorithms enabled.  Using the default features
+is only appropriate for leaf crates, see [this section].
+
+[this section]: #how-to-select-crypto-backends-in-crates
 
 Note that if you use `default-features = false`, you need to
-explicitly enable a crypto backend.
+explicitly enable a crypto backend, and also enable compression
+features.
 
 ## Crypto backends
 
@@ -109,6 +113,85 @@ operations require a constant amount of time.  This may leak secret
 keys in some settings.  The use of such backends requires explicit
 opt-in using the feature flag `allow-variable-time-crypto`.
 
+### How to select crypto backends in crates
+
+In Rust, [features are unified], and consequently features should be
+additive, i.e. it should be safe to enable any combination of
+features.  But, this does not hold for crypto backends, because
+exactly one cryptographic backend has to be selected in order to
+compile Sequoia.
+
+[features are unified]: https://doc.rust-lang.org/cargo/reference/features.html#feature-unification
+
+To accommodate this, we came up with the following rule: in any
+project using Sequoia, exactly one crate may select the cryptographic
+backend, and that crate is the leaf crate (i.e. the binary or cdylib
+crate).  Any non-leaf, library crate must refrain from selecting a
+crypto backend, including the default one, by disabling the default
+features.
+
+To recap, follow these rules depending on what kind of crate you are
+developing:
+
+#### Leaf crate
+
+The leaf crate should pick a default backend (you may defer to Sequoia
+to pick the default one), but should allow your downstream users to
+switch backends:
+
+```toml
+# Cargo.toml
+[dependencies]
+sequoia-openpgp = { version = "*", default-features = false }
+# If you need compression features, enable them here:
+# sequoia-openpgp = { version = "*", default-features = false, features = ["compression"] }
+
+[features]
+# Pick a crypto backend enabled by default (here we defer to Sequoia
+# to pick the default):
+default = ["sequoia-openpgp/default"]
+
+# .. but allow others to select a different backend, as well
+crypto-nettle = ["sequoia-openpgp/crypto-nettle"]
+crypto-openssl = ["sequoia-openpgp/crypto-openssl"]
+crypto-botan = ["sequoia-openpgp/crypto-botan"]
+crypto-botan2 = ["sequoia-openpgp/crypto-botan2"]
+crypto-rust = ["sequoia-openpgp/crypto-rust"]
+crypto-cng = ["sequoia-openpgp/crypto-cng"]
+
+# Experimental and variable-time cryptographic backend opt-ins
+allow-experimental-crypto = ["sequoia-openpgp/allow-experimental-crypto"]
+allow-variable-time-crypto = ["sequoia-openpgp/allow-variable-time-crypto"]
+```
+
+#### Intermediate crate
+
+Non-leaf crates must not select a cryptographic backend, and must
+disable the default features.  Additionally, to make `cargo test` work
+without having to select a crypto backend, and to enable `docs.rs` to
+build your documentation, do selectively enable crypto backends for
+those cases:
+
+```toml
+# Cargo.toml
+[dependencies]
+sequoia-openpgp = { version = "*", default-features = false }
+# If you need compression features, enable them here:
+# sequoia-openpgp = { version = "*", default-features = false, features = ["compression"] }
+
+# Enables a crypto backend for the tests:
+[target.'cfg(not(windows))'.dev-dependencies]
+sequoia-openpgp = { version = "1", default-features = false, features = ["crypto-nettle", "__implicit-crypto-backend-for-tests"]  }
+
+# Enables a crypto backend for the tests:
+[target.'cfg(windows)'.dev-dependencies]
+sequoia-openpgp = { version = "1", default-features = false, features = ["crypto-cng", "__implicit-crypto-backend-for-tests"] }
+
+# Enables a crypto backend for the docs.rs generation:
+[package.metadata.docs.rs]
+features = ["sequoia-openpgp/default"]
+```
+
 ## Compression algorithms
 
 Use the `compression` flag to enable support for all compression