Clean up tls-related feature flags

This provides a clear and consistent interface for selecting TLS-related
features on both (xmpp and tokio-xmpp) crates. All feature checks have
been revamped. All working combinations have been tested (including a
connectivity test + --all-features docs build) using:

```
set -xeuo pipefail
features=(aws_lc_rs ring ktls,aws_lc_rs ktls,ring aws_lc_rs,ring aws_lc_rs,ring,ktls native-tls rustls-any-backend)
export RUSTFLAGS=" -D warnings"
cargo test --no-default-features
cargo test
for feature in ${features[@]}; do
  echo ">>> BUILDING with $feature" 2>&1
  # Running code or building examples cannot succeed with rustls-any-backend.
  features="starttls,$feature"
  if [ "$feature" != 'rustls-any-backend' ]; then
    if ! cargo test --no-default-features --features="$features"; then
      echo ">>> BUILD FAILED for tls feature set: $features" >&2
      exit 1
    fi
    set +e
    timeout -sINT -p -k 2 3 cargo run --no-default-features --features="$features" --example keep_connection -- test@hub.sotecware.net "$(pass xmpp/test@hub.sotecware.net)"
    status="$?"
    set -e
    if [ $status -ne 0 ]; then
      echo ">>> keep_connection did not shut down cleanly! (status: $status)" >&2
      exit 1
    fi
  else
    if ! cargo build --no-default-features --features="$feature"; then
      echo ">>> BUILD FAILED for tls feature set: $features" >&2
      exit 1
    fi
  fi
done
RUSTDOCFLAGS="--cfg docsrs" RUSTFLAGS="--cfg xmpprs_doc_build" cargo +nightly doc -Zrustdoc-map --all-features
```

xmpp/Cargo.toml

@@ -31,11 +31,20 @@ name = "hello_bot"
 required-features = ["avatars"]
 
 [features]
-default = ["avatars", "starttls-rust"]
-starttls-native = ["tokio-xmpp/starttls", "tokio-xmpp/tls-native", "reqwest/native-tls"]
-starttls-rust = ["tokio-xmpp/starttls", "tokio-xmpp/tls-rust", "reqwest/rustls-tls-no-provider", "tokio-xmpp/tls-rust-webpki-roots"]
-starttls-rust-aws_lc_rs = ["tokio-xmpp/tls-rust-aws_lc_rs", "starttls-rust"]
-starttls-rust-ring = ["tokio-xmpp/tls-rust-ring", "starttls-rust"]
+default = ["avatars", "aws_lc_rs", "starttls", "rustls-native-certs"]
+
+aws_lc_rs = ["rustls-any-backend", "tokio-xmpp/aws_lc_rs", "reqwest/rustls-tls-no-provider"]
+ring = ["rustls-any-backend", "tokio-xmpp/ring", "reqwest/rustls-tls-no-provider"]
+native-tls = ["tokio-xmpp/native-tls", "reqwest/native-tls"]
+ktls = ["rustls-any-backend", "tokio-xmpp/ktls", "reqwest/rustls-tls"]
+
+rustls-any-backend = ["tokio-xmpp/rustls-any-backend"]
+
+rustls-native-certs = ["tokio-xmpp/rustls-native-certs"]
+webpki-roots = ["tokio-xmpp/webpki-roots"]
+
+starttls = ["tokio-xmpp/starttls"]
+
 avatars = []
 escape-hatch = []
 syntax-highlighting = [ "tokio-xmpp/syntax-highlighting" ]

xmpp/ChangeLog

@@ -15,13 +15,14 @@ XXXX-YY-ZZ [ RELEASER <admin@localhost> ]
       - Agent::send_room_private_message now takes RoomPrivateMessageSettings (!487)
       - Event now exposes Option<MessageId> for incoming messages, and MessageId
         for incoming message corrections; type alias Id has been removed (!504)
-      - The `starttls-rust` feature flag does not automatically enable a
-        `rustls` crypto provider anymore. This is to avoid conflict between
-        two crypto providers and to avoid linking unnecessary code. The
-        `aws_lc_rs` crypto provider is still built by default, however,
-        applications which use `xmpp` without default features will have to
-        adapt their feature flags to explicitly enable the
-        `starttls-rust-aws_lc_rs` or `starttls-rust-ring` features. (!581)
+      - The TLS-related feature flags have been completely reworked to make
+        them easier to use. The `starttls-*` feature flags have been removed
+        in favour of more concise flag names identifying the TLS backends
+        directly (`aws_lc_rs`, `ring`, `native-tls`). The `starttls` feature
+        is now independent of the specific backend (but a backend still needs
+        to be enabled for compilation to succeed).
+
+        Please refer to the crate docs for details. (!581)
     * Added:
       - Agent::send_room_message takes RoomMessageSettings argument (!483)
       - Agent::send_raw_message takes RawMessageSettings for any message type (!487)

