Skip to content

Commit

Permalink
Merge pull request #2282 from rushilmehra/update-docs
Browse files Browse the repository at this point in the history 
Update some docs to use the corresponds macro
  • Loading branch information
@sfackler
sfackler authored Aug 25, 2024
2 parents 7000b5d + da75d41 commit 28be7ed
Show file tree
Hide file tree
Showing 7 changed files with 50 additions and 208 deletions.
4 changes: 0 additions & 4 deletions openssl/src/cipher_ctx.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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> {
Expand Down
11 changes: 3 additions & 8 deletions openssl/src/hash.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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))] {
Expand All @@ -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 {
Expand All @@ -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()?;
Expand Down
2 changes: 0 additions & 2 deletions openssl/src/nid.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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> {
Expand Down
92 changes: 20 additions & 72 deletions openssl/src/sign.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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))] {
Expand Down Expand Up @@ -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,
Expand All @@ -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,
Expand Down Expand Up @@ -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;
Expand All @@ -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(
Expand All @@ -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(
Expand All @@ -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(
Expand All @@ -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(
Expand All @@ -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()
}
Expand Down Expand Up @@ -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();
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand All @@ -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,
Expand Down Expand Up @@ -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;
Expand All @@ -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(
Expand All @@ -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(
Expand All @@ -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(
Expand All @@ -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(
Expand All @@ -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 =
Expand All @@ -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 {
Expand Down
Loading

0 comments on commit 28be7ed

Please sign in to comment.