Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update some docs to use the corresponds macro #2282

Merged
merged 1 commit into from
Aug 25, 2024
Merged

Update some docs to use the corresponds macro #2282

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 0 additions & 4 deletions openssl/src/cipher_ctx.rs
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading