From 51ac3b5bf776b6724bb8f229145057e34dd6aad4 Mon Sep 17 00:00:00 2001
From: Rushil Mehra <rmehra@cloudflare.com>
Date: Fri, 9 Aug 2024 04:16:07 -0700
Subject: [PATCH 1/6] Expose mTLS related APIs

---
 boring/src/ssl/mod.rs  | 57 ++++++++++++++++++++++++++++++++++++++++++
 boring/src/x509/mod.rs | 24 ++++++++++++++++++
 2 files changed, 81 insertions(+)

diff --git a/boring/src/ssl/mod.rs b/boring/src/ssl/mod.rs
index be26aa94..83b616a6 100644
--- a/boring/src/ssl/mod.rs
+++ b/boring/src/ssl/mod.rs
@@ -2918,6 +2918,25 @@ impl SslRef {
         unsafe { ffi::SSL_set_verify(self.as_ptr(), mode.bits() as c_int, None) }
     }
 
+    /// Sets the certificate verification depth.
+    ///
+    /// If the peer's certificate chain is longer than this value, verification will fail.
+    ///
+    /// This corresponds to [`SSL_set_verify_depth`].
+    ///
+    /// [`SSL_set_verify_depth`]: https://docs.openssl.org/1.1.1/man3/SSL_CTX_set_verify/
+    pub fn set_verify_depth(&mut self, depth: u32) {
+        #[cfg(feature = "rpk")]
+        assert!(
+            !self.ssl_context().is_rpk(),
+            "This API is not supported for RPK"
+        );
+
+        unsafe {
+            ffi::SSL_set_verify_depth(self.as_ptr(), depth as c_int);
+        }
+    }
+
     /// Returns the verify mode that was set using `set_verify`.
     ///
     /// This corresponds to [`SSL_get_verify_mode`].
@@ -2975,6 +2994,25 @@ impl SslRef {
         }
     }
 
+    /// Sets a custom certificate store for verifying peer certificates.
+    ///
+    /// This corresponds to [`SSL_CTX_set0_verify_cert_store`].
+    ///
+    /// [`SSL_set0_verify_cert_store`]: https://docs.openssl.org/1.0.2/man3/SSL_CTX_set1_verify_cert_store/
+    pub fn set_verify_cert_store(&mut self, cert_store: X509Store) -> Result<(), ErrorStack> {
+        #[cfg(feature = "rpk")]
+        assert!(
+            !self.ssl_context().is_rpk(),
+            "This API is not supported for RPK"
+        );
+
+        unsafe {
+            cvt(ffi::SSL_set0_verify_cert_store(self.as_ptr(), cert_store.as_ptr()) as c_int)?;
+            mem::forget(cert_store);
+            Ok(())
+        }
+    }
+
     /// Like [`SslContextBuilder::set_custom_verify_callback`].
     ///
     /// This corresponds to [`SSL_set_custom_verify`].
@@ -3800,6 +3838,25 @@ impl SslRef {
         Ok(())
     }
 
+    /// Sets the list of CA names sent to the client.
+    ///
+    /// The CA certificates must still be added to the trust root - they are not automatically set
+    /// as trusted by this method.
+    ///
+    /// This corresponds to [`SSL_set_client_CA_list`].
+    ///
+    /// [`SSL_set_client_CA_list`]: https://docs.openssl.org/1.1.1/man3/SSL_CTX_set0_CA_list/
+    pub fn set_client_ca_list(&mut self, list: Stack<X509Name>) {
+        #[cfg(feature = "rpk")]
+        assert!(
+            !self.ssl_context().is_rpk(),
+            "This API is not supported for RPK"
+        );
+
+        unsafe { ffi::SSL_set_client_CA_list(self.as_ptr(), list.as_ptr()) }
+        mem::forget(list);
+    }
+
     /// Sets the private key.
     ///
     /// This corresponds to [`SSL_use_PrivateKey`].
diff --git a/boring/src/x509/mod.rs b/boring/src/x509/mod.rs
index 30a4b2b8..1ef04454 100644
--- a/boring/src/x509/mod.rs
+++ b/boring/src/x509/mod.rs
@@ -474,6 +474,30 @@ impl X509Ref {
         }
     }
 
