RFC: change high-level API to make key usage explicit

src/end_entity.rs

@@ -15,10 +15,11 @@
 #[cfg(feature = "alloc")]
 use crate::subject_name::GeneralDnsNameRef;
 use crate::{
-    cert, signed_data, subject_name, verify_cert, CertRevocationList, Error, ExtendedKeyUsage,
-    NonTlsTrustAnchors, SignatureAlgorithm, SubjectNameRef, Time, TlsClientTrustAnchors,
-    TlsServerTrustAnchors, TrustAnchor,
+    cert, signed_data, subject_name, verify_cert, CertRevocationList, Error, KeyUsage,
+    SignatureAlgorithm, SubjectNameRef, Time, TrustAnchor,
 };
+#[allow(deprecated)]
+use crate::{TlsClientTrustAnchors, TlsServerTrustAnchors};
 
 /// An end-entity certificate.
 ///
@@ -81,7 +82,7 @@ impl<'a> EndEntityCert<'a> {
         trust_anchors: &[TrustAnchor],
         intermediate_certs: &[&[u8]],
         time: Time,
-        eku: ExtendedKeyUsage,
+        eku: KeyUsage,
         crls: &[&dyn CertRevocationList],
     ) -> Result<(), Error> {
         verify_cert::build_chain(
@@ -100,28 +101,33 @@ impl<'a> EndEntityCert<'a> {
     /// Verifies that the end-entity certificate is valid for use against the
     /// specified Extended Key Usage (EKU).
     ///
-    /// `supported_sig_algs` is the list of signature algorithms that are
-    /// trusted for use in certificate signatures; the end-entity certificate's
-    /// public key is not validated against this list. `trust_anchors` is the
-    /// list of root CAs to trust. `intermediate_certs` is the sequence of
-    /// intermediate certificates that the server sent in the TLS handshake.
-    /// `time` is the time for which the validation is effective (usually the
-    /// current time).
-    pub fn verify_is_valid_cert_with_eku(
+    /// * `supported_sig_algs` is the list of signature algorithms that are
+    ///   trusted for use in certificate signatures; the end-entity certificate's
+    ///   public key is not validated against this list.
+    /// * `trust_anchors` is the list of root CAs to trust
+    /// * `intermediate_certs` is the sequence of intermediate certificates that
+    ///   the server sent in the TLS handshake.
+    /// * `time` is the time for which the validation is effective (usually the
+    ///   current time).
+    /// * `usage` is the intended usage of the certificate, indicating what kind
+    ///   of usage we're verifying the certificate for.
+    /// * `crls` is the list of certificate revocation lists to check
+    ///   the certificate against.
+    pub fn verify_for_usage(
         &self,
         supported_sig_algs: &[&SignatureAlgorithm],
-        &NonTlsTrustAnchors(trust_anchors): &NonTlsTrustAnchors,
+        trust_anchors: &[TrustAnchor],
         intermediate_certs: &[&[u8]],
         time: Time,
-        eku: ExtendedKeyUsage,
+        usage: KeyUsage,
         crls: &[&dyn CertRevocationList],
     ) -> Result<(), Error> {
         self.verify_is_valid_cert(
             supported_sig_algs,
             trust_anchors,
             intermediate_certs,
             time,
-            eku,
+            usage,
             crls,
         )
     }
@@ -136,6 +142,8 @@ impl<'a> EndEntityCert<'a> {
     /// intermediate certificates that the server sent in the TLS handshake.
     /// `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")]
     pub fn verify_is_valid_tls_server_cert(
         &self,
         supported_sig_algs: &[&SignatureAlgorithm],
@@ -148,7 +156,7 @@ impl<'a> EndEntityCert<'a> {
             trust_anchors,
             intermediate_certs,
             time,
-            ExtendedKeyUsage::RequiredIfPresent(verify_cert::EKU_SERVER_AUTH),
+            KeyUsage::server_auth(),
             &[],
         )
     }
@@ -164,6 +172,8 @@ impl<'a> EndEntityCert<'a> {
     /// `cert` is the purported end-entity certificate of the client. `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")]
     pub fn verify_is_valid_tls_client_cert(
         &self,
         supported_sig_algs: &[&SignatureAlgorithm],
@@ -177,7 +187,7 @@ impl<'a> EndEntityCert<'a> {
             trust_anchors,
             intermediate_certs,
             time,
-            ExtendedKeyUsage::RequiredIfPresent(verify_cert::EKU_CLIENT_AUTH),
+            KeyUsage::client_auth(),
             crls,
         )
     }

src/lib.rs

@@ -58,6 +58,8 @@ mod crl;
 mod verify_cert;
 mod x509;
 
+#[allow(deprecated)]
+pub use trust_anchor::{TlsClientTrustAnchors, TlsServerTrustAnchors};
 pub use {
     cert::{Cert, EndEntityOrCa},
     crl::{BorrowedCertRevocationList, BorrowedRevokedCert, CertRevocationList, RevocationReason},
@@ -72,8 +74,8 @@ pub use {
         SubjectNameRef,
     },
     time::Time,
-    trust_anchor::{NonTlsTrustAnchors, TlsClientTrustAnchors, TlsServerTrustAnchors, TrustAnchor},
-    verify_cert::{ExtendedKeyUsage, KeyPurposeId},
+    trust_anchor::TrustAnchor,
+    verify_cert::KeyUsage,
 };
 
 #[cfg(feature = "alloc")]

src/trust_anchor.rs

@@ -26,15 +26,13 @@ pub struct TrustAnchor<'a> {
     pub name_constraints: Option<&'a [u8]>,
 }
 
-/// Trust anchors which may be used for authenticating certificates of any kind.
-#[derive(Debug)]
-pub struct NonTlsTrustAnchors<'a>(pub &'a [TrustAnchor<'a>]);
-
 /// Trust anchors which may be used for authenticating servers.
+#[deprecated(since = "0.101.2")]
 #[derive(Debug)]
 pub struct TlsServerTrustAnchors<'a>(pub &'a [TrustAnchor<'a>]);
 
 /// Trust anchors which may be used for authenticating clients.
+#[deprecated(since = "0.101.2")]
 #[derive(Debug)]
 pub struct TlsClientTrustAnchors<'a>(pub &'a [TrustAnchor<'a>]);