Unverified Commit 28be7edd authored by Steven Fackler's avatar Steven Fackler Committed by GitHub
Browse files

Merge pull request #2282 from rushilmehra/update-docs 

Update some docs to use the corresponds macro
parents 7000b5dd da75d41f

openssl/src/cipher_ctx.rs

+0 −4
Original line number Diff line number Diff line
@@ -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

+3 −8
Original line number Diff line number Diff line
@@ -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

+0 −2
Original line number Diff line number Diff line
@@ -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

+20 −72
Original line number Diff line number Diff line
@@ -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 {

openssl/src/ssl/mod.rs

+7 −48
Original line number Diff line number Diff line
@@ -2297,10 +2297,6 @@ impl Ssl { 
    }



    /// Creates a new `Ssl`.

    ///

    /// This corresponds to [`SSL_new`].

    ///

    /// [`SSL_new`]: https://www.openssl.org/docs/manmaster/ssl/SSL_new.html

    #[corresponds(SSL_new)]

    pub fn new(ctx: &SslContextRef) -> Result<Ssl, ErrorStack> {

        let session_ctx_index = try_get_session_ctx_index()?;
@@ -2314,15 +2310,10 @@ impl Ssl { 
    }



    /// Initiates a client-side TLS handshake.

    ///

    /// This corresponds to [`SSL_connect`].

    ///

    /// # Warning

    ///

    /// OpenSSL's default configuration is insecure. It is highly recommended to use

    /// `SslConnector` rather than `Ssl` directly, as it manages that configuration.

    ///

    /// [`SSL_connect`]: https://www.openssl.org/docs/manmaster/man3/SSL_connect.html

    #[corresponds(SSL_connect)]

    #[allow(deprecated)]

    pub fn connect<S>(self, stream: S) -> Result<SslStream<S>, HandshakeError<S>>
@@ -2334,14 +2325,10 @@ impl Ssl { 


    /// Initiates a server-side TLS handshake.

    ///

    /// This corresponds to [`SSL_accept`].

    ///

    /// # Warning

    ///

    /// OpenSSL's default configuration is insecure. It is highly recommended to use

    /// `SslAcceptor` rather than `Ssl` directly, as it manages that configuration.

    ///

    /// [`SSL_accept`]: https://www.openssl.org/docs/manmaster/man3/SSL_accept.html

    #[corresponds(SSL_accept)]

    #[allow(deprecated)]

    pub fn accept<S>(self, stream: S) -> Result<SslStream<S>, HandshakeError<S>>
@@ -2656,10 +2643,6 @@ 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 {
@@ -2678,10 +2661,6 @@ 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_srtp_profiles)]

    pub fn srtp_profiles(&self) -> Option<&StackRef<SrtpProtectionProfile>> {

        unsafe {
@@ -3526,9 +3505,7 @@ where 
{

    /// Restarts the handshake process.

    ///

    /// 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(mut self) -> Result<SslStream<S>, HandshakeError<S>> {

        match self.stream.do_handshake() {

            Ok(()) => Ok(self.stream),
@@ -4056,10 +4033,7 @@ where 
    /// `accept`. If a HelloRetryRequest containing a fresh cookie was

    /// transmitted, `Ok(false)` is returned instead. If the handshake cannot

    /// proceed at all, `Err` is returned.

    ///

    /// This corresponds to [`SSL_stateless`]

    ///

    /// [`SSL_stateless`]: https://www.openssl.org/docs/manmaster/man3/SSL_stateless.html

    #[corresponds(SSL_stateless)]

    #[cfg(ossl111)]

    pub fn stateless(&mut self) -> Result<bool, ErrorStack> {

        match unsafe { ffi::SSL_stateless(self.inner.ssl.as_ptr()) } {
@@ -4071,19 +4045,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()) }

    }
@@ -4129,10 +4097,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(mut self) -> Result<SslStream<S>, HandshakeError<S>> {

        match self.inner.do_handshake() {

            Ok(()) => Ok(self.inner),
@@ -4160,10 +4125,7 @@ where 
    /// Returns `Ok(0)` if all early data has been read.

    ///

    /// Requires OpenSSL 1.1.1 or LibreSSL 3.4.0 or newer.

    ///

    /// This corresponds to [`SSL_read_early_data`].

    ///

    /// [`SSL_read_early_data`]: https://www.openssl.org/docs/manmaster/man3/SSL_read_early_data.html

    #[corresponds(SSL_read_early_data)]

    #[cfg(any(ossl111, libressl340))]

    pub fn read_early_data(&mut self, buf: &mut [u8]) -> Result<usize, Error> {

        self.inner.read_early_data(buf)
@@ -4175,10 +4137,7 @@ where 
    /// `set_connect_state` first.

    ///

    /// Requires OpenSSL 1.1.1 or LibreSSL 3.4.0 or newer.

    ///

    /// This corresponds to [`SSL_write_early_data`].

    ///

    /// [`SSL_write_early_data`]: https://www.openssl.org/docs/manmaster/man3/SSL_write_early_data.html

    #[corresponds(SSL_write_early_data)]

    #[cfg(any(ossl111, libressl340))]

    pub fn write_early_data(&mut self, buf: &[u8]) -> Result<usize, Error> {

        self.inner.write_early_data(buf)