+    /// Returns this certificate's subject key id.
+    ///
+    /// This corresponds to [`X509_get0_subject_key_id`].
+    ///
+    /// [`X509_get0_subject_key_id`]: https://docs.openssl.org/1.1.1/man3/X509_get_extension_flags/
+    pub fn subject_key_id(&self) -> &Asn1StringRef {
+        unsafe {
+            let name = ffi::X509_get0_subject_key_id(self.as_ptr());
+            Asn1StringRef::from_ptr(name as _)
+        }
+    }
+
+    /// Returns this certificate's authority key id.
+    ///
+    /// This corresponds to [`X509_get0_authority_key_id`].
+    ///
+    /// [`X509_get0_authority_key_id`]: https://docs.openssl.org/1.1.1/man3/X509_get_extension_flags/
+    pub fn authority_key_id(&self) -> &Asn1StringRef {
+        unsafe {
+            let name = ffi::X509_get0_authority_key_id(self.as_ptr());
+            Asn1StringRef::from_ptr(name as _)
+        }
+    }
+
     pub fn public_key(&self) -> Result<PKey<Public>, ErrorStack> {
         unsafe {
             let pkey = cvt_p(ffi::X509_get_pubkey(self.as_ptr()))?;

From ffca69df330f17d0400fd4fd13b66187498924cd Mon Sep 17 00:00:00 2001
From: Rushil Mehra <rmehra@cloudflare.com>
Date: Tue, 13 Aug 2024 17:24:42 -0700
Subject: [PATCH 2/6] Introduce ForeignTypeExt and ForeignTypeRefExt

`ForeignTypeExt` and `ForeignTypeRefExt` are inspired by
https://github.com/sfackler/rust-openssl/pull/1345, which make dealing
with FFI safer and more ergonomic. The new APIs (e.g.
from_const_ptr_opt`) also allow for gracefully handling instances where
the initial API call results in `NULL`. Instead of crashing the program,
`None` will be returned.
---
 boring/src/util.rs     | 31 ++++++++++++++++++++++++--
 boring/src/x509/mod.rs | 50 ++++++++++++++++--------------------------
 2 files changed, 48 insertions(+), 33 deletions(-)

diff --git a/boring/src/util.rs b/boring/src/util.rs
index 21591d2f..bb6373c1 100644
--- a/boring/src/util.rs
+++ b/boring/src/util.rs
@@ -1,10 +1,10 @@
+use crate::error::ErrorStack;
+use foreign_types::{ForeignType, ForeignTypeRef};
 use libc::{c_char, c_int, c_void};
 use std::any::Any;
 use std::panic::{self, AssertUnwindSafe};
 use std::slice;
 
-use crate::error::ErrorStack;
-
 /// Wraps a user-supplied callback and a slot for panics thrown inside the callback (while FFI
 /// frames are on the stack).
 ///
@@ -65,3 +65,30 @@ where
         }
     }
 }
+
+#[allow(dead_code)]
+pub trait ForeignTypeExt: ForeignType {
+    unsafe fn from_ptr_opt(ptr: *mut Self::CType) -> Option<Self> {
+        if ptr.is_null() {
+            None
+        } else {
+            Some(Self::from_ptr(ptr))
+        }
+    }
+}
+impl<FT: ForeignType> ForeignTypeExt for FT {}
+
+pub trait ForeignTypeRefExt: ForeignTypeRef {
+    unsafe fn from_const_ptr<'a>(ptr: *const Self::CType) -> &'a Self {
+        Self::from_ptr(ptr as *mut Self::CType)
+    }
+
+    unsafe fn from_const_ptr_opt<'a>(ptr: *const Self::CType) -> Option<&'a Self> {
+        if ptr.is_null() {
+            None
+        } else {
+            Some(Self::from_const_ptr(ptr as *mut Self::CType))
+        }
+    }
+}
+impl<FT: ForeignTypeRef> ForeignTypeRefExt for FT {}
diff --git a/boring/src/x509/mod.rs b/boring/src/x509/mod.rs
index 1ef04454..eb55c305 100644
--- a/boring/src/x509/mod.rs
+++ b/boring/src/x509/mod.rs
@@ -36,6 +36,7 @@ use crate::pkey::{HasPrivate, HasPublic, PKey, PKeyRef, Public};
 use crate::ssl::SslRef;
 use crate::stack::{Stack, StackRef, Stackable};
 use crate::string::OpensslString;
+use crate::util::ForeignTypeRefExt;
 use crate::x509::verify::X509VerifyParamRef;
 use crate::{cvt, cvt_n, cvt_p};
 
@@ -407,8 +408,7 @@ impl X509Ref {
     pub fn subject_name(&self) -> &X509NameRef {
         unsafe {
             let name = ffi::X509_get_subject_name(self.as_ptr());
-            assert!(!name.is_null());
-            X509NameRef::from_ptr(name)
+            X509NameRef::from_const_ptr_opt(name).expect("issuer name must not be null")
         }
     }
 
@@ -419,19 +419,6 @@ impl X509Ref {
         unsafe { ffi::X509_subject_name_hash(self.as_ptr()) as u32 }
     }
 
-    /// Returns this certificate's issuer name.
-    ///
-    /// This corresponds to [`X509_get_issuer_name`].
-    ///
-    /// [`X509_get_issuer_name`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_get_subject_name.html
-    pub fn issuer_name(&self) -> &X509NameRef {
-        unsafe {
-            let name = ffi::X509_get_issuer_name(self.as_ptr());
-            assert!(!name.is_null());
-            X509NameRef::from_ptr(name)
-        }
-    }
-
     /// Returns this certificate's subject alternative name entries, if they exist.
     ///
     /// This corresponds to [`X509_get_ext_d2i`] called with `NID_subject_alt_name`.
@@ -453,6 +440,15 @@ impl X509Ref {
         }
     }
 
+    /// Returns this certificate's issuer name.
+    #[corresponds(X509_get_issuer_name)]
+    pub fn issuer_name(&self) -> &X509NameRef {
+        unsafe {
+            let name = ffi::X509_get_issuer_name(self.as_ptr());
+            X509NameRef::from_const_ptr_opt(name).expect("issuer name must not be null")
+        }
+    }
+
     /// Returns this certificate's issuer alternative name entries, if they exist.
     ///
     /// This corresponds to [`X509_get_ext_d2i`] called with `NID_issuer_alt_name`.
@@ -474,27 +470,19 @@ impl X509Ref {
         }
     }
 
-    /// Returns this certificate's subject key id.
-    ///
-    /// This corresponds to [`X509_get0_subject_key_id`].
-    ///
-    /// [`X509_get0_subject_key_id`]: https://docs.openssl.org/1.1.1/man3/X509_get_extension_flags/
-    pub fn subject_key_id(&self) -> &Asn1StringRef {
+    /// Returns this certificate's subject key id, if it exists.
+    pub fn subject_key_id(&self) -> Option<&Asn1StringRef> {
         unsafe {
-            let name = ffi::X509_get0_subject_key_id(self.as_ptr());
-            Asn1StringRef::from_ptr(name as _)
+            let data = ffi::X509_get0_subject_key_id(self.as_ptr());
+            Asn1StringRef::from_const_ptr_opt(data)
         }
     }
 
-    /// Returns this certificate's authority key id.
-    ///
-    /// This corresponds to [`X509_get0_authority_key_id`].
-    ///
-    /// [`X509_get0_authority_key_id`]: https://docs.openssl.org/1.1.1/man3/X509_get_extension_flags/
-    pub fn authority_key_id(&self) -> &Asn1StringRef {
+    /// Returns this certificate's authority key id, if it exists.
+    pub fn authority_key_id(&self) -> Option<&Asn1StringRef> {
         unsafe {
-            let name = ffi::X509_get0_authority_key_id(self.as_ptr());
-            Asn1StringRef::from_ptr(name as _)
+            let data = ffi::X509_get0_authority_key_id(self.as_ptr());
+            Asn1StringRef::from_const_ptr_opt(data)
         }
     }
 

From 31dab8c14e2275d8767ddd3bf30b328eb471277f Mon Sep 17 00:00:00 2001
From: Rushil Mehra <rmehra@cloudflare.com>
Date: Mon, 12 Aug 2024 21:21:29 -0700
Subject: [PATCH 3/6] Introduce `corresponds` macro from openssl-macros

Our rustdocs are miserably broken. We manually link to openssl docs in
most binding definitions, and openssl keeps changing their documentation
URL, so in order to fix everything I'd have to touch every single
binding definition in every single file. Instead, we should use the
`corresponds` macro from the openssl-macros crate which nicely adds a
link to the openssl documentation on our behalf. If the openssl
documentation url ever changes again in the future, a simple dependency
bump should solve the issue.
---
 Cargo.toml             |   1 +
 boring/Cargo.toml      |   1 +
 boring/src/ssl/mod.rs  | 793 +++++++++--------------------------------
 boring/src/x509/mod.rs |  82 ++---
 4 files changed, 204 insertions(+), 673 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 3836084b..e8bf6e38 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -40,5 +40,6 @@ http = "0.2"
 hyper = { version = "0.14", default-features = false }
 linked_hash_set = "0.1"
 once_cell = "1.0"
+openssl-macros = "0.1.1"
 tower = "0.4"
 tower-layer = "0.3"
diff --git a/boring/Cargo.toml b/boring/Cargo.toml
index 0a576ab4..a558eefa 100644
--- a/boring/Cargo.toml
+++ b/boring/Cargo.toml
@@ -69,6 +69,7 @@ kx-client-nist-required = ["kx-safe-default"]
 bitflags = { workspace = true }
 foreign-types = { workspace = true }
 once_cell = { workspace = true }
+openssl-macros = { workspace = true }
 libc = { workspace = true }
 boring-sys = { workspace = true }
 
diff --git a/boring/src/ssl/mod.rs b/boring/src/ssl/mod.rs
index 83b616a6..12ffedf5 100644
--- a/boring/src/ssl/mod.rs
+++ b/boring/src/ssl/mod.rs
@@ -57,10 +57,10 @@
 //!     }
 //! }
 //! ```
-use crate::ffi;
 use foreign_types::{ForeignType, ForeignTypeRef, Opaque};
 use libc::{c_char, c_int, c_long, c_uchar, c_uint, c_void};
 use once_cell::sync::Lazy;
+use openssl_macros::corresponds;
 use std::any::TypeId;
 use std::collections::HashMap;
 use std::convert::TryInto;
@@ -82,6 +82,7 @@ use crate::dh::DhRef;
 use crate::ec::EcKeyRef;
 use crate::error::ErrorStack;
 use crate::ex_data::Index;
+use crate::ffi;
 use crate::nid::Nid;
 use crate::pkey::{HasPrivate, PKeyRef, Params, Private};
 use crate::srtp::{SrtpProtectionProfile, SrtpProtectionProfileRef};
@@ -243,9 +244,7 @@ pub struct SslMethod(*const ffi::SSL_METHOD);
 
 impl SslMethod {
     /// Support all versions of the TLS protocol.
-    ///
-    /// This corresponds to `TLS_method` on OpenSSL 1.1.0 and `SSLv23_method`
-    /// on OpenSSL 1.0.x.
+    #[corresponds(TLS_method)]
     pub fn tls() -> SslMethod {
         unsafe { SslMethod(TLS_method()) }
     }
@@ -257,25 +256,19 @@ impl SslMethod {
     }
 
     /// Support all versions of the DTLS protocol.
-    ///
-    /// This corresponds to `DTLS_method` on OpenSSL 1.1.0 and `DTLSv1_method`
-    /// on OpenSSL 1.0.x.
+    #[corresponds(DTLS_method)]
     pub fn dtls() -> SslMethod {
         unsafe { SslMethod(DTLS_method()) }
     }
 
     /// Support all versions of the TLS protocol, explicitly as a client.
-    ///
-    /// This corresponds to `TLS_client_method` on OpenSSL 1.1.0 and
-    /// `SSLv23_client_method` on OpenSSL 1.0.x.
+    #[corresponds(TLS_client_method)]
     pub fn tls_client() -> SslMethod {
         unsafe { SslMethod(TLS_client_method()) }
     }
 
     /// Support all versions of the TLS protocol, explicitly as a server.
-    ///
-    /// This corresponds to `TLS_server_method` on OpenSSL 1.1.0 and
-    /// `SSLv23_server_method` on OpenSSL 1.0.x.
+    #[corresponds(TLS_server_method)]
     pub fn tls_server() -> SslMethod {
         unsafe { SslMethod(TLS_server_method()) }
     }
@@ -285,6 +278,7 @@ impl SslMethod {
     /// # Safety
     ///
     /// The caller must ensure the pointer is valid.
+    #[corresponds(TLS_server_method)]
     pub unsafe fn from_ptr(ptr: *const ffi::SSL_METHOD) -> SslMethod {
         SslMethod(ptr)
     }
@@ -737,6 +731,7 @@ impl SslCurve {
     /// This corresponds to [`SSL_get_curve_name`]
     ///
     /// [`SSL_get_curve_name`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_get_curve_name
+    #[corresponds(SSL_get_curve_name)]
     pub fn name(&self) -> Option<&'static str> {
         unsafe {
             let ptr = ffi::SSL_get_curve_name(self.0 as u16);
@@ -858,10 +853,7 @@ pub struct SslContextBuilder {
 #[cfg(feature = "rpk")]
 impl SslContextBuilder {
     /// Creates a new `SslContextBuilder` to be used with Raw Public Key.
-    ///
-    /// This corresponds to [`SSL_CTX_new`].
-    ///
-    /// [`SSL_CTX_new`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_new.html
+    #[corresponds(SSL_CTX_new)]
     pub fn new_rpk() -> Result<SslContextBuilder, ErrorStack> {
         unsafe {
             init();
@@ -901,10 +893,7 @@ impl SslContextBuilder {
 
 impl SslContextBuilder {
     /// Creates a new `SslContextBuilder`.
-    ///
-    /// This corresponds to [`SSL_CTX_new`].
-    ///
-    /// [`SSL_CTX_new`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_new.html
+    #[corresponds(SSL_CTX_new)]
     pub fn new(method: SslMethod) -> Result<SslContextBuilder, ErrorStack> {
         unsafe {
             init();
@@ -955,10 +944,7 @@ impl SslContextBuilder {
     }
 
     /// Configures the certificate verification method for new connections.
-    ///
-    /// This corresponds to [`SSL_CTX_set_verify`].
-    ///
-    /// [`SSL_CTX_set_verify`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_verify.html
+    #[corresponds(SSL_CTX_set_verify)]
     pub fn set_verify(&mut self, mode: SslVerifyMode) {
         #[cfg(feature = "rpk")]
         assert!(!self.is_rpk, "This API is not supported for RPK");
@@ -981,13 +967,10 @@ impl SslContextBuilder {
     /// Those callbacks can inspect the peer-sent chain, call [`X509StoreContextRef::verify_cert`]
     /// and inspect the result, or perform other operations more straightforwardly.
     ///
-    /// This corresponds to [`SSL_CTX_set_verify`].
-    ///
     /// # Panics
     ///
     /// This method panics if this `Ssl` is associated with a RPK context.
-    ///
-    /// [`SSL_CTX_set_verify`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_verify.html
+    #[corresponds(SSL_CTX_set_verify)]
     pub fn set_verify_callback<F>(&mut self, mode: SslVerifyMode, callback: F)
     where
         F: Fn(bool, &mut X509StoreContextRef) -> bool + 'static + Sync + Send,
@@ -1015,6 +998,7 @@ impl SslContextBuilder {
     /// # Panics
     ///
     /// This method panics if this `Ssl` is associated with a RPK context.
+    #[corresponds(SSL_CTX_set_custom_verify)]
     pub fn set_custom_verify_callback<F>(&mut self, mode: SslVerifyMode, callback: F)
     where
         F: Fn(&mut SslRef) -> Result<(), SslVerifyError> + 'static + Sync + Send,
@@ -1040,10 +1024,8 @@ impl SslContextBuilder {
     /// Obtain the server name with the `servername` method and then set the corresponding context
     /// with `set_ssl_context`
     ///
-    /// This corresponds to [`SSL_CTX_set_tlsext_servername_callback`].
-    ///
-    /// [`SSL_CTX_set_tlsext_servername_callback`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_tlsext_servername_callback.html
     // FIXME tlsext prefix?
+    #[corresponds(SSL_CTX_set_tlsext_servername_callback)]
     pub fn set_servername_callback<F>(&mut self, callback: F)
     where
         F: Fn(&mut SslRef, &mut SslAlert) -> Result<(), SniError> + 'static + Sync + Send,
@@ -1069,10 +1051,7 @@ impl SslContextBuilder {
     /// Sets the certificate verification depth.
     ///
     /// If the peer's certificate chain is longer than this value, verification will fail.
-    ///
-    /// This corresponds to [`SSL_CTX_set_verify_depth`].
-    ///
-    /// [`SSL_CTX_set_verify_depth`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_verify_depth.html
+    #[corresponds(SSL_CTX_set_verify_depth)]
     pub fn set_verify_depth(&mut self, depth: u32) {
         #[cfg(feature = "rpk")]
         assert!(!self.is_rpk, "This API is not supported for RPK");
@@ -1083,10 +1062,7 @@ impl SslContextBuilder {
     }
 
     /// Sets a custom certificate store for verifying peer certificates.
-    ///
-    /// This corresponds to [`SSL_CTX_set0_verify_cert_store`].
-    ///
-    /// [`SSL_CTX_set0_verify_cert_store`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set0_verify_cert_store.html
+    #[corresponds(SSL_CTX_set0_verify_cert_store)]
     pub fn set_verify_cert_store(&mut self, cert_store: X509Store) -> Result<(), ErrorStack> {
         #[cfg(feature = "rpk")]
         assert!(!self.is_rpk, "This API is not supported for RPK");
@@ -1101,10 +1077,7 @@ impl SslContextBuilder {
     }
 
     /// Replaces the context's certificate store.
-    ///
-    /// This corresponds to [`SSL_CTX_set_cert_store`].
-    ///
-    /// [`SSL_CTX_set_cert_store`]: https://www.openssl.org/docs/man1.0.2/man3/SSL_CTX_set_cert_store.html
+    #[corresponds(SSL_CTX_set_cert_store)]
     pub fn set_cert_store(&mut self, cert_store: X509Store) {
         #[cfg(feature = "rpk")]
         assert!(!self.is_rpk, "This API is not supported for RPK");
@@ -1121,10 +1094,7 @@ impl SslContextBuilder {
     /// instead of a single record at a time.
     ///
     /// It has no effect when used with DTLS.
-    ///
-    /// This corresponds to [`SSL_CTX_set_read_ahead`].
-    ///
-    /// [`SSL_CTX_set_read_ahead`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_read_ahead.html
+    #[corresponds(SSL_CTX_set_read_ahead)]
     pub fn set_read_ahead(&mut self, read_ahead: bool) {
         unsafe {
             ffi::SSL_CTX_set_read_ahead(self.as_ptr(), read_ahead as c_int);
@@ -1132,27 +1102,20 @@ impl SslContextBuilder {
     }
 
     /// Sets the mode used by the context, returning the new bit-mask after adding mode.
-    ///
-    /// This corresponds to [`SSL_CTX_set_mode`].
-    ///
-    /// [`SSL_CTX_set_mode`]: https://www.openssl.org/docs/man1.0.2/man3/SSL_CTX_set_mode.html
+    #[corresponds(SSL_CTX_set_mode)]
     pub fn set_mode(&mut self, mode: SslMode) -> SslMode {
         let bits = unsafe { ffi::SSL_CTX_set_mode(self.as_ptr(), mode.bits()) };
         SslMode::from_bits_retain(bits)
     }
 
     /// Sets the parameters to be used during ephemeral Diffie-Hellman key exchange.
-    ///
-    /// This corresponds to [`SSL_CTX_set_tmp_dh`].
-    ///
-    /// [`SSL_CTX_set_tmp_dh`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_tmp_dh.html
+    #[corresponds(SSL_CTX_set_tmp_dh)]
     pub fn set_tmp_dh(&mut self, dh: &DhRef<Params>) -> Result<(), ErrorStack> {
         unsafe { cvt(ffi::SSL_CTX_set_tmp_dh(self.as_ptr(), dh.as_ptr()) as c_int).map(|_| ()) }
     }
 
     /// Sets the parameters to be used during ephemeral elliptic curve Diffie-Hellman key exchange.
-    ///
-    /// This corresponds to `SSL_CTX_set_tmp_ecdh`.
+    #[corresponds(SSL_CTX_set_tmp_ecdh)]
     pub fn set_tmp_ecdh(&mut self, key: &EcKeyRef<Params>) -> Result<(), ErrorStack> {
         unsafe { cvt(ffi::SSL_CTX_set_tmp_ecdh(self.as_ptr(), key.as_ptr()) as c_int).map(|_| ()) }
     }
@@ -1161,10 +1124,7 @@ impl SslContextBuilder {
     ///
     /// These locations are read from the `SSL_CERT_FILE` and `SSL_CERT_DIR` environment variables
     /// if present, or defaults specified at OpenSSL build time otherwise.
-    ///
-    /// This corresponds to [`SSL_CTX_set_default_verify_paths`].
-    ///
-    /// [`SSL_CTX_set_default_verify_paths`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_default_verify_paths.html
+    #[corresponds(SSL_CTX_set_default_verify_paths)]
     pub fn set_default_verify_paths(&mut self) -> Result<(), ErrorStack> {
         #[cfg(feature = "rpk")]
         assert!(!self.is_rpk, "This API is not supported for RPK");
@@ -1175,10 +1135,7 @@ impl SslContextBuilder {
     /// Loads trusted root certificates from a file.
     ///
     /// The file should contain a sequence of PEM-formatted CA certificates.
-    ///
-    /// This corresponds to [`SSL_CTX_load_verify_locations`].
-    ///
-    /// [`SSL_CTX_load_verify_locations`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_load_verify_locations.html
+    #[corresponds(SSL_CTX_load_verify_locations)]
     pub fn set_ca_file<P: AsRef<Path>>(&mut self, file: P) -> Result<(), ErrorStack> {
         #[cfg(feature = "rpk")]
         assert!(!self.is_rpk, "This API is not supported for RPK");
@@ -1198,10 +1155,7 @@ impl SslContextBuilder {
     ///
     /// The CA certificates must still be added to the trust root - they are not automatically set
     /// as trusted by this method.
-    ///
-    /// This corresponds to [`SSL_CTX_set_client_CA_list`].
-    ///
-    /// [`SSL_CTX_set_client_CA_list`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_client_CA_list.html
+    #[corresponds(SSL_CTX_set_client_CA_list)]
     pub fn set_client_ca_list(&mut self, list: Stack<X509Name>) {
         #[cfg(feature = "rpk")]
         assert!(!self.is_rpk, "This API is not supported for RPK");
@@ -1214,10 +1168,7 @@ impl SslContextBuilder {
 
     /// Add the provided CA certificate to the list sent by the server to the client when
     /// requesting client-side TLS authentication.
-    ///
-    /// This corresponds to [`SSL_CTX_add_client_CA`].
-    ///
-    /// [`SSL_CTX_add_client_CA`]: https://www.openssl.org/docs/man1.0.2/man3/SSL_CTX_set_client_CA_list.html
+    #[corresponds(SSL_CTX_add_client_CA)]
     pub fn add_client_ca(&mut self, cacert: &X509Ref) -> Result<(), ErrorStack> {
         #[cfg(feature = "rpk")]
         assert!(!self.is_rpk, "This API is not supported for RPK");
@@ -1233,10 +1184,7 @@ impl SslContextBuilder {
     ///
     /// This value should be set when using client certificates, or each request will fail its
     /// handshake and need to be restarted.
-    ///
-    /// This corresponds to [`SSL_CTX_set_session_id_context`].
-    ///
-    /// [`SSL_CTX_set_session_id_context`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_session_id_context.html
+    #[corresponds(SSL_CTX_set_session_id_context)]
     pub fn set_session_id_context(&mut self, sid_ctx: &[u8]) -> Result<(), ErrorStack> {
         unsafe {
             assert!(sid_ctx.len() <= c_uint::MAX as usize);
@@ -1254,10 +1202,7 @@ impl SslContextBuilder {
     /// Only a single certificate will be loaded - use `add_extra_chain_cert` to add the remainder
     /// of the certificate chain, or `set_certificate_chain_file` to load the entire chain from a
     /// single file.
-    ///
-    /// This corresponds to [`SSL_CTX_use_certificate_file`].
-    ///
-    /// [`SSL_CTX_use_certificate_file`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_use_certificate_file.html
+    #[corresponds(SSL_CTX_use_certificate_file)]
     pub fn set_certificate_file<P: AsRef<Path>>(
         &mut self,
         file: P,
@@ -1282,10 +1227,7 @@ impl SslContextBuilder {
     /// The file should contain a sequence of PEM-formatted certificates, the first being the leaf
     /// certificate, and the remainder forming the chain of certificates up to and including the
     /// trusted root certificate.
-    ///
-    /// This corresponds to [`SSL_CTX_use_certificate_chain_file`].
-    ///
-    /// [`SSL_CTX_use_certificate_chain_file`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_use_certificate_file.html
+    #[corresponds(SSL_CTX_use_certificate_chain_file)]
     pub fn set_certificate_chain_file<P: AsRef<Path>>(
         &mut self,
         file: P,
@@ -1303,10 +1245,7 @@ impl SslContextBuilder {
     /// Sets the leaf certificate.
     ///
     /// Use `add_extra_chain_cert` to add the remainder of the certificate chain.
-    ///
-    /// This corresponds to [`SSL_CTX_use_certificate`].
-    ///
-    /// [`SSL_CTX_use_certificate`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_use_certificate_file.html
+    #[corresponds(SSL_CTX_use_certificate)]
     pub fn set_certificate(&mut self, cert: &X509Ref) -> Result<(), ErrorStack> {
         unsafe { cvt(ffi::SSL_CTX_use_certificate(self.as_ptr(), cert.as_ptr())).map(|_| ()) }
     }
@@ -1315,10 +1254,7 @@ impl SslContextBuilder {
     ///
     /// This chain should contain all certificates necessary to go from the certificate specified by
     /// `set_certificate` to a trusted root.
-    ///
-    /// This corresponds to [`SSL_CTX_add_extra_chain_cert`].
-    ///
-    /// [`SSL_CTX_add_extra_chain_cert`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_add_extra_chain_cert.html
+    #[corresponds(SSL_CTX_add_extra_chain_cert)]
     pub fn add_extra_chain_cert(&mut self, cert: X509) -> Result<(), ErrorStack> {
         #[cfg(feature = "rpk")]
         assert!(!self.is_rpk, "This API is not supported for RPK");
@@ -1331,10 +1267,7 @@ impl SslContextBuilder {
     }
 
     /// Loads the private key from a file.
-    ///
-    /// This corresponds to [`SSL_CTX_use_PrivateKey_file`].
-    ///
-    /// [`SSL_CTX_use_PrivateKey_file`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_use_PrivateKey_file.html
+    #[corresponds(SSL_CTX_use_PrivateKey_file)]
     pub fn set_private_key_file<P: AsRef<Path>>(
         &mut self,
         file: P,
@@ -1352,10 +1285,7 @@ impl SslContextBuilder {
     }
 
     /// Sets the private key.
-    ///
-    /// This corresponds to [`SSL_CTX_use_PrivateKey`].
-    ///
-    /// [`SSL_CTX_use_PrivateKey`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_use_PrivateKey_file.html
+    #[corresponds(SSL_CTX_use_PrivateKey)]
     pub fn set_private_key<T>(&mut self, key: &PKeyRef<T>) -> Result<(), ErrorStack>
     where
         T: HasPrivate,
@@ -1371,10 +1301,8 @@ impl SslContextBuilder {
     ///
     /// See [`ciphers`] for details on the format.
     ///
-    /// This corresponds to [`SSL_CTX_set_cipher_list`].
-    ///
-    /// [`ciphers`]: https://www.openssl.org/docs/man1.1.0/apps/ciphers.html
-    /// [`SSL_CTX_set_cipher_list`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_cipher_list.html
+    /// [`ciphers`]: https://www.openssl.org/docs/manmaster/apps/ciphers.html
+    #[corresponds(SSL_CTX_set_cipher_list)]
     pub fn set_cipher_list(&mut self, cipher_list: &str) -> Result<(), ErrorStack> {
         let cipher_list = CString::new(cipher_list).unwrap();
         unsafe {
@@ -1390,44 +1318,33 @@ impl SslContextBuilder {
     ///
     /// See [`ciphers`] for details on the format
     ///
-    /// This corresponds to [`SSL_CTX_get_ciphers`].
-    ///
     /// [`ciphers`]: https://www.openssl.org/docs/manmaster/man1/ciphers.html
-    /// [`SSL_CTX_set_cipher_list`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_ciphers.html
+    #[corresponds(SSL_CTX_get_ciphers)]
     pub fn ciphers(&self) -> Option<&StackRef<SslCipher>> {
         self.ctx.ciphers()
     }
 
     /// Sets the options used by the context, returning the old set.
     ///
-    /// This corresponds to [`SSL_CTX_set_options`].
-    ///
     /// # Note
     ///
     /// This *enables* the specified options, but does not disable unspecified options. Use
     /// `clear_options` for that.
-    ///
-    /// [`SSL_CTX_set_options`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_options.html
+    #[corresponds(SSL_CTX_set_options)]
     pub fn set_options(&mut self, option: SslOptions) -> SslOptions {
         let bits = unsafe { ffi::SSL_CTX_set_options(self.as_ptr(), option.bits()) };
         SslOptions::from_bits_retain(bits)
     }
 
     /// Returns the options used by the context.
-    ///
-    /// This corresponds to [`SSL_CTX_get_options`].
-    ///
-    /// [`SSL_CTX_get_options`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_options.html
+    #[corresponds(SSL_CTX_get_options)]
     pub fn options(&self) -> SslOptions {
         let bits = unsafe { ffi::SSL_CTX_get_options(self.as_ptr()) };
         SslOptions::from_bits_retain(bits)
     }
 
     /// Clears the options used by the context, returning the old set.
-    ///
-    /// This corresponds to [`SSL_CTX_clear_options`].
-    ///
-    /// [`SSL_CTX_clear_options`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_options.html
+    #[corresponds(SSL_CTX_clear_options)]
     pub fn clear_options(&mut self, option: SslOptions) -> SslOptions {
         let bits = unsafe { ffi::SSL_CTX_clear_options(self.as_ptr(), option.bits()) };
         SslOptions::from_bits_retain(bits)
@@ -1437,10 +1354,7 @@ impl SslContextBuilder {
     ///
     /// If version is `None`, the default minimum version is used. For BoringSSL this defaults to
     /// TLS 1.0.
-    ///
-    /// This corresponds to [`SSL_CTX_set_min_proto_version`].
-    ///
-    /// [`SSL_CTX_set_min_proto_version`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_min_proto_version.html
+    #[corresponds(SSL_CTX_set_min_proto_version)]
     pub fn set_min_proto_version(&mut self, version: Option<SslVersion>) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::SSL_CTX_set_min_proto_version(
@@ -1454,10 +1368,7 @@ impl SslContextBuilder {
     /// Sets the maximum supported protocol version.
     ///
     /// If version is `None`, the default maximum version is used. For BoringSSL this is TLS 1.3.
-    ///
-    /// This corresponds to [`SSL_CTX_set_max_proto_version`].
-    ///
-    /// [`SSL_CTX_set_max_proto_version`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_max_proto_version.html
+    #[corresponds(SSL_CTX_set_max_proto_version)]
     pub fn set_max_proto_version(&mut self, version: Option<SslVersion>) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::SSL_CTX_set_max_proto_version(
@@ -1469,10 +1380,7 @@ impl SslContextBuilder {
     }
 
     /// Gets the minimum supported protocol version.
-    ///
-    /// This corresponds to [`SSL_CTX_get_min_proto_version`].
-    ///
-    /// [`SSL_CTX_get_min_proto_version`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_min_proto_version.html
+    #[corresponds(SSL_CTX_get_min_proto_version)]
     pub fn min_proto_version(&mut self) -> Option<SslVersion> {
         unsafe {
             let r = ffi::SSL_CTX_get_min_proto_version(self.as_ptr());
@@ -1485,10 +1393,7 @@ impl SslContextBuilder {
     }
 
     /// Gets the maximum supported protocol version.
-    ///
-    /// This corresponds to [`SSL_CTX_get_max_proto_version`].
-    ///
-    /// [`SSL_CTX_get_max_proto_version`]: https://www.openssl.org/docs/man3.1/man3/SSL_CTX_get_max_proto_version.html
+    #[corresponds(SSL_CTX_get_max_proto_version)]
     pub fn max_proto_version(&mut self) -> Option<SslVersion> {
         unsafe {
             let r = ffi::SSL_CTX_get_max_proto_version(self.as_ptr());
@@ -1506,10 +1411,7 @@ impl SslContextBuilder {
     /// names prefixed by their byte length. For example, the protocol list consisting of `spdy/1`
     /// and `http/1.1` is encoded as `b"\x06spdy/1\x08http/1.1"`. The protocols are ordered by
     /// preference.
-    ///
-    /// This corresponds to [`SSL_CTX_set_alpn_protos`].
-    ///
-    /// [`SSL_CTX_set_alpn_protos`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_alpn_protos.html
+    #[corresponds(SSL_CTX_set_alpn_protos)]
     pub fn set_alpn_protos(&mut self, protocols: &[u8]) -> Result<(), ErrorStack> {
         unsafe {
             #[cfg_attr(not(feature = "fips"), allow(clippy::unnecessary_cast))]
@@ -1531,10 +1433,7 @@ impl SslContextBuilder {
     }
 
     /// Enables the DTLS extension "use_srtp" as defined in RFC5764.
-    ///
-    /// This corresponds to [`SSL_CTX_set_tlsext_use_srtp`].
-    ///
-    /// [`SSL_CTX_set_tlsext_use_srtp`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_tlsext_use_srtp.html
+    #[corresponds(SSL_CTX_set_tlsext_use_srtp)]
     pub fn set_tlsext_use_srtp(&mut self, protocols: &str) -> Result<(), ErrorStack> {
         unsafe {
             let cstr = CString::new(protocols).unwrap();
@@ -1557,11 +1456,9 @@ impl SslContextBuilder {
     /// of those protocols on success. The [`select_next_proto`] function implements the standard
     /// protocol selection algorithm.
     ///
-    /// This corresponds to [`SSL_CTX_set_alpn_select_cb`].
-    ///
     /// [`SslContextBuilder::set_alpn_protos`]: struct.SslContextBuilder.html#method.set_alpn_protos
     /// [`select_next_proto`]: fn.select_next_proto.html
-    /// [`SSL_CTX_set_alpn_select_cb`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_alpn_protos.html
+    #[corresponds(SSL_CTX_set_alpn_select_cb)]
     pub fn set_alpn_select_callback<F>(&mut self, callback: F)
     where
         F: for<'a> Fn(&mut SslRef, &'a [u8]) -> Result<&'a [u8], AlpnError> + 'static + Sync + Send,
@@ -1579,10 +1476,7 @@ impl SslContextBuilder {
     /// Sets a callback that is called before most ClientHello processing and before the decision whether
     /// to resume a session is made. The callback may inspect the ClientHello and configure the
     /// connection.
-    ///
-    /// This corresponds to [`SSL_CTX_set_select_certificate_cb`].
-    ///
-    /// [`SSL_CTX_set_select_certificate_cb`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_select_certificate_cb.html
+    #[corresponds(SSL_CTX_set_select_certificate_cb)]
     pub fn set_select_certificate_callback<F>(&mut self, callback: F)
     where
         F: Fn(ClientHello<'_>) -> Result<(), SelectCertError> + Sync + Send + 'static,
@@ -1599,10 +1493,7 @@ impl SslContextBuilder {
     /// Configures a custom private key method on the context.
     ///
     /// See [`PrivateKeyMethod`] for more details.
-    ///
-    /// This corresponds to [`SSL_CTX_set_private_key_method`]
-    ///
-    /// [`SSL_CTX_set_private_key_method`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_set_private_key_method
+    #[corresponds(SSL_CTX_set_private_key_method)]
     pub fn set_private_key_method<M>(&mut self, method: M)
     where
         M: PrivateKeyMethod,
@@ -1622,19 +1513,13 @@ impl SslContextBuilder {
     }
 
     /// Checks for consistency between the private key and certificate.
-    ///
-    /// This corresponds to [`SSL_CTX_check_private_key`].
-    ///
-    /// [`SSL_CTX_check_private_key`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_check_private_key.html
+    #[corresponds(SSL_CTX_check_private_key)]
     pub fn check_private_key(&self) -> Result<(), ErrorStack> {
         unsafe { cvt(ffi::SSL_CTX_check_private_key(self.as_ptr())).map(|_| ()) }
     }
 
     /// Returns a shared reference to the context's certificate store.
-    ///
-    /// This corresponds to [`SSL_CTX_get_cert_store`].
-    ///
-    /// [`SSL_CTX_get_cert_store`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_get_cert_store.html
+    #[corresponds(SSL_CTX_get_cert_store)]
     pub fn cert_store(&self) -> &X509StoreBuilderRef {
         #[cfg(feature = "rpk")]
         assert!(!self.is_rpk, "This API is not supported for RPK");
@@ -1643,10 +1528,7 @@ impl SslContextBuilder {
     }
 
     /// Returns a mutable reference to the context's certificate store.
-    ///
-    /// This corresponds to [`SSL_CTX_get_cert_store`].
-    ///
-    /// [`SSL_CTX_get_cert_store`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_get_cert_store.html
+    #[corresponds(SSL_CTX_get_cert_store)]
     pub fn cert_store_mut(&mut self) -> &mut X509StoreBuilderRef {
         #[cfg(feature = "rpk")]
         assert!(!self.is_rpk, "This API is not supported for RPK");
@@ -1666,10 +1548,7 @@ impl SslContextBuilder {
     /// returned to clients. The status may be set with the `SslRef::set_ocsp_status` method. A
     /// response of `Ok(true)` indicates that the OCSP status should be returned to the client, and
     /// `Ok(false)` indicates that the status should not be returned to the client.
-    ///
-    /// This corresponds to [`SSL_CTX_set_tlsext_status_cb`].
-    ///
-    /// [`SSL_CTX_set_tlsext_status_cb`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_tlsext_status_cb.html
+    #[corresponds(SSL_CTX_set_tlsext_status_cb)]
     pub fn set_status_callback<F>(&mut self, callback: F) -> Result<(), ErrorStack>
     where
         F: Fn(&mut SslRef) -> Result<bool, ErrorStack> + 'static + Sync + Send,
@@ -1689,10 +1568,7 @@ impl SslContextBuilder {
     /// The callback will be called with the SSL context, an identity hint if one was provided
     /// by the server, a mutable slice for each of the identity and pre-shared key bytes. The
     /// identity must be written as a null-terminated C string.
-    ///
-    /// This corresponds to [`SSL_CTX_set_psk_client_callback`].
-    ///
-    /// [`SSL_CTX_set_psk_client_callback`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_psk_client_callback.html
+    #[corresponds(SSL_CTX_set_psk_client_callback)]
     pub fn set_psk_client_callback<F>(&mut self, callback: F)
     where
         F: Fn(&mut SslRef, Option<&[u8]>, &mut [u8], &mut [u8]) -> Result<usize, ErrorStack>
@@ -1722,10 +1598,7 @@ impl SslContextBuilder {
     /// The callback will be called with the SSL context, an identity provided by the client,
     /// and, a mutable slice for the pre-shared key bytes. The callback returns the number of
     /// bytes in the pre-shared key.
-    ///
-    /// This corresponds to [`SSL_CTX_set_psk_server_callback`].
-    ///
-    /// [`SSL_CTX_set_psk_server_callback`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_psk_server_callback.html
+    #[corresponds(SSL_CTX_set_psk_server_callback)]
     pub fn set_psk_server_callback<F>(&mut self, callback: F)
     where
         F: Fn(&mut SslRef, Option<&[u8]>, &mut [u8]) -> Result<usize, ErrorStack>
@@ -1750,11 +1623,9 @@ impl SslContextBuilder {
     /// Note that session caching must be enabled for the callback to be invoked, and it defaults
     /// off for clients. [`set_session_cache_mode`] controls that behavior.
     ///
-    /// This corresponds to [`SSL_CTX_sess_set_new_cb`].
-    ///
     /// [`SslRef::session`]: struct.SslRef.html#method.session
     /// [`set_session_cache_mode`]: #method.set_session_cache_mode
-    /// [`SSL_CTX_sess_set_new_cb`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html
+    #[corresponds(SSL_CTX_sess_set_new_cb)]
     pub fn set_new_session_callback<F>(&mut self, callback: F)
     where
         F: Fn(&mut SslRef, SslSession) + 'static + Sync + Send,
@@ -1768,10 +1639,7 @@ impl SslContextBuilder {
     /// Sets the callback which is called when sessions are removed from the context.
     ///
     /// Sessions can be removed because they have timed out or because they are considered faulty.
-    ///
-    /// This corresponds to [`SSL_CTX_sess_set_remove_cb`].
-    ///
-    /// [`SSL_CTX_sess_set_remove_cb`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html
+    #[corresponds(SSL_CTX_sess_set_remove_cb)]
     pub fn set_remove_session_callback<F>(&mut self, callback: F)
     where
         F: Fn(&SslContextRef, &SslSessionRef) + 'static + Sync + Send,
@@ -1792,13 +1660,10 @@ impl SslContextBuilder {
     /// return the session corresponding to that ID if available. This is only used for servers, not
     /// clients.
     ///
-    /// This corresponds to [`SSL_CTX_sess_set_get_cb`].
-    ///
     /// # Safety
     ///
     /// The returned [`SslSession`] must not be associated with a different [`SslContext`].
-    ///
-    /// [`SSL_CTX_sess_set_get_cb`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html
+    #[corresponds(SSL_CTX_sess_set_get_cb)]
     pub unsafe fn set_get_session_callback<F>(&mut self, callback: F)
     where
         F: Fn(&mut SslRef, &[u8]) -> Result<Option<SslSession>, GetSessionPendingError>
@@ -1815,10 +1680,7 @@ impl SslContextBuilder {
     /// The callback is invoked whenever TLS key material is generated, and is passed a line of NSS
     /// SSLKEYLOGFILE-formatted text. This can be used by tools like Wireshark to decrypt message
     /// traffic. The line does not contain a trailing newline.
-    ///
-    /// This corresponds to [`SSL_CTX_set_keylog_callback`].
-    ///
-    /// [`SSL_CTX_set_keylog_callback`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_keylog_callback.html
+    #[corresponds(SSL_CTX_set_keylog_callback)]
     pub fn set_keylog_callback<F>(&mut self, callback: F)
     where
         F: Fn(&SslRef, &str) + 'static + Sync + Send,
@@ -1832,10 +1694,7 @@ impl SslContextBuilder {
     /// Sets the session caching mode use for connections made with the context.
     ///
     /// Returns the previous session caching mode.
-    ///
-    /// This corresponds to [`SSL_CTX_set_session_cache_mode`].
-    ///
-    /// [`SSL_CTX_set_session_cache_mode`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_get_session_cache_mode.html
+    #[corresponds(SSL_CTX_set_session_cache_mode)]
     pub fn set_session_cache_mode(&mut self, mode: SslSessionCacheMode) -> SslSessionCacheMode {
         unsafe {
             let bits = ffi::SSL_CTX_set_session_cache_mode(self.as_ptr(), mode.bits());
@@ -1848,12 +1707,9 @@ impl SslContextBuilder {
     /// This can be used to provide data to callbacks registered with the context. Use the
     /// `SslContext::new_ex_index` method to create an `Index`.
     ///
-    /// This corresponds to [`SSL_CTX_set_ex_data`].
-    ///
     /// Note that if this method is called multiple times with the same index, any previous
     /// value stored in the `SslContextBuilder` will be leaked.
-    ///
-    /// [`SSL_CTX_set_ex_data`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_ex_data.html
+    #[corresponds(SSL_CTX_set_ex_data)]
     pub fn set_ex_data<T>(&mut self, index: Index<SslContext, T>, data: T) {
         unsafe {
             self.ctx.set_ex_data(index, data);
@@ -1865,11 +1721,8 @@ impl SslContextBuilder {
     /// This can be used to provide data to callbacks registered with the context. Use the
     /// `Ssl::new_ex_index` method to create an `Index`.
     ///
-    /// This corresponds to [`SSL_set_ex_data`].
-    ///
     /// Any previous value will be returned and replaced by the new one.
-    ///
-    /// [`SSL_set_ex_data`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_ex_data.html
+    #[corresponds(SSL_CTX_set_ex_data)]
     pub fn replace_ex_data<T>(&mut self, index: Index<SslContext, T>, data: T) -> Option<T> {
         unsafe { self.ctx.replace_ex_data(index, data) }
     }
@@ -1877,20 +1730,14 @@ impl SslContextBuilder {
     /// Sets the context's session cache size limit, returning the previous limit.
     ///
     /// A value of 0 means that the cache size is unbounded.
-    ///
-    /// This corresponds to [`SSL_CTX_sess_get_cache_size`].
-    ///
-    /// [`SSL_CTX_sess_get_cache_size`]: https://www.openssl.org/docs/man1.0.2/man3/SSL_CTX_sess_set_cache_size.html
+    #[corresponds(SSL_CTX_sess_set_cache_size)]
     #[allow(clippy::useless_conversion)]
     pub fn set_session_cache_size(&mut self, size: u32) -> u64 {
         unsafe { ffi::SSL_CTX_sess_set_cache_size(self.as_ptr(), size.into()).into() }
     }
 
     /// Sets the context's supported signature algorithms.
-    ///
-    /// This corresponds to [`SSL_CTX_set1_sigalgs_list`].
-    ///
-    /// [`SSL_CTX_set1_sigalgs_list`]: https://www.openssl.org/docs/man1.1.0/man3/SSL_CTX_set1_sigalgs_list.html
+    #[corresponds(SSL_CTX_set1_sigalgs_list)]
     pub fn set_sigalgs_list(&mut self, sigalgs: &str) -> Result<(), ErrorStack> {
         let sigalgs = CString::new(sigalgs).unwrap();
         unsafe {
@@ -1900,33 +1747,24 @@ impl SslContextBuilder {
     }
 
     /// Set's whether the context should enable GREASE.
-    ///
-    /// This corresponds to [`SSL_CTX_set_grease_enabled`]
-    ///
-    /// [`SSL_CTX_set_grease_enabled`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_set_grease_enabled
+    #[corresponds(SSL_CTX_set_grease_enabled)]
     pub fn set_grease_enabled(&mut self, enabled: bool) {
         unsafe { ffi::SSL_CTX_set_grease_enabled(self.as_ptr(), enabled as _) }
     }
 
     /// Configures whether ClientHello extensions should be permuted.
     ///
-    /// This corresponds to [`SSL_CTX_set_permute_extensions`].
-    ///
-    /// [`SSL_CTX_set_permute_extensions`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_set_permute_extensions
-    ///
     /// Note: This is gated to non-fips because the fips feature builds with a separate
     /// version of BoringSSL which doesn't yet include these APIs.
     /// Once the submoduled fips commit is upgraded, these gates can be removed.
+    #[corresponds(SSL_CTX_set_permute_extensions)]
     #[cfg(not(feature = "fips"))]
     pub fn set_permute_extensions(&mut self, enabled: bool) {
         unsafe { ffi::SSL_CTX_set_permute_extensions(self.as_ptr(), enabled as _) }
     }
 
     /// Sets the context's supported signature verification algorithms.
-    ///
-    /// This corresponds to [`SSL_CTX_set_verify_algorithm_prefs`]
-    ///
-    /// [`SSL_CTX_set_verify_algorithm_prefs`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_set_verify_algorithm_prefs
+    #[corresponds(SSL_CTX_set_verify_algorithm_prefs)]
     pub fn set_verify_algorithm_prefs(
         &mut self,
         prefs: &[SslSignatureAlgorithm],
@@ -1942,32 +1780,23 @@ impl SslContextBuilder {
     }
 
     /// Enables SCT requests on all client SSL handshakes.
-    ///
-    /// This corresponds to [`SSL_CTX_enable_signed_cert_timestamps`]
-    ///
-    /// [`SSL_CTX_enable_signed_cert_timestamps`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_enable_signed_cert_timestamps
+    #[corresponds(SSL_CTX_enable_signed_cert_timestamps)]
     pub fn enable_signed_cert_timestamps(&mut self) {
         unsafe { ffi::SSL_CTX_enable_signed_cert_timestamps(self.as_ptr()) }
     }
 
     /// Enables OCSP stapling on all client SSL handshakes.
-    ///
-    /// This corresponds to [`SSL_CTX_enable_ocsp_stapling`]
-    ///
-    /// [`SSL_CTX_enable_ocsp_stapling`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_enable_ocsp_stapling
+    #[corresponds(SSL_CTX_enable_ocsp_stapling)]
     pub fn enable_ocsp_stapling(&mut self) {
         unsafe { ffi::SSL_CTX_enable_ocsp_stapling(self.as_ptr()) }
     }
 
     /// Sets the context's supported curves.
-    ///
-    /// This corresponds to [`SSL_CTX_set1_curves`]
-    ///
-    /// [`SSL_CTX_set1_curves`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_set1_curves
     //
     // If the "kx-*" flags are used to set key exchange preference, then don't allow the user to
     // set them here. This ensures we don't override the user's preference without telling them:
     // when the flags are used, the preferences are set just before connecting or accepting.
+    #[corresponds(SSL_CTX_set1_curves)]
     #[cfg(not(feature = "kx-safe-default"))]
     pub fn set_curves(&mut self, curves: &[SslCurve]) -> Result<(), ErrorStack> {
         let curves: Vec<i32> = curves.iter().filter_map(|curve| curve.nid()).collect();
@@ -1984,10 +1813,8 @@ impl SslContextBuilder {
 
     /// Sets the context's compliance policy.
     ///
-    /// This corresponds to [`SSL_CTX_set_compliance_policy`]
-    ///
-    /// [`SSL_CTX_set_compliance_policy`] https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_set_compliance_policy
     /// This feature isn't available in the certified version of BoringSSL.
+    #[corresponds(SSL_CTX_set_compliance_policy)]
     #[cfg(not(feature = "fips"))]
     pub fn set_compliance_policy(&mut self, policy: CompliancePolicy) -> Result<(), ErrorStack> {
         unsafe { cvt_0i(ffi::SSL_CTX_set_compliance_policy(self.as_ptr(), policy.0)).map(|_| ()) }
@@ -2044,10 +1871,7 @@ impl SslContext {
     ///
     /// Each invocation of this function is guaranteed to return a distinct index. These can be used
     /// to store data in the context that can be retrieved later by callbacks, for example.
-    ///
-    /// This corresponds to [`SSL_CTX_get_ex_new_index`].
-    ///
-    /// [`SSL_CTX_get_ex_new_index`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_get_ex_new_index.html
+    #[corresponds(SSL_CTX_get_ex_new_index)]
     pub fn new_ex_index<T>() -> Result<Index<SslContext, T>, ErrorStack>
     where
         T: 'static + Sync + Send,
@@ -2078,10 +1902,8 @@ impl SslContext {
     ///
     /// See [`ciphers`] for details on the format
     ///
-    /// This corresponds to [`SSL_CTX_get_ciphers`].
-    ///
     /// [`ciphers`]: https://www.openssl.org/docs/manmaster/man1/ciphers.html
-    /// [`SSL_CTX_set_cipher_list`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_ciphers.html
+    #[corresponds(SSL_CTX_get_ciphers)]
     pub fn ciphers(&self) -> Option<&StackRef<SslCipher>> {
         unsafe {
             let ciphers = ffi::SSL_CTX_get_ciphers(self.as_ptr());
@@ -2096,10 +1918,7 @@ impl SslContext {
 
 impl SslContextRef {
     /// Returns the certificate associated with this `SslContext`, if present.
-    ///
-    /// This corresponds to [`SSL_CTX_get0_certificate`].
-    ///
-    /// [`SSL_CTX_get0_certificate`]: https://www.openssl.org/docs/man1.1.0/ssl/ssl.html
+    #[corresponds(SSL_CTX_get0_certificate)]
     pub fn certificate(&self) -> Option<&X509Ref> {
         #[cfg(feature = "rpk")]
         assert!(!self.is_rpk(), "This API is not supported for RPK");
@@ -2115,10 +1934,7 @@ impl SslContextRef {
     }
 
     /// Returns the private key associated with this `SslContext`, if present.
-    ///
-    /// This corresponds to [`SSL_CTX_get0_privatekey`].
-    ///
-    /// [`SSL_CTX_get0_privatekey`]: https://www.openssl.org/docs/man1.1.0/ssl/ssl.html
+    #[corresponds(SSL_CTX_get0_privatekey)]
     pub fn private_key(&self) -> Option<&PKeyRef<Private>> {
         unsafe {
             let ptr = ffi::SSL_CTX_get0_privatekey(self.as_ptr());
@@ -2131,10 +1947,7 @@ impl SslContextRef {
     }
 
     /// Returns a shared reference to the certificate store used for verification.
-    ///
-    /// This corresponds to [`SSL_CTX_get_cert_store`].
-    ///
-    /// [`SSL_CTX_get_cert_store`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_get_cert_store.html
+    #[corresponds(SSL_CTX_get_cert_store)]
     pub fn cert_store(&self) -> &X509StoreRef {
         #[cfg(feature = "rpk")]
         assert!(!self.is_rpk(), "This API is not supported for RPK");
@@ -2143,8 +1956,7 @@ impl SslContextRef {
     }
 
     /// Returns a shared reference to the stack of certificates making up the chain from the leaf.
-    ///
-    /// This corresponds to `SSL_CTX_get_extra_chain_certs`.
+    #[corresponds(SSL_CTX_get_extra_chain_certs)]
     pub fn extra_chain_certs(&self) -> &StackRef<X509> {
         unsafe {
             let mut chain = ptr::null_mut();
@@ -2155,10 +1967,7 @@ impl SslContextRef {
     }
 
     /// Returns a reference to the extra data at the specified index.
-    ///
-    /// This corresponds to [`SSL_CTX_get_ex_data`].
-    ///
-    /// [`SSL_CTX_get_ex_data`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_ex_data.html
+    #[corresponds(SSL_CTX_get_ex_data)]
     pub fn ex_data<T>(&self, index: Index<SslContext, T>) -> Option<&T> {
         unsafe {
             let data = ffi::SSL_CTX_get_ex_data(self.as_ptr(), index.as_raw());
@@ -2172,6 +1981,7 @@ impl SslContextRef {
 
     // Unsafe because SSL contexts are not guaranteed to be unique, we call
     // this only from SslContextBuilder.
+    #[corresponds(SSL_CTX_get_ex_data)]
     unsafe fn ex_data_mut<T>(&mut self, index: Index<SslContext, T>) -> Option<&mut T> {
         let data = ffi::SSL_CTX_get_ex_data(self.as_ptr(), index.as_raw());
         if data.is_null() {
@@ -2183,6 +1993,7 @@ impl SslContextRef {
 
     // Unsafe because SSL contexts are not guaranteed to be unique, we call
     // this only from SslContextBuilder.
+    #[corresponds(SSL_CTX_set_ex_data)]
     unsafe fn set_ex_data<T>(&mut self, index: Index<SslContext, T>, data: T) {
         unsafe {
             let data = Box::into_raw(Box::new(data)) as *mut c_void;
@@ -2192,6 +2003,7 @@ impl SslContextRef {
 
     // Unsafe because SSL contexts are not guaranteed to be unique, we call
     // this only from SslContextBuilder.
+    #[corresponds(SSL_CTX_set_ex_data)]
     unsafe fn replace_ex_data<T>(&mut self, index: Index<SslContext, T>, data: T) -> Option<T> {
         if let Some(old) = self.ex_data_mut(index) {
             return Some(mem::replace(old, data));
@@ -2206,14 +2018,11 @@ impl SslContextRef {
     ///
     /// Returns `true` if the session was successfully added to the cache, and `false` if it was already present.
     ///
-    /// This corresponds to [`SSL_CTX_add_session`].
-    ///
     /// # Safety
     ///
     /// The caller of this method is responsible for ensuring that the session has never been used with another
     /// `SslContext` than this one.
-    ///
-    /// [`SSL_CTX_add_session`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_remove_session.html
+    #[corresponds(SSL_CTX_add_session)]
     pub unsafe fn add_session(&self, session: &SslSessionRef) -> bool {
         ffi::SSL_CTX_add_session(self.as_ptr(), session.as_ptr()) != 0
     }
@@ -2222,14 +2031,11 @@ impl SslContextRef {
     ///
     /// Returns `true` if the session was successfully found and removed, and `false` otherwise.
     ///
-    /// This corresponds to [`SSL_CTX_remove_session`].
-    ///
     /// # Safety
     ///
     /// The caller of this method is responsible for ensuring that the session has never been used with another
     /// `SslContext` than this one.
-    ///
-    /// [`SSL_CTX_remove_session`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_remove_session.html
+    #[corresponds(SSL_CTX_remove_session)]
     pub unsafe fn remove_session(&self, session: &SslSessionRef) -> bool {
         ffi::SSL_CTX_remove_session(self.as_ptr(), session.as_ptr()) != 0
     }
@@ -2237,10 +2043,7 @@ impl SslContextRef {
     /// Returns the context's session cache size limit.
     ///
     /// A value of 0 means that the cache size is unbounded.
-    ///
-    /// This corresponds to [`SSL_CTX_sess_get_cache_size`].
-    ///
-    /// [`SSL_CTX_sess_get_cache_size`]: https://www.openssl.org/docs/man1.0.2/man3/SSL_CTX_sess_set_cache_size.html
+    #[corresponds(SSL_CTX_sess_get_cache_size)]
     #[allow(clippy::useless_conversion)]
     pub fn session_cache_size(&self) -> u64 {
         unsafe { ffi::SSL_CTX_sess_get_cache_size(self.as_ptr()).into() }
@@ -2248,10 +2051,8 @@ impl SslContextRef {
 
     /// Returns the verify mode that was set on this context from [`SslContextBuilder::set_verify`].
     ///
-    /// This corresponds to [`SSL_CTX_get_verify_mode`].
-    ///
     /// [`SslContextBuilder::set_verify`]: struct.SslContextBuilder.html#method.set_verify
-    /// [`SSL_CTX_get_verify_mode`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_get_verify_mode.html
+    #[corresponds(SSL_CTX_get_verify_mode)]
     pub fn verify_mode(&self) -> SslVerifyMode {
         #[cfg(feature = "rpk")]
         assert!(!self.is_rpk(), "This API is not supported for RPK");
@@ -2353,6 +2154,7 @@ impl ClientHello<'_> {
 pub struct SslCipher(*mut ffi::SSL_CIPHER);
 
 impl SslCipher {
+    #[corresponds(SSL_get_cipher_by_value)]
     pub fn from_value(value: u16) -> Option<Self> {
         unsafe {
             let ptr = ffi::SSL_get_cipher_by_value(value);
@@ -2409,10 +2211,7 @@ unsafe impl ForeignTypeRef for SslCipherRef {
 
 impl SslCipherRef {
     /// Returns the name of the cipher.
-    ///
-    /// This corresponds to [`SSL_CIPHER_get_name`].
-    ///
-    /// [`SSL_CIPHER_get_name`]: https://www.openssl.org/docs/manmaster/man3/SSL_CIPHER_get_name.html
+    #[corresponds(SSL_CIPHER_get_name)]
     pub fn name(&self) -> &'static str {
         unsafe {
             let ptr = ffi::SSL_CIPHER_get_name(self.as_ptr());
@@ -2421,10 +2220,7 @@ impl SslCipherRef {
     }
 
     /// Returns the RFC-standard name of the cipher, if one exists.
-    ///
-    /// This corresponds to [`SSL_CIPHER_standard_name`].
-    ///
-    /// [`SSL_CIPHER_standard_name`]: https://www.openssl.org/docs/manmaster/man3/SSL_CIPHER_get_name.html
+    #[corresponds(SSL_CIPHER_standard_name)]
     pub fn standard_name(&self) -> Option<&'static str> {
         unsafe {
             let ptr = ffi::SSL_CIPHER_standard_name(self.as_ptr());
@@ -2437,10 +2233,7 @@ impl SslCipherRef {
     }
 
     /// Returns the SSL/TLS protocol version that first defined the cipher.
-    ///
-    /// This corresponds to [`SSL_CIPHER_get_version`].
-    ///
-    /// [`SSL_CIPHER_get_version`]: https://www.openssl.org/docs/manmaster/man3/SSL_CIPHER_get_name.html
+    #[corresponds(SSL_CIPHER_get_version)]
     pub fn version(&self) -> &'static str {
         let version = unsafe {
             let ptr = ffi::SSL_CIPHER_get_version(self.as_ptr());
@@ -2451,10 +2244,7 @@ impl SslCipherRef {
     }
 
     /// Returns the number of bits used for the cipher.
-    ///
-    /// This corresponds to [`SSL_CIPHER_get_bits`].
-    ///
-    /// [`SSL_CIPHER_get_bits`]: https://www.openssl.org/docs/manmaster/man3/SSL_CIPHER_get_name.html
+    #[corresponds(SSL_CIPHER_get_bits)]
     #[allow(clippy::useless_conversion)]
     pub fn bits(&self) -> CipherBits {
         unsafe {
@@ -2468,10 +2258,7 @@ impl SslCipherRef {
     }
 
     /// Returns a textual description of the cipher.
-    ///
-    /// This corresponds to [`SSL_CIPHER_description`].
-    ///
-    /// [`SSL_CIPHER_description`]: https://www.openssl.org/docs/manmaster/man3/SSL_CIPHER_get_name.html
+    #[corresponds(SSL_CIPHER_description)]
     pub fn description(&self) -> String {
         unsafe {
             // SSL_CIPHER_description requires a buffer of at least 128 bytes.
@@ -2482,19 +2269,13 @@ impl SslCipherRef {
     }
 
     /// Returns one if the cipher uses an AEAD cipher.
-    ///
-    /// This corresponds to [`SSL_CIPHER_is_aead`].
-    ///
-    /// [`SSL_CIPHER_is_aead`]: https://www.openssl.org/docs/manmaster/man3/SSL_CIPHER_is_aead.html
+    #[corresponds(SSL_CIPHER_is_aead)]
     pub fn cipher_is_aead(&self) -> bool {
         unsafe { ffi::SSL_CIPHER_is_aead(self.as_ptr()) != 0 }
     }
 
     /// Returns the NID corresponding to the cipher's authentication type.
-    ///
-    /// This corresponds to [`SSL_CIPHER_get_auth_nid`].
-    ///
-    /// [`SSL_CIPHER_get_auth_nid`]: https://www.openssl.org/docs/manmaster/man3/SSL_CIPHER_get_auth_nid.html
+    #[corresponds(SSL_CIPHER_get_auth_nid)]
     pub fn cipher_auth_nid(&self) -> Option<Nid> {
         let n = unsafe { ffi::SSL_CIPHER_get_auth_nid(self.as_ptr()) };
         if n == 0 {
@@ -2505,10 +2286,7 @@ impl SslCipherRef {
     }
 
     /// Returns the NID corresponding to the cipher.
-    ///
-    /// This corresponds to [`SSL_CIPHER_get_cipher_nid`].
-    ///
-    /// [`SSL_CIPHER_get_cipher_nid`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CIPHER_get_cipher_nid.html
+    #[corresponds(SSL_CIPHER_get_cipher_nid)]
     pub fn cipher_nid(&self) -> Option<Nid> {
         let n = unsafe { ffi::SSL_CIPHER_get_cipher_nid(self.as_ptr()) };
         if n == 0 {
@@ -2562,10 +2340,7 @@ impl ToOwned for SslSessionRef {
 
 impl SslSessionRef {
     /// Returns the SSL session ID.
-    ///
-    /// This corresponds to [`SSL_SESSION_get_id`].
-    ///
-    /// [`SSL_SESSION_get_id`]: https://www.openssl.org/docs/manmaster/man3/SSL_SESSION_get_id.html
+    #[corresponds(SSL_SESSION_get_id)]
     pub fn id(&self) -> &[u8] {
         unsafe {
             let mut len = 0;
@@ -2575,10 +2350,7 @@ impl SslSessionRef {
     }
 
     /// Returns the length of the master key.
-    ///
-    /// This corresponds to [`SSL_SESSION_get_master_key`].
-    ///
-    /// [`SSL_SESSION_get_master_key`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_SESSION_get_master_key.html
+    #[corresponds(SSL_SESSION_get_master_key)]
     pub fn master_key_len(&self) -> usize {
         unsafe { SSL_SESSION_get_master_key(self.as_ptr(), ptr::null_mut(), 0) }
     }
@@ -2586,19 +2358,13 @@ impl SslSessionRef {
     /// Copies the master key into the provided buffer.
     ///
     /// Returns the number of bytes written, or the size of the master key if the buffer is empty.
-    ///
-    /// This corresponds to [`SSL_SESSION_get_master_key`].
-    ///
-    /// [`SSL_SESSION_get_master_key`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_SESSION_get_master_key.html
+    #[corresponds(SSL_SESSION_get_master_key)]
     pub fn master_key(&self, buf: &mut [u8]) -> usize {
         unsafe { SSL_SESSION_get_master_key(self.as_ptr(), buf.as_mut_ptr(), buf.len()) }
     }
 
     /// Returns the time at which the session was established, in seconds since the Unix epoch.
-    ///
-    /// This corresponds to [`SSL_SESSION_get_time`].
-    ///
-    /// [`SSL_SESSION_get_time`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_SESSION_get_time.html
+    #[corresponds(SSL_SESSION_get_time)]
     #[allow(clippy::useless_conversion)]
     pub fn time(&self) -> u64 {
         unsafe { ffi::SSL_SESSION_get_time(self.as_ptr()) }
@@ -2607,20 +2373,14 @@ impl SslSessionRef {
     /// Returns the sessions timeout, in seconds.
     ///
     /// A session older than this time should not be used for session resumption.
-    ///
-    /// This corresponds to [`SSL_SESSION_get_timeout`].
-    ///
-    /// [`SSL_SESSION_get_timeout`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_SESSION_get_time.html
+    #[corresponds(SSL_SESSION_get_timeout)]
     #[allow(clippy::useless_conversion)]
     pub fn timeout(&self) -> u32 {
         unsafe { ffi::SSL_SESSION_get_timeout(self.as_ptr()) }
     }
 
     /// Returns the session's TLS protocol version.
-    ///
-    /// This corresponds to [`SSL_SESSION_get_protocol_version`].
-    ///
-    /// [`SSL_SESSION_get_protocol_version`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_SESSION_get_protocol_version.html
+    #[corresponds(SSL_SESSION_get_protocol_version)]
     pub fn protocol_version(&self) -> SslVersion {
         unsafe {
             let version = ffi::SSL_SESSION_get_protocol_version(self.as_ptr());
@@ -2663,10 +2423,7 @@ impl Ssl {
     ///
     /// Each invocation of this function is guaranteed to return a distinct index. These can be used
     /// to store data in the context that can be retrieved later by callbacks, for example.
-    ///
-    /// This corresponds to [`SSL_get_ex_new_index`].
-    ///
-    /// [`SSL_get_ex_new_index`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_get_ex_new_index.html
+    #[corresponds(SSL_get_ex_new_index)]
     pub fn new_ex_index<T>() -> Result<Index<Ssl, T>, ErrorStack>
     where
         T: 'static + Sync + Send,
@@ -2695,10 +2452,8 @@ impl Ssl {
 
     /// Creates a new `Ssl`.
     ///
-    /// This corresponds to [`SSL_new`].
-    ///
-    /// [`SSL_new`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_new.html
     // FIXME should take &SslContextRef
+    #[corresponds(SSL_new)]
     pub fn new(ctx: &SslContext) -> Result<Ssl, ErrorStack> {
         unsafe {
             let ptr = cvt_p(ffi::SSL_new(ctx.as_ptr()))?;
@@ -2711,10 +2466,9 @@ impl Ssl {
 
     /// Creates a new [`Ssl`].
     ///
-    /// This corresponds to [`SSL_new`](`ffi::SSL_new`).
-    ///
     /// This function does the same as [`Self:new`] except that it takes &[SslContextRef].
     // Both functions exist for backward compatibility (no breaking API).
+    #[corresponds(SSL_new)]
     pub fn new_from_ref(ctx: &SslContextRef) -> Result<Ssl, ErrorStack> {
         unsafe {
             let ptr = cvt_p(ffi::SSL_new(ctx.as_ptr()))?;
@@ -2836,6 +2590,7 @@ impl SslRef {
         unsafe { ffi::SSL_get_rbio(self.as_ptr()) }
     }
 
+    #[corresponds(SSL_set1_curves_list)]
     #[cfg(feature = "kx-safe-default")]
     fn set_curves_list(&mut self, curves: &str) -> Result<(), ErrorStack> {
         let curves = CString::new(curves).unwrap();
@@ -2881,10 +2636,7 @@ impl SslRef {
     }
 
     /// Returns the [`SslCurve`] used for this `SslRef`.
-    ///
-    /// This corresponds to [`SSL_get_curve_id`]
-    ///
-    /// [`SSL_get_curve_id`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_get_curve_id
+    #[corresponds(SSL_get_curve_id)]
     pub fn curve(&self) -> Option<SslCurve> {
         let curve_id = unsafe { ffi::SSL_get_curve_id(self.as_ptr()) };
         if curve_id == 0 {
@@ -2894,20 +2646,15 @@ impl SslRef {
     }
 
     /// Returns an `ErrorCode` value for the most recent operation on this `SslRef`.
-    ///
-    /// This corresponds to [`SSL_get_error`].
-    ///
-    /// [`SSL_get_error`]: https://github.com/google/boringssl/blob/master/include/openssl/ssl.h#L475
+    #[corresponds(SSL_get_error)]
     pub fn error_code(&self, ret: c_int) -> ErrorCode {
         unsafe { ErrorCode::from_raw(ffi::SSL_get_error(self.as_ptr(), ret)) }
     }
 
     /// Like [`SslContextBuilder::set_verify`].
     ///
-    /// This corresponds to [`SSL_set_verify`].
-    ///
     /// [`SslContextBuilder::set_verify`]: struct.SslContextBuilder.html#method.set_verify
-    /// [`SSL_set_verify`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_set_verify.html
+    #[corresponds(SSL_set_verify)]
     pub fn set_verify(&mut self, mode: SslVerifyMode) {
         #[cfg(feature = "rpk")]
         assert!(
@@ -2921,10 +2668,7 @@ impl SslRef {
     /// Sets the certificate verification depth.
     ///
     /// If the peer's certificate chain is longer than this value, verification will fail.
-    ///
-    /// This corresponds to [`SSL_set_verify_depth`].
-    ///
-    /// [`SSL_set_verify_depth`]: https://docs.openssl.org/1.1.1/man3/SSL_CTX_set_verify/
+    #[corresponds(SSL_set_verify_depth)]
     pub fn set_verify_depth(&mut self, depth: u32) {
         #[cfg(feature = "rpk")]
         assert!(
@@ -2938,10 +2682,7 @@ impl SslRef {
     }
 
     /// Returns the verify mode that was set using `set_verify`.
-    ///
-    /// This corresponds to [`SSL_get_verify_mode`].
-    ///
-    /// [`SSL_get_verify_mode`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_get_verify_mode.html
+    #[corresponds(SSL_get_verify_mode)]
     pub fn verify_mode(&self) -> SslVerifyMode {
         #[cfg(feature = "rpk")]
         assert!(
@@ -2966,13 +2707,10 @@ impl SslRef {
     /// call [`X509StoreContextRef::verify_cert`] and inspect the result, or perform
     /// other operations more straightforwardly.
     ///
-    /// This corresponds to [`SSL_set_verify`].
-    ///
     /// # Panics
     ///
     /// This method panics if this `Ssl` is associated with a RPK context.
-    ///
-    /// [`SSL_set_verify`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_set_verify.html
+    #[corresponds(SSL_set_verify)]
     pub fn set_verify_callback<F>(&mut self, mode: SslVerifyMode, callback: F)
     where
         F: Fn(bool, &mut X509StoreContextRef) -> bool + 'static + Sync + Send,
@@ -2995,10 +2733,7 @@ impl SslRef {
     }
 
     /// Sets a custom certificate store for verifying peer certificates.
-    ///
-    /// This corresponds to [`SSL_CTX_set0_verify_cert_store`].
-    ///
-    /// [`SSL_set0_verify_cert_store`]: https://docs.openssl.org/1.0.2/man3/SSL_CTX_set1_verify_cert_store/
+    #[corresponds(SSL_set0_verify_cert_store)]
     pub fn set_verify_cert_store(&mut self, cert_store: X509Store) -> Result<(), ErrorStack> {
         #[cfg(feature = "rpk")]
         assert!(
@@ -3015,11 +2750,10 @@ impl SslRef {
 
     /// Like [`SslContextBuilder::set_custom_verify_callback`].
     ///
-    /// This corresponds to [`SSL_set_custom_verify`].
-    ///
     /// # Panics
     ///
     /// This method panics if this `Ssl` is associated with a RPK context.
+    #[corresponds(SSL_set_custom_verify)]
     pub fn set_custom_verify_callback<F>(&mut self, mode: SslVerifyMode, callback: F)
     where
         F: Fn(&mut SslRef) -> Result<(), SslVerifyError> + 'static + Sync + Send,
@@ -3043,19 +2777,16 @@ impl SslRef {
 
     /// Like [`SslContextBuilder::set_tmp_dh`].
     ///
-    /// This corresponds to [`SSL_set_tmp_dh`].
-    ///
     /// [`SslContextBuilder::set_tmp_dh`]: struct.SslContextBuilder.html#method.set_tmp_dh
-    /// [`SSL_set_tmp_dh`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_set_tmp_dh.html
+    #[corresponds(SSL_set_tmp_dh)]
     pub fn set_tmp_dh(&mut self, dh: &DhRef<Params>) -> Result<(), ErrorStack> {
         unsafe { cvt(ffi::SSL_set_tmp_dh(self.as_ptr(), dh.as_ptr()) as c_int).map(|_| ()) }
     }
 
     /// Like [`SslContextBuilder::set_tmp_ecdh`].
     ///
-    /// This corresponds to `SSL_set_tmp_ecdh`.
-    ///
     /// [`SslContextBuilder::set_tmp_ecdh`]: struct.SslContextBuilder.html#method.set_tmp_ecdh
+    #[corresponds(SSL_set_tmp_ecdh)]
     pub fn set_tmp_ecdh(&mut self, key: &EcKeyRef<Params>) -> Result<(), ErrorStack> {
         unsafe { cvt(ffi::SSL_set_tmp_ecdh(self.as_ptr(), key.as_ptr()) as c_int).map(|_| ()) }
     }
@@ -3076,10 +2807,8 @@ impl SslRef {
 
     /// Like [`SslContextBuilder::set_alpn_protos`].
     ///
-    /// This corresponds to [`SSL_set_alpn_protos`].
-    ///
     /// [`SslContextBuilder::set_alpn_protos`]: struct.SslContextBuilder.html#method.set_alpn_protos
-    /// [`SSL_set_alpn_protos`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_set_alpn_protos.html
+    #[corresponds(SSL_set_alpn_protos)]
     pub fn set_alpn_protos(&mut self, protocols: &[u8]) -> Result<(), ErrorStack> {
         unsafe {
             #[cfg_attr(not(feature = "fips"), allow(clippy::unnecessary_cast))]
@@ -3101,10 +2830,7 @@ impl SslRef {
     }
 
     /// Returns the stack of available SslCiphers for `SSL`, sorted by preference.
-    ///
-    /// This corresponds to [`SSL_get_ciphers`].
-    ///
-    /// [`SSL_get_ciphers`]: https://www.openssl.org/docs/man1.0.2/man3/SSL_get_ciphers.html
+    #[corresponds(SSL_get_ciphers)]
     pub fn ciphers(&self) -> &StackRef<SslCipher> {
         unsafe {
             let cipher_list = ffi::SSL_get_ciphers(self.as_ptr());
@@ -3113,10 +2839,7 @@ impl SslRef {
     }
 
     /// Returns the current cipher if the session is active.
-    ///
-    /// This corresponds to [`SSL_get_current_cipher`].
-    ///
-    /// [`SSL_get_current_cipher`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_current_cipher.html
+    #[corresponds(SSL_get_current_cipher)]
     pub fn current_cipher(&self) -> Option<&SslCipherRef> {
         unsafe {
             let ptr = ffi::SSL_get_current_cipher(self.as_ptr());
@@ -3130,10 +2853,7 @@ impl SslRef {
     }
 
     /// Returns a short string describing the state of the session.
-    ///
-    /// This corresponds to [`SSL_state_string`].
-    ///
-    /// [`SSL_state_string`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_state_string.html
+    #[corresponds(SSL_state_string)]
     pub fn state_string(&self) -> &'static str {
         let state = unsafe {
             let ptr = ffi::SSL_state_string(self.as_ptr());
@@ -3144,10 +2864,7 @@ impl SslRef {
     }
 
     /// Returns a longer string describing the state of the session.
-    ///
-    /// This corresponds to [`SSL_state_string_long`].
-    ///
-    /// [`SSL_state_string_long`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_state_string_long.html
+    #[corresponds(SSL_state_string_long)]
     pub fn state_string_long(&self) -> &'static str {
         let state = unsafe {
             let ptr = ffi::SSL_state_string_long(self.as_ptr());
@@ -3160,10 +2877,7 @@ impl SslRef {
     /// Sets the host name to be sent to the server for Server Name Indication (SNI).
     ///
     /// It has no effect for a server-side connection.
-    ///
-    /// This corresponds to [`SSL_set_tlsext_host_name`].
-    ///
-    /// [`SSL_set_tlsext_host_name`]: https://www.openssl.org/docs/manmaster/man3/SSL_get_servername_type.html
+    #[corresponds(SSL_set_tlsext_host_name)]
     pub fn set_hostname(&mut self, hostname: &str) -> Result<(), ErrorStack> {
         let cstr = CString::new(hostname).unwrap();
         unsafe {
@@ -3173,10 +2887,7 @@ impl SslRef {
     }
 
     /// Returns the peer's certificate, if present.
-    ///
-    /// This corresponds to [`SSL_get_peer_certificate`].
-    ///
-    /// [`SSL_get_peer_certificate`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_peer_certificate.html
+    #[corresponds(SSL_get_peer_certificate)]
     pub fn peer_certificate(&self) -> Option<X509> {
         #[cfg(feature = "rpk")]
         assert!(
@@ -3198,10 +2909,7 @@ impl SslRef {
     ///
     /// On the client side, the chain includes the leaf certificate, but on the server side it does
     /// not. Fun!
-    ///
-    /// This corresponds to [`SSL_get_peer_cert_chain`].
-    ///
-    /// [`SSL_get_peer_cert_chain`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_peer_cert_chain.html
+    #[corresponds(SSL_get_peer_certificate)]
     pub fn peer_cert_chain(&self) -> Option<&StackRef<X509>> {
         #[cfg(feature = "rpk")]
         assert!(
@@ -3220,10 +2928,7 @@ impl SslRef {
     }
 
     /// Like [`SslContext::certificate`].
-    ///
-    /// This corresponds to `SSL_get_certificate`.
-    ///
-    /// [`SslContext::certificate`]: struct.SslContext.html#method.certificate
+    #[corresponds(SSL_get_certificate)]
     pub fn certificate(&self) -> Option<&X509Ref> {
         #[cfg(feature = "rpk")]
         assert!(
@@ -3242,10 +2947,7 @@ impl SslRef {
     }
 
     /// Like [`SslContext::private_key`].
-    ///
-    /// This corresponds to `SSL_get_privatekey`.
-    ///
-    /// [`SslContext::private_key`]: struct.SslContext.html#method.private_key
+    #[corresponds(SSL_get_privatekey)]
     pub fn private_key(&self) -> Option<&PKeyRef<Private>> {
         unsafe {
             let ptr = ffi::SSL_get_privatekey(self.as_ptr());
@@ -3263,10 +2965,7 @@ impl SslRef {
     }
 
     /// Returns the protocol version of the session.
-    ///
-    /// This corresponds to [`SSL_version`].
-    ///
-    /// [`SSL_version`]: https://www.openssl.org/docs/manmaster/man3/SSL_version.html
+    #[corresponds(SSL_version)]
     pub fn version2(&self) -> Option<SslVersion> {
         unsafe {
             let r = ffi::SSL_version(self.as_ptr());
@@ -3279,10 +2978,7 @@ impl SslRef {
     }
 
     /// Returns a string describing the protocol version of the session.
-    ///
-    /// This corresponds to [`SSL_get_version`].
-    ///
-    /// [`SSL_get_version`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_version.html
+    #[corresponds(SSL_get_version)]
     pub fn version_str(&self) -> &'static str {
         let version = unsafe {
             let ptr = ffi::SSL_get_version(self.as_ptr());
@@ -3296,10 +2992,7 @@ impl SslRef {
     ///
     /// If version is `None`, the default minimum version is used. For BoringSSL this defaults to
     /// TLS 1.0.
-    ///
-    /// This corresponds to [`SSL_set_min_proto_version`].
-    ///
-    /// [`SSL_set_min_proto_version`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_set_min_proto_version.html
+    #[corresponds(SSL_set_min_proto_version)]
     pub fn set_min_proto_version(&mut self, version: Option<SslVersion>) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::SSL_set_min_proto_version(
@@ -3313,10 +3006,7 @@ impl SslRef {
     /// Sets the maximum supported protocol version.
     ///
     /// If version is `None`, the default maximum version is used. For BoringSSL this is TLS 1.3.
-    ///
-    /// This corresponds to [`SSL_set_max_proto_version`].
-    ///
-    /// [`SSL_set_max_proto_version`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_set_max_proto_version.html
+    #[corresponds(SSL_set_max_proto_version)]
     pub fn set_max_proto_version(&mut self, version: Option<SslVersion>) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::SSL_set_max_proto_version(
@@ -3328,10 +3018,7 @@ impl SslRef {
     }
 
     /// Gets the minimum supported protocol version.
-    ///
-    /// This corresponds to [`SSL_get_min_proto_version`].
-    ///
-    /// [`SSL_get_min_proto_version`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_set_min_proto_version.html
+    #[corresponds(SSL_get_min_proto_version)]
     pub fn min_proto_version(&mut self) -> Option<SslVersion> {
         unsafe {
             let r = ffi::SSL_get_min_proto_version(self.as_ptr());
@@ -3344,10 +3031,7 @@ impl SslRef {
     }
 
     /// Gets the maximum supported protocol version.
-    ///
-    /// This corresponds to [`SSL_get_max_proto_version`].
-    ///
-    /// [`SSL_get_max_proto_version`]: https://www.openssl.org/docs/man3.1/man3/SSL_get_max_proto_version.html
+    #[corresponds(SSL_get_max_proto_version)]
     pub fn max_proto_version(&self) -> Option<SslVersion> {
         let r = unsafe { ffi::SSL_get_max_proto_version(self.as_ptr()) };
         if r == 0 {
@@ -3361,10 +3045,7 @@ impl SslRef {
     ///
     /// The protocol's name is returned is an opaque sequence of bytes. It is up to the client
     /// to interpret it.
-    ///
-    /// This corresponds to [`SSL_get0_alpn_selected`].
-    ///
-    /// [`SSL_get0_alpn_selected`]: https://www.openssl.org/docs/manmaster/man3/SSL_get0_next_proto_negotiated.html
+    #[corresponds(SSL_get0_alpn_selected)]
     pub fn selected_alpn_protocol(&self) -> Option<&[u8]> {
         unsafe {
             let mut data: *const c_uchar = ptr::null();
@@ -3382,10 +3063,7 @@ impl SslRef {
     }
 
     /// Enables the DTLS extension "use_srtp" as defined in RFC5764.
-    ///
-    /// This corresponds to [`SSL_set_tlsext_use_srtp`].
-    ///
-    /// [`SSL_set_tlsext_use_srtp`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_tlsext_use_srtp.html
+    #[corresponds(SSL_set_tlsext_use_srtp)]
     pub fn set_tlsext_use_srtp(&mut self, protocols: &str) -> Result<(), ErrorStack> {
         unsafe {
             let cstr = CString::new(protocols).unwrap();
@@ -3403,10 +3081,7 @@ impl SslRef {
     /// Gets all SRTP profiles that are enabled for handshake via set_tlsext_use_srtp
     ///
     /// DTLS extension "use_srtp" as defined in RFC5764 has to be enabled.
-    ///
-    /// This corresponds to [`SSL_get_srtp_profiles`].
-    ///
-    /// [`SSL_get_srtp_profiles`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_tlsext_use_srtp.html
+    #[corresponds(SSL_get_strp_profiles)]
     pub fn srtp_profiles(&self) -> Option<&StackRef<SrtpProtectionProfile>> {
         unsafe {
             let chain = ffi::SSL_get_srtp_profiles(self.as_ptr());
@@ -3422,10 +3097,7 @@ impl SslRef {
     /// Gets the SRTP profile selected by handshake.
     ///
     /// DTLS extension "use_srtp" as defined in RFC5764 has to be enabled.
-    ///
-    /// This corresponds to [`SSL_get_selected_srtp_profile`].
-    ///
-    /// [`SSL_get_selected_srtp_profile`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_tlsext_use_srtp.html
+    #[corresponds(SSL_get_selected_srtp_profile)]
     pub fn selected_srtp_profile(&self) -> Option<&SrtpProtectionProfileRef> {
         unsafe {
             let profile = ffi::SSL_get_selected_srtp_profile(self.as_ptr());
@@ -3442,10 +3114,7 @@ impl SslRef {
     ///
     /// If this is greater than 0, the next call to `read` will not call down to the underlying
     /// stream.
-    ///
-    /// This corresponds to [`SSL_pending`].
-    ///
-    /// [`SSL_pending`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_pending.html
+    #[corresponds(SSL_pending)]
     pub fn pending(&self) -> usize {
         unsafe { ffi::SSL_pending(self.as_ptr()) as usize }
     }
@@ -3454,8 +3123,6 @@ impl SslRef {
     ///
     /// It is only useful on the server side.
     ///
-    /// This corresponds to [`SSL_get_servername`].
-    ///
     /// # Note
     ///
     /// While the SNI specification requires that servernames be valid domain names (and therefore
@@ -3463,8 +3130,8 @@ impl SslRef {
     /// is not valid UTF-8, this function will return `None`. The `servername_raw` method returns
     /// the raw bytes and does not have this restriction.
     ///
-    /// [`SSL_get_servername`]: https://www.openssl.org/docs/manmaster/man3/SSL_get_servername.html
     // FIXME maybe rethink in 0.11?
+    #[corresponds(SSL_get_servername)]
     pub fn servername(&self, type_: NameType) -> Option<&str> {
         self.servername_raw(type_)
             .and_then(|b| str::from_utf8(b).ok())
@@ -3474,13 +3141,10 @@ impl SslRef {
     ///
     /// It is only useful on the server side.
     ///
-    /// This corresponds to [`SSL_get_servername`].
-    ///
     /// # Note
     ///
     /// Unlike `servername`, this method does not require the name be valid UTF-8.
-    ///
-    /// [`SSL_get_servername`]: https://www.openssl.org/docs/manmaster/man3/SSL_get_servername.html
+    #[corresponds(SSL_get_servername)]
     pub fn servername_raw(&self, type_: NameType) -> Option<&[u8]> {
         unsafe {
             let name = ffi::SSL_get_servername(self.as_ptr(), type_.0);
@@ -3495,17 +3159,13 @@ impl SslRef {
     /// Changes the context corresponding to the current connection.
     ///
     /// It is most commonly used in the Server Name Indication (SNI) callback.
-    ///
-    /// This corresponds to `SSL_set_SSL_CTX`.
+    #[corresponds(SSL_set_SSL_CTX)]
     pub fn set_ssl_context(&mut self, ctx: &SslContextRef) -> Result<(), ErrorStack> {
         unsafe { cvt_p(ffi::SSL_set_SSL_CTX(self.as_ptr(), ctx.as_ptr())).map(|_| ()) }
     }
 
     /// Returns the context corresponding to the current connection.
-    ///
-    /// This corresponds to [`SSL_get_SSL_CTX`].
-    ///
-    /// [`SSL_get_SSL_CTX`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_get_SSL_CTX.html
+    #[corresponds(SSL_get_SSL_CTX)]
     pub fn ssl_context(&self) -> &SslContextRef {
         unsafe {
             let ssl_ctx = ffi::SSL_get_SSL_CTX(self.as_ptr());
@@ -3514,10 +3174,7 @@ impl SslRef {
     }
 
     /// Returns a mutable reference to the X509 verification configuration.
-    ///
-    /// This corresponds to [`SSL_get0_param`].
-    ///
-    /// [`SSL_get0_param`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_get0_param.html
+    #[corresponds(SSL_get0_param)]
     pub fn verify_param_mut(&mut self) -> &mut X509VerifyParamRef {
         #[cfg(feature = "rpk")]
         assert!(
@@ -3534,10 +3191,7 @@ impl SslRef {
     }
 
     /// Returns the certificate verification result.
-    ///
-    /// This corresponds to [`SSL_get_verify_result`].
-    ///
-    /// [`SSL_get_verify_result`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_get_verify_result.html
+    #[corresponds(SSL_get_verify_result)]
     pub fn verify_result(&self) -> X509VerifyResult {
         #[cfg(feature = "rpk")]
         assert!(
@@ -3549,10 +3203,7 @@ impl SslRef {
     }
 
     /// Returns a shared reference to the SSL session.
-    ///
-    /// This corresponds to [`SSL_get_session`].
-    ///
-    /// [`SSL_get_session`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_session.html
+    #[corresponds(SSL_get_session)]
     pub fn session(&self) -> Option<&SslSessionRef> {
         unsafe {
             let p = ffi::SSL_get_session(self.as_ptr());
@@ -3568,10 +3219,7 @@ impl SslRef {
     ///
     /// Returns the number of bytes copied, or if the buffer is empty, the size of the client_random
     /// value.
-    ///
-    /// This corresponds to [`SSL_get_client_random`].
-    ///
-    /// [`SSL_get_client_random`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_client_random.html
+    #[corresponds(SSL_get_client_random)]
     pub fn client_random(&self, buf: &mut [u8]) -> usize {
         unsafe {
             ffi::SSL_get_client_random(self.as_ptr(), buf.as_mut_ptr() as *mut c_uchar, buf.len())
@@ -3582,10 +3230,7 @@ impl SslRef {
     ///
     /// Returns the number of bytes copied, or if the buffer is empty, the size of the server_random
     /// value.
-    ///
-    /// This corresponds to [`SSL_get_server_random`].
-    ///
-    /// [`SSL_get_server_random`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_client_random.html
+    #[corresponds(SSL_get_server_random)]
     pub fn server_random(&self, buf: &mut [u8]) -> usize {
         unsafe {
             ffi::SSL_get_server_random(self.as_ptr(), buf.as_mut_ptr() as *mut c_uchar, buf.len())
@@ -3593,10 +3238,7 @@ impl SslRef {
     }
 
     /// Derives keying material for application use in accordance to RFC 5705.
-    ///
-    /// This corresponds to [`SSL_export_keying_material`].
-    ///
-    /// [`SSL_export_keying_material`]: https://www.openssl.org/docs/manmaster/man3/SSL_export_keying_material.html
+    #[corresponds(SSL_export_keying_material)]
     pub fn export_keying_material(
         &self,
         out: &mut [u8],
@@ -3628,32 +3270,23 @@ impl SslRef {
     /// session. If the server is not willing to reuse the session, a new one will be transparently
     /// negotiated.
     ///
-    /// This corresponds to [`SSL_set_session`].
-    ///
     /// # Safety
     ///
     /// The caller of this method is responsible for ensuring that the session is associated
     /// with the same `SslContext` as this `Ssl`.
-    ///
-    /// [`SSL_set_session`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_session.html
+    #[corresponds(SSL_set_session)]
     pub unsafe fn set_session(&mut self, session: &SslSessionRef) -> Result<(), ErrorStack> {
         cvt(ffi::SSL_set_session(self.as_ptr(), session.as_ptr())).map(|_| ())
     }
 
     /// Determines if the session provided to `set_session` was successfully reused.
-    ///
-    /// This corresponds to [`SSL_session_reused`].
-    ///
-    /// [`SSL_session_reused`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_session_reused.html
+    #[corresponds(SSL_session_reused)]
     pub fn session_reused(&self) -> bool {
         unsafe { ffi::SSL_session_reused(self.as_ptr()) != 0 }
     }
 
     /// Sets the status response a client wishes the server to reply with.
-    ///
-    /// This corresponds to [`SSL_set_tlsext_status_type`].
-    ///
-    /// [`SSL_set_tlsext_status_type`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_set_tlsext_status_type.html
+    #[corresponds(SSL_set_tlsext_status_type)]
     pub fn set_status_type(&mut self, type_: StatusType) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::SSL_set_tlsext_status_type(self.as_ptr(), type_.as_raw()) as c_int).map(|_| ())
@@ -3661,10 +3294,7 @@ impl SslRef {
     }
 
     /// Returns the server's OCSP response, if present.
-    ///
-    /// This corresponds to [`SSL_get_tlsext_status_ocsp_resp`].
-    ///
-    /// [`SSL_get_tlsext_status_ocsp_resp`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_set_tlsext_status_type.html
+    #[corresponds(SSL_get_tlsext_status_ocsp_resp)]
     pub fn ocsp_status(&self) -> Option<&[u8]> {
         unsafe {
             let mut p = ptr::null();
@@ -3679,10 +3309,7 @@ impl SslRef {
     }
 
     /// Sets the OCSP response to be returned to the client.
-    ///
-    /// This corresponds to [`SSL_set_tlsext_status_ocsp_resp`].
-    ///
-    /// [`SSL_set_tlsext_status_ocsp_resp`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_set_tlsext_status_type.html
+    #[corresponds(SSL_set_tlsext_status_ocsp_resp)]
     pub fn set_ocsp_status(&mut self, response: &[u8]) -> Result<(), ErrorStack> {
         unsafe {
             assert!(response.len() <= c_int::MAX as usize);
@@ -3698,10 +3325,7 @@ impl SslRef {
     }
 
     /// Determines if this `Ssl` is configured for server-side or client-side use.
-    ///
-    /// This corresponds to [`SSL_is_server`].
-    ///
-    /// [`SSL_is_server`]: https://www.openssl.org/docs/manmaster/man3/SSL_is_server.html
+    #[corresponds(SSL_is_server)]
     pub fn is_server(&self) -> bool {
         unsafe { SSL_is_server(self.as_ptr()) != 0 }
     }
@@ -3711,12 +3335,9 @@ impl SslRef {
     /// This can be used to provide data to callbacks registered with the context. Use the
     /// `Ssl::new_ex_index` method to create an `Index`.
     ///
-    /// This corresponds to [`SSL_set_ex_data`].
-    ///
     /// Note that if this method is called multiple times with the same index, any previous
     /// value stored in the `SslContextBuilder` will be leaked.
-    ///
-    /// [`SSL_set_ex_data`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_ex_data.html
+    #[corresponds(SSL_set_ex_data)]
     pub fn set_ex_data<T>(&mut self, index: Index<Ssl, T>, data: T) {
         if let Some(old) = self.ex_data_mut(index) {
             *old = data;
@@ -3739,11 +3360,8 @@ impl SslRef {
     /// This can be used to provide data to callbacks registered with the context. Use the
     /// `Ssl::new_ex_index` method to create an `Index`.
     ///
-    /// This corresponds to [`SSL_set_ex_data`].
-    ///
     /// Any previous value will be dropped and replaced by the new one.
-    ///
-    /// [`SSL_set_ex_data`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_ex_data.html
+    #[corresponds(SSL_set_ex_data)]
     pub fn replace_ex_data<T>(&mut self, index: Index<Ssl, T>, data: T) -> Option<T> {
         if let Some(old) = self.ex_data_mut(index) {
             return Some(mem::replace(old, data));
@@ -3755,10 +3373,7 @@ impl SslRef {
     }
 
     /// Returns a reference to the extra data at the specified index.
-    ///
-    /// This corresponds to [`SSL_get_ex_data`].
-    ///
-    /// [`SSL_get_ex_data`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_ex_data.html
+    #[corresponds(SSL_get_ex_data)]
     pub fn ex_data<T>(&self, index: Index<Ssl, T>) -> Option<&T> {
         unsafe {
             let data = ffi::SSL_get_ex_data(self.as_ptr(), index.as_raw());
@@ -3771,10 +3386,7 @@ impl SslRef {
     }
 
     /// Returns a mutable reference to the extra data at the specified index.
-    ///
-    /// This corresponds to [`SSL_get_ex_data`].
-    ///
-    /// [`SSL_get_ex_data`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_ex_data.html
+    #[corresponds(SSL_get_ex_data)]
     pub fn ex_data_mut<T>(&mut self, index: Index<Ssl, T>) -> Option<&mut T> {
         unsafe {
             let data = ffi::SSL_get_ex_data(self.as_ptr(), index.as_raw());
@@ -3790,8 +3402,7 @@ impl SslRef {
     ///
     /// The total size of the message is returned, so this can be used to determine the size of the
     /// buffer required.
-    ///
-    /// This corresponds to `SSL_get_finished`.
+    #[corresponds(SSL_get_finished)]
     pub fn finished(&self, buf: &mut [u8]) -> usize {
         unsafe { ffi::SSL_get_finished(self.as_ptr(), buf.as_mut_ptr() as *mut c_void, buf.len()) }
     }
@@ -3801,8 +3412,7 @@ impl SslRef {
     ///
     /// The total size of the message is returned, so this can be used to determine the size of the
     /// buffer required.
-    ///
-    /// This corresponds to `SSL_get_peer_finished`.
+    #[corresponds(SSL_get_peer_finished)]
     pub fn peer_finished(&self, buf: &mut [u8]) -> usize {
         unsafe {
             ffi::SSL_get_peer_finished(self.as_ptr(), buf.as_mut_ptr() as *mut c_void, buf.len())
@@ -3810,26 +3420,19 @@ impl SslRef {
     }
 
     /// Determines if the initial handshake has been completed.
-    ///
-    /// This corresponds to [`SSL_is_init_finished`].
-    ///
-    /// [`SSL_is_init_finished`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_is_init_finished.html
+    #[corresponds(SSL_is_init_finished)]
     pub fn is_init_finished(&self) -> bool {
         unsafe { ffi::SSL_is_init_finished(self.as_ptr()) != 0 }
     }
 
     /// Sets the MTU used for DTLS connections.
-    ///
-    /// This corresponds to `SSL_set_mtu`.
+    #[corresponds(SSL_set_mtu)]
     pub fn set_mtu(&mut self, mtu: u32) -> Result<(), ErrorStack> {
         unsafe { cvt(ffi::SSL_set_mtu(self.as_ptr(), mtu as c_uint) as c_int).map(|_| ()) }
     }
 
     /// Sets the certificate.
-    ///
-    /// This corresponds to [`SSL_use_certificate`].
-    ///
-    /// [`SSL_use_certificate`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_use_certificate.html
+    #[corresponds(SSL_use_certificate)]
     pub fn set_certificate(&mut self, cert: &X509Ref) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::SSL_use_certificate(self.as_ptr(), cert.as_ptr()))?;
@@ -3842,10 +3445,7 @@ impl SslRef {
     ///
     /// The CA certificates must still be added to the trust root - they are not automatically set
     /// as trusted by this method.
-    ///
-    /// This corresponds to [`SSL_set_client_CA_list`].
-    ///
-    /// [`SSL_set_client_CA_list`]: https://docs.openssl.org/1.1.1/man3/SSL_CTX_set0_CA_list/
+    #[corresponds(SSL_set_client_CA_list)]
     pub fn set_client_ca_list(&mut self, list: Stack<X509Name>) {
         #[cfg(feature = "rpk")]
         assert!(
@@ -3858,10 +3458,7 @@ impl SslRef {
     }
 
     /// Sets the private key.
-    ///
-    /// This corresponds to [`SSL_use_PrivateKey`].
-    ///
-    /// [`SSL_use_PrivateKey`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_use_PrivateKey.html
+    #[corresponds(SSL_use_PrivateKey)]
     pub fn set_private_key<T>(&mut self, key: &PKeyRef<T>) -> Result<(), ErrorStack>
     where
         T: HasPrivate,
@@ -3871,10 +3468,7 @@ impl SslRef {
 
     /// Enables all modes set in `mode` in `SSL`. Returns a bitmask representing the resulting
     /// enabled modes.
-    ///
-    /// This corresponds to [`SSL_set_mode`].
-    ///
-    /// [`SSL_set_mode`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_set_mode.html
+    #[corresponds(SSL_set_mode)]
     pub fn set_mode(&mut self, mode: SslMode) -> SslMode {
         let bits = unsafe { ffi::SSL_set_mode(self.as_ptr(), mode.bits()) };
         SslMode::from_bits_retain(bits)
@@ -3882,20 +3476,14 @@ impl SslRef {
 
     /// Disables all modes set in `mode` in `SSL`. Returns a bitmask representing the resulting
     /// enabled modes.
-    ///
-    /// This corresponds to [`SSL_clear_mode`].
-    ///
-    /// [`SSL_clear_mode`]: https://www.openssl.org/docs/man3.1/man3/SSL_clear_mode.html
+    #[corresponds(SSL_clear_mode)]
     pub fn clear_mode(&mut self, mode: SslMode) -> SslMode {
         let bits = unsafe { ffi::SSL_clear_mode(self.as_ptr(), mode.bits()) };
         SslMode::from_bits_retain(bits)
     }
 
     /// Appends `cert` to the chain associated with the current certificate of `SSL`.
-    ///
-    /// This corresponds to [`SSL_add1_chain_cert`].
-    ///
-    /// [`SSL_add1_chain_cert`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_add1_chain_cert.html
+    #[corresponds(SSL_add1_chain_cert)]
     pub fn add_chain_cert(&mut self, cert: &X509Ref) -> Result<(), ErrorStack> {
         unsafe { cvt(ffi::SSL_add1_chain_cert(self.as_ptr(), cert.as_ptr())).map(|_| ()) }
     }
@@ -4060,10 +3648,7 @@ impl<S: Read + Write> SslStream<S> {
     ///
     /// It is particularly useful with a nonblocking socket, where the error value will identify if
     /// OpenSSL is waiting on read or write readiness.
-    ///
-    /// This corresponds to [`SSL_read`].
-    ///
-    /// [`SSL_read`]: https://www.openssl.org/docs/manmaster/man3/SSL_read.html
+    #[corresponds(SSL_read)]
     pub fn ssl_read(&mut self, buf: &mut [u8]) -> Result<usize, Error> {
         // SAFETY: `ssl_read_uninit` does not de-initialize the buffer.
         unsafe {
@@ -4098,10 +3683,7 @@ impl<S: Read + Write> SslStream<S> {
     ///
     /// It is particularly useful with a nonblocking socket, where the error value will identify if
     /// OpenSSL is waiting on read or write readiness.
-    ///
-    /// This corresponds to [`SSL_write`].
-    ///
-    /// [`SSL_write`]: https://www.openssl.org/docs/manmaster/man3/SSL_write.html
+    #[corresponds(SSL_write)]
     pub fn ssl_write(&mut self, buf: &[u8]) -> Result<usize, Error> {
         if buf.is_empty() {
             return Ok(0);
@@ -4125,10 +3707,7 @@ impl<S: Read + Write> SslStream<S> {
     /// While the connection may be closed after the first step, it is recommended to fully shut the
     /// session down. In particular, it must be fully shut down if the connection is to be used for
     /// further communication in the future.
-    ///
-    /// This corresponds to [`SSL_shutdown`].
-    ///
-    /// [`SSL_shutdown`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_shutdown.html
+    #[corresponds(SSL_shutdown)]
     pub fn shutdown(&mut self) -> Result<ShutdownResult, Error> {
         match unsafe { ffi::SSL_shutdown(self.ssl.as_ptr()) } {
             0 => Ok(ShutdownResult::Sent),
@@ -4138,10 +3717,7 @@ impl<S: Read + Write> SslStream<S> {
     }
 
     /// Returns the session's shutdown state.
-    ///
-    /// This corresponds to [`SSL_get_shutdown`].
-    ///
-    /// [`SSL_get_shutdown`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_set_shutdown.html
+    #[corresponds(SSL_get_shutdown)]
     pub fn get_shutdown(&mut self) -> ShutdownState {
         unsafe {
             let bits = ffi::SSL_get_shutdown(self.ssl.as_ptr());
@@ -4153,19 +3729,13 @@ impl<S: Read + Write> SslStream<S> {
     ///
     /// This can be used to tell OpenSSL that the session should be cached even if a full two-way
     /// shutdown was not completed.
-    ///
-    /// This corresponds to [`SSL_set_shutdown`].
-    ///
-    /// [`SSL_set_shutdown`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_set_shutdown.html
+    #[corresponds(SSL_set_shutdown)]
     pub fn set_shutdown(&mut self, state: ShutdownState) {
         unsafe { ffi::SSL_set_shutdown(self.ssl.as_ptr(), state.bits()) }
     }
 
     /// Initiates a client-side TLS handshake.
-    ///
-    /// This corresponds to [`SSL_connect`].
-    ///
-    /// [`SSL_connect`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_connect.html
+    #[corresponds(SSL_connect)]
     pub fn connect(&mut self) -> Result<(), Error> {
         let ret = unsafe { ffi::SSL_connect(self.ssl.as_ptr()) };
         if ret > 0 {
@@ -4176,10 +3746,7 @@ impl<S: Read + Write> SslStream<S> {
     }
 
     /// Initiates a server-side TLS handshake.
-    ///
-    /// This corresponds to [`SSL_accept`].
-    ///
-    /// [`SSL_accept`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_accept.html
+    #[corresponds(SSL_accept)]
     pub fn accept(&mut self) -> Result<(), Error> {
         let ret = unsafe { ffi::SSL_accept(self.ssl.as_ptr()) };
         if ret > 0 {
@@ -4190,10 +3757,7 @@ impl<S: Read + Write> SslStream<S> {
     }
 
     /// Initiates the handshake.
-    ///
-    /// This corresponds to [`SSL_do_handshake`].
-    ///
-    /// [`SSL_do_handshake`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_do_handshake.html
+    #[corresponds(SSL_do_handshake)]
     pub fn do_handshake(&mut self) -> Result<(), Error> {
         let ret = unsafe { ffi::SSL_do_handshake(self.ssl.as_ptr()) };
         if ret > 0 {
@@ -4326,19 +3890,13 @@ where
     }
 
     /// Configure as an outgoing stream from a client.
-    ///
-    /// This corresponds to [`SSL_set_connect_state`].
-    ///
-    /// [`SSL_set_connect_state`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_connect_state.html
+    #[corresponds(SSL_set_connect_state)]
     pub fn set_connect_state(&mut self) {
         unsafe { ffi::SSL_set_connect_state(self.inner.ssl.as_ptr()) }
     }
 
     /// Configure as an incoming stream to a server.
-    ///
-    /// This corresponds to [`SSL_set_accept_state`].
-    ///
-    /// [`SSL_set_accept_state`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_accept_state.html
+    #[corresponds(SSL_set_accept_state)]
     pub fn set_accept_state(&mut self) {
         unsafe { ffi::SSL_set_accept_state(self.inner.ssl.as_ptr()) }
     }
@@ -4408,10 +3966,7 @@ where
     /// Initiates the handshake.
     ///
     /// This will fail if `set_accept_state` or `set_connect_state` was not called first.
-    ///
-    /// This corresponds to [`SSL_do_handshake`].
-    ///
-    /// [`SSL_do_handshake`]: https://www.openssl.org/docs/manmaster/man3/SSL_do_handshake.html
+    #[corresponds(SSL_do_handshake)]
     pub fn handshake(self) -> Result<SslStream<S>, HandshakeError<S>> {
         let mut stream = self.inner;
         let ret = unsafe { ffi::SSL_do_handshake(stream.ssl.as_ptr()) };
diff --git a/boring/src/x509/mod.rs b/boring/src/x509/mod.rs
index eb55c305..a90a4934 100644
--- a/boring/src/x509/mod.rs
+++ b/boring/src/x509/mod.rs
@@ -9,6 +9,7 @@
 
 use foreign_types::{ForeignType, ForeignTypeRef};
 use libc::{c_int, c_long, c_void};
+use openssl_macros::corresponds;
 use std::convert::TryInto;
 use std::error::Error;
 use std::ffi::{CStr, CString};
@@ -58,15 +59,13 @@ foreign_type_and_impl_send_sync! {
 impl X509StoreContext {
     /// Returns the index which can be used to obtain a reference to the `Ssl` associated with a
     /// context.
+    #[corresponds(SSL_get_ex_data_X509_STORE_CTX_idx)]
     pub fn ssl_idx() -> Result<Index<X509StoreContext, SslRef>, ErrorStack> {
         unsafe { cvt_n(ffi::SSL_get_ex_data_X509_STORE_CTX_idx()).map(|idx| Index::from_raw(idx)) }
     }
 
     /// Creates a new `X509StoreContext` instance.
-    ///
-    /// This corresponds to [`X509_STORE_CTX_new`].
-    ///
-    /// [`X509_STORE_CTX_new`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_STORE_CTX_new.html
+    #[corresponds(X509_STORE_CTX_new)]
     pub fn new() -> Result<X509StoreContext, ErrorStack> {
         unsafe {
             ffi::init();
@@ -77,10 +76,7 @@ impl X509StoreContext {
 
 impl X509StoreContextRef {
     /// Returns application data pertaining to an `X509` store context.
-    ///
-    /// This corresponds to [`X509_STORE_CTX_get_ex_data`].
-    ///
-    /// [`X509_STORE_CTX_get_ex_data`]: https://www.openssl.org/docs/man1.0.2/crypto/X509_STORE_CTX_get_ex_data.html
+    #[corresponds(X509_STORE_CTX_get_ex_data)]
     pub fn ex_data<T>(&self, index: Index<X509StoreContext, T>) -> Option<&T> {
         unsafe {
             let data = ffi::X509_STORE_CTX_get_ex_data(self.as_ptr(), index.as_raw());
@@ -93,10 +89,7 @@ impl X509StoreContextRef {
     }
 
     /// Returns the verify result of the context.
-    ///
-    /// This corresponds to [`X509_STORE_CTX_get_error`].
-    ///
-    /// [`X509_STORE_CTX_get_error`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_STORE_CTX_get_error.html
+    #[corresponds(X509_STORE_CTX_get_error)]
     pub fn verify_result(&self) -> X509VerifyResult {
         unsafe { X509VerifyError::from_raw(ffi::X509_STORE_CTX_get_error(self.as_ptr())) }
     }
@@ -150,10 +143,7 @@ impl X509StoreContextRef {
     }
 
     /// Returns a mutable reference to the X509 verification configuration.
-    ///
-    /// This corresponds to [`X509_STORE_CTX_get0_param`].
-    ///
-    /// [`SSL_get0_param`]: https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_get0_param.html
+    #[corresponds(X509_STORE_CTX_get0_param)]
     pub fn verify_param_mut(&mut self) -> &mut X509VerifyParamRef {
         unsafe { X509VerifyParamRef::from_ptr_mut(ffi::X509_STORE_CTX_get0_param(self.as_ptr())) }
     }
@@ -164,19 +154,13 @@ impl X509StoreContextRef {
     /// validation error if the certificate was not valid.
     ///
     /// This will only work inside of a call to `init`.
-    ///
-    /// This corresponds to [`X509_verify_cert`].
-    ///
-    /// [`X509_verify_cert`]:  https://www.openssl.org/docs/man1.0.2/crypto/X509_verify_cert.html
+    #[corresponds(X509_verify_cert)]
     pub fn verify_cert(&mut self) -> Result<bool, ErrorStack> {
         unsafe { cvt_n(ffi::X509_verify_cert(self.as_ptr())).map(|n| n != 0) }
     }
 
     /// Set the verify result of the context.
-    ///
-    /// This corresponds to [`X509_STORE_CTX_set_error`].
-    ///
-    /// [`X509_STORE_CTX_set_error`]:  https://www.openssl.org/docs/man1.1.0/crypto/X509_STORE_CTX_set_error.html
+    #[corresponds(X509_STORE_CTX_set_error)]
     pub fn set_error(&mut self, result: X509VerifyResult) {
         unsafe {
             ffi::X509_STORE_CTX_set_error(
@@ -191,10 +175,7 @@ impl X509StoreContextRef {
 
     /// Returns a reference to the certificate which caused the error or None if
     /// no certificate is relevant to the error.
-    ///
-    /// This corresponds to [`X509_STORE_CTX_get_current_cert`].
-    ///
-    /// [`X509_STORE_CTX_get_current_cert`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_STORE_CTX_get_current_cert.html
+    #[corresponds(X509_STORE_CTX_get_current_cert)]
     pub fn current_cert(&self) -> Option<&X509Ref> {
         unsafe {
             let ptr = ffi::X509_STORE_CTX_get_current_cert(self.as_ptr());
@@ -210,19 +191,13 @@ impl X509StoreContextRef {
     /// chain where the error occurred. If it is zero it occurred in the end
     /// entity certificate, one if it is the certificate which signed the end
     /// entity certificate and so on.
-    ///
-    /// This corresponds to [`X509_STORE_CTX_get_error_depth`].
-    ///
-    /// [`X509_STORE_CTX_get_error_depth`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_STORE_CTX_get_error_depth.html
+    #[corresponds(X509_STORE_CTX_get_error_depth)]
     pub fn error_depth(&self) -> u32 {
         unsafe { ffi::X509_STORE_CTX_get_error_depth(self.as_ptr()) as u32 }
     }
 
     /// Returns a reference to a complete valid `X509` certificate chain.
-    ///
-    /// This corresponds to [`X509_STORE_CTX_get0_chain`].
-    ///
-    /// [`X509_STORE_CTX_get0_chain`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_STORE_CTX_get0_chain.html
+    #[corresponds(X509_STORE_CTX_get0_chain)]
     pub fn chain(&self) -> Option<&StackRef<X509>> {
         unsafe {
             let chain = X509_STORE_CTX_get0_chain(self.as_ptr());
@@ -241,6 +216,7 @@ pub struct X509Builder(X509);
 
 impl X509Builder {
     /// Creates a new builder.
+    #[corresponds(X509_new)]
     pub fn new() -> Result<X509Builder, ErrorStack> {
         unsafe {
             ffi::init();
@@ -249,11 +225,13 @@ impl X509Builder {
     }
 
     /// Sets the notAfter constraint on the certificate.
+    #[corresponds(X509_set1_notAfter)]
     pub fn set_not_after(&mut self, not_after: &Asn1TimeRef) -> Result<(), ErrorStack> {
         unsafe { cvt(X509_set1_notAfter(self.0.as_ptr(), not_after.as_ptr())).map(|_| ()) }
     }
 
     /// Sets the notBefore constraint on the certificate.
+    #[corresponds(X509_set1_notBefore)]
     pub fn set_not_before(&mut self, not_before: &Asn1TimeRef) -> Result<(), ErrorStack> {
         unsafe { cvt(X509_set1_notBefore(self.0.as_ptr(), not_before.as_ptr())).map(|_| ()) }
     }
@@ -262,11 +240,13 @@ impl X509Builder {
     ///
     /// Note that the version is zero-indexed; that is, a certificate corresponding to version 3 of
     /// the X.509 standard should pass `2` to this method.
+    #[corresponds(X509_set_version)]
     pub fn set_version(&mut self, version: i32) -> Result<(), ErrorStack> {
         unsafe { cvt(ffi::X509_set_version(self.0.as_ptr(), version.into())).map(|_| ()) }
     }
 
     /// Sets the serial number of the certificate.
+    #[corresponds(X509_set_serialNumber)]
     pub fn set_serial_number(&mut self, serial_number: &Asn1IntegerRef) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::X509_set_serialNumber(
@@ -278,6 +258,7 @@ impl X509Builder {
     }
 
     /// Sets the issuer name of the certificate.
+    #[corresponds(X509_set_issuer_name)]
     pub fn set_issuer_name(&mut self, issuer_name: &X509NameRef) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::X509_set_issuer_name(
@@ -306,6 +287,7 @@ impl X509Builder {
     /// let mut x509 = boring::x509::X509::builder().unwrap();
     /// x509.set_subject_name(&x509_name).unwrap();
     /// ```
+    #[corresponds(X509_set_subject_name)]
     pub fn set_subject_name(&mut self, subject_name: &X509NameRef) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::X509_set_subject_name(
@@ -317,6 +299,7 @@ impl X509Builder {
     }
 
     /// Sets the public key associated with the certificate.
+    #[corresponds(X509_set_pubkey)]
     pub fn set_pubkey<T>(&mut self, key: &PKeyRef<T>) -> Result<(), ErrorStack>
     where
         T: HasPublic,
@@ -327,6 +310,7 @@ impl X509Builder {
     /// Returns a context object which is needed to create certain X509 extension values.
     ///
     /// Set `issuer` to `None` if the certificate will be self-signed.
+    #[corresponds(X509V3_set_ctx)]
     pub fn x509v3_context<'a>(
         &'a self,
         issuer: Option<&'a X509Ref>,
@@ -366,10 +350,7 @@ impl X509Builder {
     }
 
     /// Adds an X509 extension value to the certificate.
-    ///
-    /// This corresponds to [`X509_add_ext`].
-    ///
-    /// [`X509_add_ext`]: https://www.openssl.org/docs/man1.1.0/man3/X509_get_ext.html
+    #[corresponds(X509_add_ext)]
     pub fn append_extension2(&mut self, extension: &X509ExtensionRef) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::X509_add_ext(self.0.as_ptr(), extension.as_ptr(), -1))?;
@@ -378,6 +359,7 @@ impl X509Builder {
     }
 
     /// Signs the certificate with a private key.
+    #[corresponds(X509_sign)]
     pub fn sign<T>(&mut self, key: &PKeyRef<T>, hash: MessageDigest) -> Result<(), ErrorStack>
     where
         T: HasPrivate,
@@ -401,10 +383,7 @@ foreign_type_and_impl_send_sync! {
 
 impl X509Ref {
     /// Returns this certificate's subject name.
-    ///
-    /// This corresponds to [`X509_get_subject_name`].
-    ///
-    /// [`X509_get_subject_name`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_get_subject_name.html
+    #[corresponds(X509_get_subject_name)]
     pub fn subject_name(&self) -> &X509NameRef {
         unsafe {
             let name = ffi::X509_get_subject_name(self.as_ptr());
@@ -413,17 +392,13 @@ impl X509Ref {
     }
 
     /// Returns the hash of the certificates subject
-    ///
-    /// This corresponds to `X509_subject_name_hash`.
+    #[corresponds(X509_subject_name_hash)]
     pub fn subject_name_hash(&self) -> u32 {
         unsafe { ffi::X509_subject_name_hash(self.as_ptr()) as u32 }
     }
 
     /// Returns this certificate's subject alternative name entries, if they exist.
-    ///
-    /// This corresponds to [`X509_get_ext_d2i`] called with `NID_subject_alt_name`.
-    ///
-    /// [`X509_get_ext_d2i`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_get_ext_d2i.html
+    #[corresponds(X509_get_ext_d2i)]
     pub fn subject_alt_names(&self) -> Option<Stack<GeneralName>> {
         unsafe {
             let stack = ffi::X509_get_ext_d2i(
@@ -450,10 +425,7 @@ impl X509Ref {
     }
 
     /// Returns this certificate's issuer alternative name entries, if they exist.
-    ///
-    /// This corresponds to [`X509_get_ext_d2i`] called with `NID_issuer_alt_name`.
-    ///
-    /// [`X509_get_ext_d2i`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_get_ext_d2i.html
+    #[corresponds(X509_get_ext_d2i)]
     pub fn issuer_alt_names(&self) -> Option<Stack<GeneralName>> {
         unsafe {
             let stack = ffi::X509_get_ext_d2i(
@@ -471,6 +443,7 @@ impl X509Ref {
     }
 
     /// Returns this certificate's subject key id, if it exists.
+    #[corresponds(X509_get0_subject_key_id)]
     pub fn subject_key_id(&self) -> Option<&Asn1StringRef> {
         unsafe {
             let data = ffi::X509_get0_subject_key_id(self.as_ptr());
@@ -479,6 +452,7 @@ impl X509Ref {
     }
 
     /// Returns this certificate's authority key id, if it exists.
+    #[corresponds(X509_get0_authority_key_id)]
     pub fn authority_key_id(&self) -> Option<&Asn1StringRef> {
         unsafe {
             let data = ffi::X509_get0_authority_key_id(self.as_ptr());

From 786ee180cd88787849dec390c8946c3de8b6d97c Mon Sep 17 00:00:00 2001
From: Rushil Mehra <rmehra@cloudflare.com>
Date: Tue, 13 Aug 2024 17:35:43 -0700
Subject: [PATCH 4/6] Expose X509NameRef::print_ex

---
 boring/src/x509/mod.rs | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/boring/src/x509/mod.rs b/boring/src/x509/mod.rs
index a90a4934..b234bd2b 100644
--- a/boring/src/x509/mod.rs
+++ b/boring/src/x509/mod.rs
@@ -26,7 +26,7 @@ use crate::asn1::{
     Asn1BitStringRef, Asn1IntegerRef, Asn1Object, Asn1ObjectRef, Asn1StringRef, Asn1TimeRef,
     Asn1Type,
 };
-use crate::bio::MemBioSlice;
+use crate::bio::{MemBio, MemBioSlice};
 use crate::conf::ConfRef;
 use crate::error::ErrorStack;
 use crate::ex_data::Index;
@@ -1044,6 +1044,20 @@ impl X509NameRef {
         }
     }
 
+    /// Returns an owned String representing the X509 name configurable via incoming flags.
+    ///
+    /// This function will return `None` if the underlying string contains invalid utf-8.
+    #[corresponds(X509_NAME_print_ex)]
+    pub fn print_ex(&self, flags: i32) -> Option<String> {
+        unsafe {
+            let bio = MemBio::new().ok()?;
+            ffi::X509_NAME_print_ex(bio.as_ptr(), self.as_ptr(), 0, flags as _);
+            let buf = bio.get_buf().to_vec();
+            let res = String::from_utf8(buf);
+            res.ok()
+        }
+    }
+
     to_der! {
         /// Serializes the certificate into a DER-encoded X509 name structure.
         ///

From 2b51e297320de97fc4f62f2fe2783dcaaec5fbc4 Mon Sep 17 00:00:00 2001
From: Rushil Mehra <rmehra@cloudflare.com>
Date: Thu, 15 Aug 2024 13:42:12 -0700
Subject: [PATCH 5/6] Add tests for X509Ref::subject_key_id,
 X509Ref::authority_key_id, and X509NameRef::print_ex

---
 boring/src/x509/tests/mod.rs | 43 ++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/boring/src/x509/tests/mod.rs b/boring/src/x509/tests/mod.rs
index 65bb7f90..b3867ce2 100644
--- a/boring/src/x509/tests/mod.rs
+++ b/boring/src/x509/tests/mod.rs
@@ -179,6 +179,49 @@ fn test_subject_alt_name_iter() {
     assert!(subject_alt_names_iter.next().is_none());
 }
 
+#[test]
+fn test_subject_key_id() {
+    // nid_test_cert_pem has SKI, but no AKI
+    let cert = include_bytes!("../../../test/nid_test_cert.pem");
+    let cert = X509::from_pem(cert).unwrap();
+
+    let ski = cert.subject_key_id().expect("unable to extract SKI");
+    assert_eq!(
+        ski.as_slice(),
+        [
+            80, 107, 158, 237, 95, 61, 235, 100, 212, 115, 249, 244, 219, 163, 124, 55, 141, 2, 76,
+            5
+        ]
+    );
+
+    let aki = cert.authority_key_id();
+    assert!(aki.is_none());
+}
+
+#[test]
+fn test_x509_name_print_ex() {
+    let cert = include_bytes!("../../../test/cert.pem");
+    let cert = X509::from_pem(cert).unwrap();
+
+    let name_no_flags = cert
+        .subject_name()
+        .print_ex(0)
+        .expect("failed to print cert subject name");
+    assert_eq!(
+        name_no_flags,
+        "C=AU, ST=Some-State, O=Internet Widgits Pty Ltd, CN=foobar.com"
+    );
+
+    let name_rfc2253 = cert
+        .subject_name()
+        .print_ex(ffi::XN_FLAG_RFC2253)
+        .expect("failed to print cert subject name");
+    assert_eq!(
+        name_rfc2253,
+        "CN=foobar.com,O=Internet Widgits Pty Ltd,ST=Some-State,C=AU"
+    );
+}
+
 #[test]
 fn x509_builder() {
     let pkey = pkey();

From b2c1e4c9dcda9ec44303ab614a46f8632d125bcf Mon Sep 17 00:00:00 2001
From: Rushil Mehra <rmehra@cloudflare.com>
Date: Thu, 15 Aug 2024 13:42:28 -0700
Subject: [PATCH 6/6] Fix macos FIPS crossbuild

---
 .github/workflows/ci.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cb68529c..fb3c07cb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -322,7 +322,8 @@ jobs:
       working-directory: ${{ runner.temp }}/llvm/bin
       run: ln -s clang clang++-12
     - name: Install ${{ matrix.target }} toolchain
-      run: brew tap messense/macos-cross-toolchains && brew install --overwrite python@3.11 && brew install ${{ matrix.target }}
+      # TODO(rmehra): find a better way to overwrite the python3 version without specifying version
+      run: brew tap messense/macos-cross-toolchains && brew install --overwrite python@3.12 && brew install ${{ matrix.target }}
     - name: Set BORING_BSSL_FIPS_COMPILER_EXTERNAL_TOOLCHAIN
       run: echo "BORING_BSSL_FIPS_COMPILER_EXTERNAL_TOOLCHAIN=$(brew --prefix ${{ matrix.target }})/toolchain" >> $GITHUB_ENV
       shell: bash