From 1f2a8a2bc31c4e6eca1c7f9421d79e9fef307075 Mon Sep 17 00:00:00 2001
From: Daniel McCarney <daniel@binaryparadox.net>
Date: Mon, 7 Aug 2023 20:15:34 -0400
Subject: [PATCH] trust_anchor/end_entity: rework deprecation notes.

In 0.101.2 we deprecated the `TlsServerTrustAnchors` and
`TlsClientTrustAnchors` types along with the
`EndEntity::verify_is_valid_tls_server_cert` and
`EndEntity::verify_is_valid_tls_client_cert` functions that used them.

However, only the `EndEntity` deprecations had a `note` pointing to the
preferred replacement, and the text was quite terse.

This commit adds notes to the trust anchor types that were missing
these, and updates the end entity verification deprecation notes to be
more user-friendly.
---
 src/end_entity.rs   | 16 ++++++++++++++--
 src/trust_anchor.rs | 16 ++++++++++++++--
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/src/end_entity.rs b/src/end_entity.rs
index d5b75475..a8619390 100644
--- a/src/end_entity.rs
+++ b/src/end_entity.rs
@@ -143,7 +143,13 @@ impl<'a> EndEntityCert<'a> {
     /// `time` is the time for which the validation is effective (usually the
     /// current time).
     #[allow(deprecated)]
-    #[deprecated(since = "0.101.2", note = "Use `verify_for_usage` instead")]
+    #[deprecated(
+        since = "0.101.2",
+        note = "The per-usage trust anchor representations and verification functions are deprecated in \
+        favor of the general-purpose `TrustAnchor` type and `EndEntity::verify_for_usage` function. \
+        The new `verify_for_usage` function expresses trust anchor and end entity purpose with the \
+        key usage argument."
+    )]
     pub fn verify_is_valid_tls_server_cert(
         &self,
         supported_sig_algs: &[&SignatureAlgorithm],
@@ -173,7 +179,13 @@ impl<'a> EndEntityCert<'a> {
     /// the time for which the validation is effective (usually the current
     /// time).
     #[allow(deprecated)]
-    #[deprecated(since = "0.101.2", note = "Use `verify_for_usage` instead")]
+    #[deprecated(
+        since = "0.101.2",
+        note = "The per-usage trust anchor representations and verification functions are deprecated in \
+        favor of the general-purpose `TrustAnchor` type and `EndEntity::verify_for_usage` function. \
+        The new `verify_for_usage` function expresses trust anchor and end entity purpose with the \
+        key usage argument."
+    )]
     pub fn verify_is_valid_tls_client_cert(
         &self,
         supported_sig_algs: &[&SignatureAlgorithm],
diff --git a/src/trust_anchor.rs b/src/trust_anchor.rs
index 32e4a5b3..21287646 100644
--- a/src/trust_anchor.rs
+++ b/src/trust_anchor.rs
@@ -24,12 +24,24 @@ pub struct TrustAnchor<'a> {
 }
 
 /// Trust anchors which may be used for authenticating servers.
-#[deprecated(since = "0.101.2")]
+#[deprecated(
+    since = "0.101.2",
+    note = "The per-usage trust anchor representations and verification functions are deprecated in \
+        favor of the general-purpose `TrustAnchor` type and `EndEntity::verify_for_usage` function. \
+        The new `verify_for_usage` function expresses trust anchor and end entity purpose with the \
+        key usage argument."
+)]
 #[derive(Debug)]
 pub struct TlsServerTrustAnchors<'a>(pub &'a [TrustAnchor<'a>]);
 
 /// Trust anchors which may be used for authenticating clients.
-#[deprecated(since = "0.101.2")]
+#[deprecated(
+    since = "0.101.2",
+    note = "The per-usage trust anchor representations and verification functions are deprecated in \
+        favor of the general-purpose `TrustAnchor` type and `EndEntity::verify_for_usage` function. \
+        The new `verify_for_usage` function expresses trust anchor and end entity purpose with the \
+        key usage argument."
+)]
 #[derive(Debug)]
 pub struct TlsClientTrustAnchors<'a>(pub &'a [TrustAnchor<'a>]);