Merge pull request #2282 from rushilmehra/update-docs

Update some docs to use the corresponds macro

Author: sfackler

openssl/src/cipher_ctx.rs

@@ -328,10 +328,6 @@ impl CipherCtxRef {
     ///
     /// Panics if the context has not been initialized with a cipher or if the buffer is smaller than the cipher's key
     /// length.
-    ///
-    /// This corresponds to [`EVP_CIPHER_CTX_rand_key`].
-    ///
-    /// [`EVP_CIPHER_CTX_rand_key`]: https://www.openssl.org/docs/manmaster/man3/EVP_CIPHER_CTX_rand_key.html
     #[corresponds(EVP_CIPHER_CTX_rand_key)]
     #[cfg(not(boringssl))]
     pub fn rand_key(&self, buf: &mut [u8]) -> Result<(), ErrorStack> {

openssl/src/hash.rs

@@ -41,6 +41,7 @@ use std::ptr;
 use crate::error::ErrorStack;
 use crate::nid::Nid;
 use crate::{cvt, cvt_p};
+use openssl_macros::corresponds;
 
 cfg_if! {
     if #[cfg(any(ossl110, boringssl, libressl382))] {
@@ -65,10 +66,7 @@ impl MessageDigest {
     }
 
     /// Returns the `MessageDigest` corresponding to an `Nid`.
-    ///
-    /// This corresponds to [`EVP_get_digestbynid`].
-    ///
-    /// [`EVP_get_digestbynid`]: https://www.openssl.org/docs/manmaster/crypto/EVP_DigestInit.html
+    #[corresponds(EVP_get_digestbynid)]
     pub fn from_nid(type_: Nid) -> Option<MessageDigest> {
         ffi::init();
         unsafe {
@@ -82,10 +80,7 @@ impl MessageDigest {
     }
 
     /// Returns the `MessageDigest` corresponding to an algorithm name.
-    ///
-    /// This corresponds to [`EVP_get_digestbyname`].
-    ///
-    /// [`EVP_get_digestbyname`]: https://www.openssl.org/docs/manmaster/crypto/EVP_DigestInit.html
+    #[corresponds(EVP_get_digestbyname)]
     pub fn from_name(name: &str) -> Option<MessageDigest> {
         ffi::init();
         let name = CString::new(name).ok()?;

openssl/src/nid.rs

@@ -79,8 +79,6 @@ impl Nid {
     }
 
     /// Returns the `Nid`s of the digest and public key algorithms associated with a signature ID.
-    ///
-    /// This corresponds to `OBJ_find_sigid_algs`.
     #[corresponds(OBJ_find_sigid_algs)]
     #[allow(clippy::trivially_copy_pass_by_ref)]
     pub fn signature_algorithms(&self) -> Option<SignatureAlgorithms> {

openssl/src/sign.rs

@@ -79,6 +79,7 @@ use crate::hash::MessageDigest;
 use crate::pkey::{HasPrivate, HasPublic, PKeyRef};
 use crate::rsa::Padding;
 use crate::{cvt, cvt_p};
+use openssl_macros::corresponds;
 
 cfg_if! {
     if #[cfg(any(ossl110, libressl382))] {
@@ -135,10 +136,7 @@ impl Signer<'_> {
     ///
     /// This cannot be used with Ed25519 or Ed448 keys. Please refer to
     /// `new_without_digest`.
-    ///
-    /// OpenSSL documentation at [`EVP_DigestSignInit`].
-    ///
-    /// [`EVP_DigestSignInit`]: https://www.openssl.org/docs/manmaster/man3/EVP_DigestSignInit.html
+    #[corresponds(EVP_DigestSignInit)]
     pub fn new<'a, T>(type_: MessageDigest, pkey: &PKeyRef<T>) -> Result<Signer<'a>, ErrorStack>
     where
         T: HasPrivate,
@@ -150,10 +148,7 @@ impl Signer<'_> {
     ///
     /// This is the only way to create a `Verifier` for Ed25519 or Ed448 keys.
     /// It can also be used to create a CMAC.
-    ///
-    /// OpenSSL documentation at [`EVP_DigestSignInit`].
-    ///
-    /// [`EVP_DigestSignInit`]: https://www.openssl.org/docs/manmaster/man3/EVP_DigestSignInit.html
+    #[corresponds(EVP_DigestSignInit)]
     pub fn new_without_digest<'a, T>(pkey: &PKeyRef<T>) -> Result<Signer<'a>, ErrorStack>
     where
         T: HasPrivate,
@@ -198,8 +193,7 @@ impl Signer<'_> {
     /// Returns the RSA padding mode in use.
     ///
     /// This is only useful for RSA keys.
-    ///
-    /// This corresponds to `EVP_PKEY_CTX_get_rsa_padding`.
+    #[corresponds(EVP_PKEY_CTX_get_rsa_padding)]
     pub fn rsa_padding(&self) -> Result<Padding, ErrorStack> {
         unsafe {
             let mut pad = 0;
@@ -211,10 +205,7 @@ impl Signer<'_> {
     /// Sets the RSA padding mode.
     ///
     /// This is only useful for RSA keys.
-    ///
-    /// This corresponds to [`EVP_PKEY_CTX_set_rsa_padding`].
-    ///
-    /// [`EVP_PKEY_CTX_set_rsa_padding`]: https://www.openssl.org/docs/manmaster/crypto/EVP_PKEY_CTX_set_rsa_padding.html
+    #[corresponds(EVP_PKEY_CTX_set_rsa_padding)]
     pub fn set_rsa_padding(&mut self, padding: Padding) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::EVP_PKEY_CTX_set_rsa_padding(
@@ -228,10 +219,7 @@ impl Signer<'_> {
     /// Sets the RSA PSS salt length.
     ///
     /// This is only useful for RSA keys.
-    ///
-    /// This corresponds to [`EVP_PKEY_CTX_set_rsa_pss_saltlen`].
-    ///
-    /// [`EVP_PKEY_CTX_set_rsa_pss_saltlen`]: https://www.openssl.org/docs/manmaster/crypto/EVP_PKEY_CTX_set_rsa_pss_saltlen.html
+    #[corresponds(EVP_PKEY_CTX_set_rsa_pss_saltlen)]
     pub fn set_rsa_pss_saltlen(&mut self, len: RsaPssSaltlen) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::EVP_PKEY_CTX_set_rsa_pss_saltlen(
@@ -245,10 +233,7 @@ impl Signer<'_> {
     /// Sets the RSA MGF1 algorithm.
     ///
     /// This is only useful for RSA keys.
-    ///
-    /// This corresponds to [`EVP_PKEY_CTX_set_rsa_mgf1_md`].
-    ///
-    /// [`EVP_PKEY_CTX_set_rsa_mgf1_md`]: https://www.openssl.org/docs/manmaster/man7/RSA-PSS.html
+    #[corresponds(EVP_PKEY_CTX_set_rsa_mgf1_md)]
     pub fn set_rsa_mgf1_md(&mut self, md: MessageDigest) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::EVP_PKEY_CTX_set_rsa_mgf1_md(
@@ -263,10 +248,7 @@ impl Signer<'_> {
     ///
     /// Please note that PureEdDSA (Ed25519 and Ed448 keys) do not support streaming.
     /// Use `sign_oneshot` instead.
-    ///
-    /// OpenSSL documentation at [`EVP_DigestUpdate`].
-    ///
-    /// [`EVP_DigestUpdate`]: https://www.openssl.org/docs/manmaster/man3/EVP_DigestInit.html
+    #[corresponds(EVP_DigestUpdate)]
     pub fn update(&mut self, buf: &[u8]) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::EVP_DigestUpdate(
@@ -282,10 +264,7 @@ impl Signer<'_> {
     ///
     /// The actual signature may be shorter than this value. Check the return value of
     /// `sign` to get the exact length.
-    ///
-    /// OpenSSL documentation at [`EVP_DigestSignFinal`].
-    ///
-    /// [`EVP_DigestSignFinal`]: https://www.openssl.org/docs/manmaster/crypto/EVP_DigestSignFinal.html
+    #[corresponds(EVP_DigestSignFinal)]
     pub fn len(&self) -> Result<usize, ErrorStack> {
         self.len_intern()
     }
@@ -322,10 +301,7 @@ impl Signer<'_> {
     ///
     /// This method will fail if the buffer is not large enough for the signature. Use the `len`
     /// method to get an upper bound on the required size.
-    ///
-    /// OpenSSL documentation at [`EVP_DigestSignFinal`].
-    ///
-    /// [`EVP_DigestSignFinal`]: https://www.openssl.org/docs/manmaster/crypto/EVP_DigestSignFinal.html
+    #[corresponds(EVP_DigestSignFinal)]
     pub fn sign(&self, buf: &mut [u8]) -> Result<usize, ErrorStack> {
         unsafe {
             let mut len = buf.len();
@@ -356,10 +332,7 @@ impl Signer<'_> {
     ///
     /// This method will fail if the buffer is not large enough for the signature. Use the `len`
     /// method to get an upper bound on the required size.
-    ///
-    /// OpenSSL documentation at [`EVP_DigestSign`].
-    ///
-    /// [`EVP_DigestSign`]: https://www.openssl.org/docs/man1.1.1/man3/EVP_DigestSign.html
+    #[corresponds(EVP_DigestSign)]
     #[cfg(any(ossl111, boringssl, libressl370))]
     pub fn sign_oneshot(
         &mut self,
@@ -429,10 +402,7 @@ impl<'a> Verifier<'a> {
     ///
     /// This cannot be used with Ed25519 or Ed448 keys. Please refer to
     /// [`Verifier::new_without_digest`].
-    ///
-    /// OpenSSL documentation at [`EVP_DigestVerifyInit`].
-    ///
-    /// [`EVP_DigestVerifyInit`]: https://www.openssl.org/docs/manmaster/man3/EVP_DigestVerifyInit.html
+    #[corresponds(EVP_DigestVerifyInit)]
     pub fn new<T>(type_: MessageDigest, pkey: &'a PKeyRef<T>) -> Result<Verifier<'a>, ErrorStack>
     where
         T: HasPublic,
@@ -443,10 +413,7 @@ impl<'a> Verifier<'a> {
     /// Creates a new `Verifier` without a digest.
     ///
     /// This is the only way to create a `Verifier` for Ed25519 or Ed448 keys.
-    ///
-    /// OpenSSL documentation at [`EVP_DigestVerifyInit`].
-    ///
-    /// [`EVP_DigestVerifyInit`]: https://www.openssl.org/docs/manmaster/man3/EVP_DigestVerifyInit.html
+    #[corresponds(EVP_DigestVerifyInit)]
     pub fn new_without_digest<T>(pkey: &'a PKeyRef<T>) -> Result<Verifier<'a>, ErrorStack>
     where
         T: HasPublic,
@@ -491,8 +458,7 @@ impl<'a> Verifier<'a> {
     /// Returns the RSA padding mode in use.
     ///
     /// This is only useful for RSA keys.
-    ///
-    /// This corresponds to `EVP_PKEY_CTX_get_rsa_padding`.
+    #[corresponds(EVP_PKEY_CTX_get_rsa_padding)]
     pub fn rsa_padding(&self) -> Result<Padding, ErrorStack> {
         unsafe {
             let mut pad = 0;
@@ -504,10 +470,7 @@ impl<'a> Verifier<'a> {
     /// Sets the RSA padding mode.
     ///
     /// This is only useful for RSA keys.
-    ///
-    /// This corresponds to [`EVP_PKEY_CTX_set_rsa_padding`].
-    ///
-    /// [`EVP_PKEY_CTX_set_rsa_padding`]: https://www.openssl.org/docs/manmaster/crypto/EVP_PKEY_CTX_set_rsa_padding.html
+    #[corresponds(EVP_PKEY_CTX_set_rsa_padding)]
     pub fn set_rsa_padding(&mut self, padding: Padding) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::EVP_PKEY_CTX_set_rsa_padding(
@@ -521,10 +484,7 @@ impl<'a> Verifier<'a> {
     /// Sets the RSA PSS salt length.
     ///
     /// This is only useful for RSA keys.
-    ///
-    /// This corresponds to [`EVP_PKEY_CTX_set_rsa_pss_saltlen`].
-    ///
-    /// [`EVP_PKEY_CTX_set_rsa_pss_saltlen`]: https://www.openssl.org/docs/manmaster/crypto/EVP_PKEY_CTX_set_rsa_pss_saltlen.html
+    #[corresponds(EVP_PKEY_CTX_set_rsa_pss_saltlen)]
     pub fn set_rsa_pss_saltlen(&mut self, len: RsaPssSaltlen) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::EVP_PKEY_CTX_set_rsa_pss_saltlen(
@@ -538,10 +498,7 @@ impl<'a> Verifier<'a> {
     /// Sets the RSA MGF1 algorithm.
     ///
     /// This is only useful for RSA keys.
-    ///
-    /// This corresponds to [`EVP_PKEY_CTX_set_rsa_mgf1_md`].
-    ///
-    /// [`EVP_PKEY_CTX_set_rsa_mgf1_md`]: https://www.openssl.org/docs/manmaster/man7/RSA-PSS.html
+    #[corresponds(EVP_PKEY_CTX_set_rsa_mgf1_md)]
     pub fn set_rsa_mgf1_md(&mut self, md: MessageDigest) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::EVP_PKEY_CTX_set_rsa_mgf1_md(
@@ -556,10 +513,7 @@ impl<'a> Verifier<'a> {
     ///
     /// Please note that PureEdDSA (Ed25519 and Ed448 keys) do not support streaming.
     /// Use [`Verifier::verify_oneshot`] instead.
-    ///
-    /// OpenSSL documentation at [`EVP_DigestUpdate`].
-    ///
-    /// [`EVP_DigestUpdate`]: https://www.openssl.org/docs/manmaster/man3/EVP_DigestInit.html
+    #[corresponds(EVP_DigestUpdate)]
     pub fn update(&mut self, buf: &[u8]) -> Result<(), ErrorStack> {
         unsafe {
             cvt(ffi::EVP_DigestUpdate(
@@ -572,10 +526,7 @@ impl<'a> Verifier<'a> {
     }
 
     /// Determines if the data fed into the `Verifier` matches the provided signature.
-    ///
-    /// OpenSSL documentation at [`EVP_DigestVerifyFinal`].
-    ///
-    /// [`EVP_DigestVerifyFinal`]: https://www.openssl.org/docs/manmaster/man3/EVP_DigestVerifyFinal.html
+    #[corresponds(EVP_DigestVerifyFinal)]
     pub fn verify(&self, signature: &[u8]) -> Result<bool, ErrorStack> {
         unsafe {
             let r =
@@ -592,10 +543,7 @@ impl<'a> Verifier<'a> {
     }
 
     /// Determines if the data given in `buf` matches the provided signature.
-    ///
-    /// OpenSSL documentation at [`EVP_DigestVerify`].
-    ///
-    /// [`EVP_DigestVerify`]: https://www.openssl.org/docs/man1.1.1/man3/EVP_DigestVerify.html
+    #[corresponds(EVP_DigestVerify)]
     #[cfg(any(ossl111, boringssl, libressl370))]
     pub fn verify_oneshot(&mut self, signature: &[u8], buf: &[u8]) -> Result<bool, ErrorStack> {
         unsafe {