xmpp/examples/hello_bot.rs

@@ -4,10 +4,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-#[cfg(all(
-    feature = "starttls-rust",
-    any(feature = "starttls-rust-aws_lc_rs", feature = "starttls-rust-ring")
-))]
+#[cfg(feature = "rustls-any-backend")]
 use xmpp::tokio_xmpp::rustls;
 use xmpp::{
     jid::BareJid,
@@ -20,20 +17,22 @@ use tokio::signal::ctrl_c;
 use std::env::args;
 use std::str::FromStr;
 
+#[cfg(all(
+    feature = "rustls-any-backend",
+    not(any(feature = "aws_lc_rs", feature = "ring"))
+))]
+compile_error!("using rustls (e.g. via the ktls feature) needs an enabled rustls backend feature (either aws_lc_rs or ring).");
+
 #[tokio::main]
 async fn main() -> Result<(), Option<()>> {
     env_logger::init();
 
-    #[cfg(all(feature = "starttls-rust", feature = "starttls-rust-aws_lc_rs"))]
+    #[cfg(all(feature = "aws_lc_rs", not(feature = "ring")))]
     rustls::crypto::aws_lc_rs::default_provider()
         .install_default()
         .expect("failed to install rustls crypto provider");
 
-    #[cfg(all(
-        feature = "starttls-rust",
-        feature = "starttls-rust-ring",
-        not(feature = "starttls-rust-aws_lc_rs")
-    ))]
+    #[cfg(all(feature = "ring"))]
     rustls::crypto::ring::default_provider()
         .install_default()
         .expect("failed to install rustls crypto provider");

xmpp/src/builder.rs

@@ -4,7 +4,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-#[cfg(any(feature = "starttls-rust", feature = "starttls-native"))]
+#[cfg(feature = "starttls")]
 use crate::tokio_xmpp::connect::{DnsConfig, StartTlsServerConnector};
 use core::str::FromStr;
 
@@ -52,7 +52,7 @@ pub struct ClientBuilder<'a, C: ServerConnector> {
     timeouts: Timeouts,
 }
 
-#[cfg(any(feature = "starttls-rust", feature = "starttls-native"))]
+#[cfg(feature = "starttls")]
 impl ClientBuilder<'_, StartTlsServerConnector> {
     pub fn new<'a>(jid: BareJid, password: &'a str) -> ClientBuilder<'a, StartTlsServerConnector> {
         Self::new_with_connector(

xmpp/src/lib.rs

@@ -3,6 +3,46 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
+//! # Cargo features
+//!
+//! ## TLS backends
+//!
+//! - `aws_lc_rs` (default) enables rustls with the `aws_lc_rs` backend.
+//! - `ring` enables rustls with the `ring` backend`.
+//! - `rustls-any-backend` enables rustls, but without enabling a backend. It
+//!   is the application's responsibility to ensure that a backend is enabled
+//!   and installed.
+//! - `ktls` enables the use of ktls.
+//!   **Important:** Currently, connections will fail if the `tls` kernel
+//!   module is not available. There is no fallback to non-ktls connections!
+//! - `native-tls` enables the system-native TLS library (commonly
+//!   libssl/OpenSSL).
+//!
+//! **Note:** It is not allowed to mix rustls-based TLS backends with
+//! `tls-native`. Attempting to do so will result in a compilation error.
+//!
+//! **Note:** The `ktls` feature requires at least one `rustls` backend to be
+//! enabled (`aws_lc_rs` or `ring`).
+//!
+//! **Note:** When enabling not exactly one rustls backend, it is the
+//! application's responsibility to make sure that a default crypto provider is
+//! installed in `rustls`. Otherwise, all TLS connections will fail.
+//!
+//! ## Certificate validation
+//!
+//! When using `native-tls`, the system's native certificate store is used.
+//! Otherwise, you need to pick one of the following to ensure that TLS
+//! connections will succeed:
+//!
+//! - `rustls-native-certs` (default): Uses [rustls-native-certs](https://crates.io/crates/rustls-native-certs).
+//! - `webpki-roots`: Uses [webpki-roots](https://crates.io/crates/webpki-roots).
+//!
+//! ## Other features
+//!
+//! - `starttls` (default): Enables support for `<starttls/>`. Required as per
+//!   RFC 6120.
+//! - `avatars` (default): Enables support for avatars.
+//! - `serde`: Enable the `serde` feature in `tokio-xmpp`.
 
 #![deny(bare_trait_objects)]
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]