From 0d30ebfd58d86e010693f5596e9cd43cedc48c8e Mon Sep 17 00:00:00 2001 From: 0x676e67 Date: Fri, 14 Feb 2025 02:07:41 +0800 Subject: [PATCH] Use corresponds macro (#50) * RTG-3333 Support X25519MLKEM768 by default, but don't sent it as client X25519MLKEM768 is the standardised successor of the preliminary X25519Kyber768Draft00. Latest browsers have switched to X25519MLKEM768. Cloudflare supports both on the edge. We've had support for X25519MLKEM768 in this crate for a while, but didn't enable by default. We're now enabling serverside support by default. We also let clients advertise support when set to kx-client-pq-supported. We don't enable support by default yet for clients set to kx-client-pq-preferred, as that would cause an extra round-trip due to HelloRetryRequest if the server doesn't support X25519MLKEM768 yet. BoringSSL against which we build must support X25519MLKEM768, otherwise this will fail. * replace once_cell with LazyLock We can drop the once_cell dependency since the same functionality is implemented in std now. Requires bumping MSRV to 1.80. * fix manual_c_str_literals clippy warning * chore: Fix docs on SslRef::replace_ex_data * Detailed error codes * Clean up boring_sys::init() We don't need the workaround that was initially introduced for a bug in openssl, and OPENSSL_init_ssl always calls into CRYPTO_library_init on boringssl, so just call it explicitly. * Expose EVP_HPKE_KEY * Expose client/server-side ECH Resolves https://github.com/cloudflare/boring/issues/282 * Clean up ECH tests * Expose SSL_set_enable_ech_grease * update * Use corresponds macro --------- Co-authored-by: Bas Westerbaan Co-authored-by: Alessandro Ghedini Co-authored-by: Evan Rittenhouse Co-authored-by: Kornel Co-authored-by: Rushil Mehra --- boring/src/derive.rs | 21 ++---- boring/src/dh.rs | 21 ++---- boring/src/dsa.rs | 36 ++------- boring/src/ec.rs | 158 ++++++++------------------------------- boring/src/ecdsa.rs | 36 ++------- boring/src/fips.rs | 4 +- boring/src/hash.rs | 6 +- boring/src/nid.rs | 12 +-- boring/src/pkcs12.rs | 11 +-- boring/src/pkey.rs | 106 ++++++-------------------- boring/src/rsa.rs | 154 ++++++++------------------------------ boring/src/sign.rs | 92 +++++------------------ boring/src/ssl/mod.rs | 33 ++------ boring/src/symm.rs | 6 +- boring/src/x509/mod.rs | 90 +++++----------------- boring/src/x509/store.rs | 5 +- 16 files changed, 171 insertions(+), 620 deletions(-) diff --git a/boring/src/derive.rs b/boring/src/derive.rs index 66df434f..701d48a3 100644 --- a/boring/src/derive.rs +++ b/boring/src/derive.rs @@ -1,6 +1,7 @@ //! Shared secret derivation. use crate::ffi; use foreign_types::ForeignTypeRef; +use openssl_macros::corresponds; use std::marker::PhantomData; use std::ptr; @@ -25,10 +26,7 @@ impl Drop for Deriver<'_> { #[allow(clippy::len_without_is_empty)] impl<'a> Deriver<'a> { /// Creates a new `Deriver` using the provided private key. - /// - /// This corresponds to [`EVP_PKEY_derive_init`]. - /// - /// [`EVP_PKEY_derive_init`]: https://www.openssl.org/docs/man1.0.2/crypto/EVP_PKEY_derive_init.html + #[corresponds(EVP_PKEY_derive_init)] pub fn new(key: &'a PKeyRef) -> Result, ErrorStack> where T: HasPrivate, @@ -41,10 +39,7 @@ impl<'a> Deriver<'a> { } /// Sets the peer key used for secret derivation. - /// - /// This corresponds to [`EVP_PKEY_derive_set_peer`]: - /// - /// [`EVP_PKEY_derive_set_peer`]: https://www.openssl.org/docs/man1.0.2/crypto/EVP_PKEY_derive_init.html + #[corresponds(EVP_PKEY_derive_set_peer)] pub fn set_peer(&mut self, key: &'a PKeyRef) -> Result<(), ErrorStack> where T: HasPublic, @@ -55,10 +50,7 @@ impl<'a> Deriver<'a> { /// Returns the size of the shared secret. /// /// It can be used to size the buffer passed to [`Deriver::derive`]. - /// - /// This corresponds to [`EVP_PKEY_derive`]. - /// - /// [`Deriver::derive`]: #method.derive + #[corresponds(EVP_PKEY_derive)] /// [`EVP_PKEY_derive`]: https://www.openssl.org/docs/man1.0.2/crypto/EVP_PKEY_derive_init.html pub fn len(&mut self) -> Result { unsafe { @@ -70,10 +62,7 @@ impl<'a> Deriver<'a> { /// Derives a shared secret between the two keys, writing it into the buffer. /// /// Returns the number of bytes written. - /// - /// This corresponds to [`EVP_PKEY_derive`]. - /// - /// [`EVP_PKEY_derive`]: https://www.openssl.org/docs/man1.0.2/crypto/EVP_PKEY_derive_init.html + #[corresponds(EVP_PKEY_derive)] pub fn derive(&mut self, buf: &mut [u8]) -> Result { let mut len = buf.len(); unsafe { diff --git a/boring/src/dh.rs b/boring/src/dh.rs index 96a8c63d..c8449d86 100644 --- a/boring/src/dh.rs +++ b/boring/src/dh.rs @@ -1,6 +1,7 @@ use crate::error::ErrorStack; use crate::ffi; use foreign_types::{ForeignType, ForeignTypeRef}; +use openssl_macros::corresponds; use std::mem; use std::ptr; @@ -25,20 +26,14 @@ where /// Serializes the parameters into a PEM-encoded PKCS#3 DHparameter structure. /// /// The output will have a header of `-----BEGIN DH PARAMETERS-----`. - /// - /// This corresponds to [`PEM_write_bio_DHparams`]. - /// - /// [`PEM_write_bio_DHparams`]: https://www.openssl.org/docs/manmaster/man3/PEM_write_bio_DHparams.html + #[corresponds(PEM_write_bio_DHparams)] params_to_pem, ffi::PEM_write_bio_DHparams } to_der! { /// Serializes the parameters into a DER-encoded PKCS#3 DHparameter structure. - /// - /// This corresponds to [`i2d_DHparams`]. - /// - /// [`i2d_DHparams`]: https://www.openssl.org/docs/man1.1.0/crypto/i2d_DHparams.html + #[corresponds(i2d_DHparams)] params_to_der, ffi::i2d_DHparams } @@ -58,10 +53,7 @@ impl Dh { /// Deserializes a PEM-encoded PKCS#3 DHpararameters structure. /// /// The input should have a header of `-----BEGIN DH PARAMETERS-----`. - /// - /// This corresponds to [`PEM_read_bio_DHparams`]. - /// - /// [`PEM_read_bio_DHparams`]: https://www.openssl.org/docs/man1.0.2/crypto/PEM_read_bio_DHparams.html + #[corresponds(PEM_read_bio_DHparams)] params_from_pem, Dh, ffi::PEM_read_bio_DHparams @@ -69,10 +61,7 @@ impl Dh { from_der! { /// Deserializes a DER-encoded PKCS#3 DHparameters structure. - /// - /// This corresponds to [`d2i_DHparams`]. - /// - /// [`d2i_DHparams`]: https://www.openssl.org/docs/man1.1.0/crypto/d2i_DHparams.html + #[corresponds(d2i_DHparams)] params_from_der, Dh, ffi::d2i_DHparams, diff --git a/boring/src/dsa.rs b/boring/src/dsa.rs index d9c35505..72d6947e 100644 --- a/boring/src/dsa.rs +++ b/boring/src/dsa.rs @@ -8,6 +8,7 @@ use crate::ffi; use foreign_types::{ForeignType, ForeignTypeRef}; use libc::c_uint; +use openssl_macros::corresponds; use std::fmt; use std::mem; use std::ptr; @@ -84,20 +85,14 @@ where /// Serialies the public key into a PEM-encoded SubjectPublicKeyInfo structure. /// /// The output will have a header of `-----BEGIN PUBLIC KEY-----`. - /// - /// This corresponds to [`PEM_write_bio_DSA_PUBKEY`]. - /// - /// [`PEM_write_bio_DSA_PUBKEY`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_write_bio_DSA_PUBKEY.html + #[corresponds(PEM_write_bio_DSA_PUBKEY)] public_key_to_pem, ffi::PEM_write_bio_DSA_PUBKEY } to_der! { /// Serializes the public key into a DER-encoded SubjectPublicKeyInfo structure. - /// - /// This corresponds to [`i2d_DSA_PUBKEY`]. - /// - /// [`i2d_DSA_PUBKEY`]: https://www.openssl.org/docs/man1.1.0/crypto/i2d_DSA_PUBKEY.html + #[corresponds(i2d_DSA_PUBKEY)] public_key_to_der, ffi::i2d_DSA_PUBKEY } @@ -120,18 +115,12 @@ where /// Serializes the private key to a PEM-encoded DSAPrivateKey structure. /// /// The output will have a header of `-----BEGIN DSA PRIVATE KEY-----`. - /// - /// This corresponds to [`PEM_write_bio_DSAPrivateKey`]. - /// - /// [`PEM_write_bio_DSAPrivateKey`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_write_bio_DSAPrivateKey.html + #[corresponds(PEM_write_bio_DSAPrivateKey)] private_key_to_pem, /// Serializes the private key to a PEM-encoded encrypted DSAPrivateKey structure. /// /// The output will have a header of `-----BEGIN DSA PRIVATE KEY-----`. - /// - /// This corresponds to [`PEM_write_bio_DSAPrivateKey`]. - /// - /// [`PEM_write_bio_DSAPrivateKey`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_write_bio_DSAPrivateKey.html + #[corresponds(PEM_write_bio_DSAPrivateKey)] private_key_to_pem_passphrase, ffi::PEM_write_bio_DSAPrivateKey } @@ -151,10 +140,7 @@ where T: HasParams, { /// Returns the maximum size of the signature output by `self` in bytes. - /// - /// OpenSSL documentation at [`DSA_size`] - /// - /// [`DSA_size`]: https://www.openssl.org/docs/man1.1.0/crypto/DSA_size.html + #[corresponds(DSA_size)] pub fn size(&self) -> u32 { unsafe { ffi::DSA_size(self.as_ptr()) as u32 } } @@ -244,10 +230,7 @@ impl Dsa { /// Decodes a PEM-encoded SubjectPublicKeyInfo structure containing a DSA key. /// /// The input should have a header of `-----BEGIN PUBLIC KEY-----`. - /// - /// This corresponds to [`PEM_read_bio_DSA_PUBKEY`]. - /// - /// [`PEM_read_bio_DSA_PUBKEY`]: https://www.openssl.org/docs/man1.0.2/crypto/PEM_read_bio_DSA_PUBKEY.html + #[corresponds(PEM_read_bio_DSA_PUBKEY)] public_key_from_pem, Dsa, ffi::PEM_read_bio_DSA_PUBKEY @@ -255,10 +238,7 @@ impl Dsa { from_der! { /// Decodes a DER-encoded SubjectPublicKeyInfo structure containing a DSA key. - /// - /// This corresponds to [`d2i_DSA_PUBKEY`]. - /// - /// [`d2i_DSA_PUBKEY`]: https://www.openssl.org/docs/man1.0.2/crypto/d2i_DSA_PUBKEY.html + #[corresponds(d2i_DSA_PUBKEY)] public_key_from_der, Dsa, ffi::d2i_DSA_PUBKEY, diff --git a/boring/src/ec.rs b/boring/src/ec.rs index bbc6638d..8008927a 100644 --- a/boring/src/ec.rs +++ b/boring/src/ec.rs @@ -18,6 +18,7 @@ use crate::ffi; use foreign_types::{ForeignType, ForeignTypeRef}; use libc::c_int; +use openssl_macros::corresponds; use std::fmt; use std::ptr; @@ -111,10 +112,7 @@ foreign_type_and_impl_send_sync! { impl EcGroup { /// Returns the group of a standard named curve. - /// - /// OpenSSL documentation at [`EC_GROUP_new`]. - /// - /// [`EC_GROUP_new`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_GROUP_new.html + #[corresponds(EC_GROUP_new)] pub fn from_curve_name(nid: Nid) -> Result { unsafe { init(); @@ -150,10 +148,7 @@ impl EcGroupRef { } /// Places the cofactor of the group in the provided `BigNum`. - /// - /// OpenSSL documentation at [`EC_GROUP_get_cofactor`] - /// - /// [`EC_GROUP_get_cofactor`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_GROUP_get_cofactor.html + #[corresponds(EC_GROUP_get_cofactor)] pub fn cofactor( &self, cofactor: &mut BigNumRef, @@ -170,29 +165,20 @@ impl EcGroupRef { } /// Returns the degree of the curve. - /// - /// OpenSSL documentation at [`EC_GROUP_get_degree`] - /// - /// [`EC_GROUP_get_degree`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_GROUP_get_degree.html + #[corresponds(EC_GROUP_get_degree)] #[allow(clippy::unnecessary_cast)] pub fn degree(&self) -> u32 { unsafe { ffi::EC_GROUP_get_degree(self.as_ptr()) as u32 } } /// Returns the number of bits in the group order. - /// - /// OpenSSL documentation at [`EC_GROUP_order_bits`] - /// - /// [`EC_GROUP_order_bits`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_GROUP_order_bits.html + #[corresponds(EC_GROUP_order_bits)] pub fn order_bits(&self) -> u32 { unsafe { ffi::EC_GROUP_order_bits(self.as_ptr()) as u32 } } /// Returns the generator for the given curve as a [`EcPoint`]. - /// - /// OpenSSL documentation at [`EC_GROUP_get0_generator`] - /// - /// [`EC_GROUP_get0_generator`]: https://www.openssl.org/docs/man1.1.0/man3/EC_GROUP_get0_generator.html + #[corresponds(EC_GROUP_get0_generator)] pub fn generator(&self) -> &EcPointRef { unsafe { let ptr = ffi::EC_GROUP_get0_generator(self.as_ptr()); @@ -201,10 +187,7 @@ impl EcGroupRef { } /// Places the order of the curve in the provided `BigNum`. - /// - /// OpenSSL documentation at [`EC_GROUP_get_order`] - /// - /// [`EC_GROUP_get_order`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_GROUP_get_order.html + #[corresponds(EC_GROUP_get_order)] pub fn order( &self, order: &mut BigNumRef, @@ -232,10 +215,7 @@ impl EcGroupRef { } /// Returns the name of the curve, if a name is associated. - /// - /// OpenSSL documentation at [`EC_GROUP_get_curve_name`] - /// - /// [`EC_GROUP_get_curve_name`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_GROUP_get_curve_name.html + #[corresponds(EC_GROUP_get_curve_name)] pub fn curve_name(&self) -> Option { let nid = unsafe { ffi::EC_GROUP_get_curve_name(self.as_ptr()) }; if nid > 0 { @@ -260,10 +240,7 @@ foreign_type_and_impl_send_sync! { impl EcPointRef { /// Computes `a + b`, storing the result in `self`. - /// - /// OpenSSL documentation at [`EC_POINT_add`] - /// - /// [`EC_POINT_add`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_add.html + #[corresponds(EC_POINT_add)] pub fn add( &mut self, group: &EcGroupRef, @@ -284,10 +261,7 @@ impl EcPointRef { } /// Computes `q * m`, storing the result in `self`. - /// - /// OpenSSL documentation at [`EC_POINT_mul`] - /// - /// [`EC_POINT_mul`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_mul.html + #[corresponds(EC_POINT_mul)] pub fn mul( &mut self, group: &EcGroupRef, @@ -353,10 +327,7 @@ impl EcPointRef { } /// Inverts `self`. - /// - /// OpenSSL documentation at [`EC_POINT_invert`] - /// - /// [`EC_POINT_invert`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_invert.html + #[corresponds(EC_POINT_invert)] pub fn invert(&mut self, group: &EcGroupRef, ctx: &BigNumContextRef) -> Result<(), ErrorStack> { unsafe { cvt(ffi::EC_POINT_invert( @@ -369,10 +340,7 @@ impl EcPointRef { } /// Serializes the point to a binary representation. - /// - /// OpenSSL documentation at [`EC_POINT_point2oct`] - /// - /// [`EC_POINT_point2oct`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_point2oct.html + #[corresponds(EC_POINT_point2oct)] pub fn to_bytes( &self, group: &EcGroupRef, @@ -409,10 +377,7 @@ impl EcPointRef { } /// Creates a new point on the specified curve with the same value. - /// - /// OpenSSL documentation at [`EC_POINT_dup`] - /// - /// [`EC_POINT_dup`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_dup.html + #[corresponds(EC_POINT_dup)] pub fn to_owned(&self, group: &EcGroupRef) -> Result { unsafe { cvt_p(ffi::EC_POINT_dup(self.as_ptr(), group.as_ptr())).map(|p| EcPoint::from_ptr(p)) @@ -443,10 +408,7 @@ impl EcPointRef { /// Place affine coordinates of a curve over a prime field in the provided /// `x` and `y` `BigNum`s - /// - /// OpenSSL documentation at [`EC_POINT_get_affine_coordinates_GFp`] - /// - /// [`EC_POINT_get_affine_coordinates_GFp`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_get_affine_coordinates_GFp.html + #[corresponds(EC_POINT_get_affine_coordinates_GFp)] pub fn affine_coordinates_gfp( &self, group: &EcGroupRef, @@ -469,19 +431,13 @@ impl EcPointRef { impl EcPoint { /// Creates a new point on the specified curve. - /// - /// OpenSSL documentation at [`EC_POINT_new`] - /// - /// [`EC_POINT_new`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_new.html + #[corresponds(EC_POINT_new)] pub fn new(group: &EcGroupRef) -> Result { unsafe { cvt_p(ffi::EC_POINT_new(group.as_ptr())).map(|p| EcPoint::from_ptr(p)) } } /// Creates point from a binary representation - /// - /// OpenSSL documentation at [`EC_POINT_oct2point`] - /// - /// [`EC_POINT_oct2point`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_POINT_oct2point.html + #[corresponds(EC_POINT_oct2point)] pub fn from_bytes( group: &EcGroupRef, buf: &[u8], @@ -507,9 +463,6 @@ generic_foreign_type_and_impl_send_sync! { /// Public and optional Private key on the given curve /// - /// OpenSSL documentation at [`EC_KEY_new`] - /// - /// [`EC_KEY_new`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_KEY_new.html pub struct EcKey; /// Reference to [`EcKey`] @@ -526,37 +479,25 @@ where /// Serializes the private key to a PEM-encoded ECPrivateKey structure. /// /// The output will have a header of `-----BEGIN EC PRIVATE KEY-----`. - /// - /// This corresponds to [`PEM_write_bio_ECPrivateKey`]. - /// - /// [`PEM_write_bio_ECPrivateKey`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_write_bio_ECPrivateKey.html + #[corresponds(PEM_write_bio_ECPrivateKey)] private_key_to_pem, /// Serializes the private key to a PEM-encoded encrypted ECPrivateKey structure. /// /// The output will have a header of `-----BEGIN EC PRIVATE KEY-----`. - /// - /// This corresponds to [`PEM_write_bio_ECPrivateKey`]. - /// - /// [`PEM_write_bio_ECPrivateKey`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_write_bio_ECPrivateKey.html + #[corresponds(PEM_write_bio_ECPrivateKey)] private_key_to_pem_passphrase, ffi::PEM_write_bio_ECPrivateKey } to_der! { /// Serializes the private key into a DER-encoded ECPrivateKey structure. - /// - /// This corresponds to [`i2d_ECPrivateKey`]. - /// - /// [`i2d_ECPrivateKey`]: https://www.openssl.org/docs/man1.0.2/crypto/d2i_ECPrivate_key.html + #[corresponds(i2d_ECPrivateKey)] private_key_to_der, ffi::i2d_ECPrivateKey } /// Return [`EcPoint`] associated with the private key - /// - /// OpenSSL documentation at [`EC_KEY_get0_private_key`] - /// - /// [`EC_KEY_get0_private_key`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_KEY_get0_private_key.html + #[corresponds(EC_KEY_get0_private_key)] pub fn private_key(&self) -> &BigNumRef { unsafe { let ptr = ffi::EC_KEY_get0_private_key(self.as_ptr()); @@ -570,10 +511,7 @@ where T: HasPublic, { /// Returns the public key. - /// - /// OpenSSL documentation at [`EC_KEY_get0_public_key`] - /// - /// [`EC_KEY_get0_public_key`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_KEY_get0_public_key.html + #[corresponds(EC_KEY_get0_public_key)] pub fn public_key(&self) -> &EcPointRef { unsafe { let ptr = ffi::EC_KEY_get0_public_key(self.as_ptr()); @@ -585,20 +523,14 @@ where /// Serialies the public key into a PEM-encoded SubjectPublicKeyInfo structure. /// /// The output will have a header of `-----BEGIN PUBLIC KEY-----`. - /// - /// This corresponds to [`PEM_write_bio_EC_PUBKEY`]. - /// - /// [`PEM_write_bio_EC_PUBKEY`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_write_bio_EC_PUBKEY.html + #[corresponds(PEM_write_bio_EC_PUBKEY)] public_key_to_pem, ffi::PEM_write_bio_EC_PUBKEY } to_der! { /// Serializes the public key into a DER-encoded SubjectPublicKeyInfo structure. - /// - /// This corresponds to [`i2d_EC_PUBKEY`]. - /// - /// [`i2d_EC_PUBKEY`]: https://www.openssl.org/docs/man1.1.0/crypto/i2d_EC_PUBKEY.html + #[corresponds(i2d_EC_PUBKEY)] public_key_to_der, ffi::i2d_EC_PUBKEY } @@ -609,10 +541,7 @@ where T: HasParams, { /// Return [`EcGroup`] of the `EcKey` - /// - /// OpenSSL documentation at [`EC_KEY_get0_group`] - /// - /// [`EC_KEY_get0_group`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_KEY_get0_group.html + #[corresponds(EC_KEY_get0_group)] pub fn group(&self) -> &EcGroupRef { unsafe { let ptr = ffi::EC_KEY_get0_group(self.as_ptr()); @@ -621,10 +550,7 @@ where } /// Checks the key for validity. - /// - /// OpenSSL documentation at [`EC_KEY_check_key`] - /// - /// [`EC_KEY_check_key`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_KEY_check_key.html + #[corresponds(EC_KEY_check_key)] pub fn check_key(&self) -> Result<(), ErrorStack> { unsafe { cvt(ffi::EC_KEY_check_key(self.as_ptr())).map(|_| ()) } } @@ -647,10 +573,7 @@ impl EcKey { /// /// It will not have an associated public or private key. This kind of key is primarily useful /// to be provided to the `set_tmp_ecdh` methods on `Ssl` and `SslContextBuilder`. - /// - /// OpenSSL documentation at [`EC_KEY_new_by_curve_name`] - /// - /// [`EC_KEY_new_by_curve_name`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_KEY_new_by_curve_name.html + #[corresponds(EC_KEY_new_by_curve_name)] pub fn from_curve_name(nid: Nid) -> Result, ErrorStack> { unsafe { init(); @@ -659,10 +582,7 @@ impl EcKey { } /// Constructs an `EcKey` corresponding to a curve. - /// - /// This corresponds to [`EC_KEY_set_group`]. - /// - /// [`EC_KEY_set_group`]: https://www.openssl.org/docs/man1.1.0/crypto/EC_KEY_new.html + #[corresponds(EC_KEY_set_group)] pub fn from_group(group: &EcGroupRef) -> Result, ErrorStack> { unsafe { cvt_p(ffi::EC_KEY_new()) @@ -743,10 +663,7 @@ impl EcKey { /// Decodes a PEM-encoded SubjectPublicKeyInfo structure containing a EC key. /// /// The input should have a header of `-----BEGIN PUBLIC KEY-----`. - /// - /// This corresponds to [`PEM_read_bio_EC_PUBKEY`]. - /// - /// [`PEM_read_bio_EC_PUBKEY`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_read_bio_EC_PUBKEY.html + #[corresponds(PEM_read_bio_EC_PUBKEY)] public_key_from_pem, EcKey, ffi::PEM_read_bio_EC_PUBKEY @@ -754,10 +671,7 @@ impl EcKey { from_der! { /// Decodes a DER-encoded SubjectPublicKeyInfo structure containing a EC key. - /// - /// This corresponds to [`d2i_EC_PUBKEY`]. - /// - /// [`d2i_EC_PUBKEY`]: https://www.openssl.org/docs/man1.1.0/crypto/d2i_EC_PUBKEY.html + #[corresponds(d2i_EC_PUBKEY)] public_key_from_der, EcKey, ffi::d2i_EC_PUBKEY, @@ -811,15 +725,13 @@ impl EcKey { /// Deserializes a private key from a PEM-encoded ECPrivateKey structure. /// /// The input should have a header of `-----BEGIN EC PRIVATE KEY-----`. - /// - /// This corresponds to `PEM_read_bio_ECPrivateKey`. + #[corresponds(PEM_read_bio_ECPrivateKey)] private_key_from_pem, /// Deserializes a private key from a PEM-encoded encrypted ECPrivateKey structure. /// /// The input should have a header of `-----BEGIN EC PRIVATE KEY-----`. - /// - /// This corresponds to `PEM_read_bio_ECPrivateKey`. + #[corresponds(PEM_read_bio_ECPrivateKey)] private_key_from_pem_passphrase, /// Deserializes a private key from a PEM-encoded encrypted ECPrivateKey structure. @@ -827,8 +739,7 @@ impl EcKey { /// The callback should fill the password into the provided buffer and return its length. /// /// The input should have a header of `-----BEGIN EC PRIVATE KEY-----`. - /// - /// This corresponds to `PEM_read_bio_ECPrivateKey`. + #[corresponds(PEM_read_bio_ECPrivateKey)] private_key_from_pem_callback, EcKey, ffi::PEM_read_bio_ECPrivateKey @@ -836,10 +747,7 @@ impl EcKey { from_der! { /// Decodes a DER-encoded elliptic curve private key structure. - /// - /// This corresponds to [`d2i_ECPrivateKey`]. - /// - /// [`d2i_ECPrivateKey`]: https://www.openssl.org/docs/man1.0.2/crypto/d2i_ECPrivate_key.html + #[corresponds(d2i_ECPrivateKey)] private_key_from_der, EcKey, ffi::d2i_ECPrivateKey, diff --git a/boring/src/ecdsa.rs b/boring/src/ecdsa.rs index 782dbf20..a56f7b68 100644 --- a/boring/src/ecdsa.rs +++ b/boring/src/ecdsa.rs @@ -3,6 +3,7 @@ use crate::ffi; use foreign_types::{ForeignType, ForeignTypeRef}; use libc::{c_int, size_t}; +use openssl_macros::corresponds; use std::mem; use std::ptr; @@ -26,10 +27,7 @@ foreign_type_and_impl_send_sync! { impl EcdsaSig { /// Computes a digital signature of the hash value `data` using the private EC key eckey. - /// - /// OpenSSL documentation at [`ECDSA_do_sign`] - /// - /// [`ECDSA_do_sign`]: https://www.openssl.org/docs/man1.1.0/crypto/ECDSA_do_sign.html + #[corresponds(ECDSA_do_sign)] pub fn sign(data: &[u8], eckey: &EcKeyRef) -> Result where T: HasPrivate, @@ -47,10 +45,7 @@ impl EcdsaSig { /// Returns a new `EcdsaSig` by setting the `r` and `s` values associated with a /// ECDSA signature. - /// - /// OpenSSL documentation at [`ECDSA_SIG_set0`] - /// - /// [`ECDSA_SIG_set0`]: https://www.openssl.org/docs/man1.1.0/crypto/ECDSA_SIG_set0.html + #[corresponds(ECDSA_SIG_set0)] pub fn from_private_components(r: BigNum, s: BigNum) -> Result { unsafe { let sig = cvt_p(ffi::ECDSA_SIG_new())?; @@ -62,10 +57,7 @@ impl EcdsaSig { from_der! { /// Decodes a DER-encoded ECDSA signature. - /// - /// This corresponds to [`d2i_ECDSA_SIG`]. - /// - /// [`d2i_ECDSA_SIG`]: https://www.openssl.org/docs/man1.1.0/crypto/d2i_ECDSA_SIG.html + #[corresponds(d2i_ECDSA_SIG)] from_der, EcdsaSig, ffi::d2i_ECDSA_SIG, @@ -76,19 +68,13 @@ impl EcdsaSig { impl EcdsaSigRef { to_der! { /// Serializes the ECDSA signature into a DER-encoded ECDSASignature structure. - /// - /// This corresponds to [`i2d_ECDSA_SIG`]. - /// - /// [`i2d_ECDSA_SIG`]: https://www.openssl.org/docs/man1.1.0/crypto/i2d_ECDSA_SIG.html + #[corresponds(i2d_ECDSA_SIG)] to_der, ffi::i2d_ECDSA_SIG } /// Verifies if the signature is a valid ECDSA signature using the given public key. - /// - /// OpenSSL documentation at [`ECDSA_do_verify`] - /// - /// [`ECDSA_do_verify`]: https://www.openssl.org/docs/man1.1.0/crypto/ECDSA_do_verify.html + #[corresponds(ECDSA_do_verify)] pub fn verify(&self, data: &[u8], eckey: &EcKeyRef) -> Result where T: HasPublic, @@ -106,10 +92,7 @@ impl EcdsaSigRef { } /// Returns internal component: `r` of an `EcdsaSig`. (See X9.62 or FIPS 186-2) - /// - /// OpenSSL documentation at [`ECDSA_SIG_get0`] - /// - /// [`ECDSA_SIG_get0`]: https://www.openssl.org/docs/man1.1.0/crypto/ECDSA_SIG_get0.html + #[corresponds(ECDSA_SIG_get0)] pub fn r(&self) -> &BigNumRef { unsafe { let mut r = ptr::null(); @@ -119,10 +102,7 @@ impl EcdsaSigRef { } /// Returns internal components: `s` of an `EcdsaSig`. (See X9.62 or FIPS 186-2) - /// - /// OpenSSL documentation at [`ECDSA_SIG_get0`] - /// - /// [`ECDSA_SIG_get0`]: https://www.openssl.org/docs/man1.1.0/crypto/ECDSA_SIG_get0.html + #[corresponds(ECDSA_SIG_get0)] pub fn s(&self) -> &BigNumRef { unsafe { let mut s = ptr::null(); diff --git a/boring/src/fips.rs b/boring/src/fips.rs index e578ae75..de28f260 100644 --- a/boring/src/fips.rs +++ b/boring/src/fips.rs @@ -4,10 +4,10 @@ //! //! [OpenSSL's documentation]: https://www.openssl.org/docs/fips/UserGuide-2.0.pdf use crate::ffi; +use openssl_macros::corresponds; /// Determines if the library is running in the FIPS 140-2 mode of operation. -/// -/// This corresponds to `FIPS_mode`. +#[corresponds(FIPS_mode)] pub fn enabled() -> bool { unsafe { ffi::FIPS_mode() != 0 } } diff --git a/boring/src/hash.rs b/boring/src/hash.rs index 76167723..ba5d7bab 100644 --- a/boring/src/hash.rs +++ b/boring/src/hash.rs @@ -1,4 +1,5 @@ use crate::ffi; +use openssl_macros::corresponds; use std::convert::TryInto; use std::ffi::{c_uint, c_void}; use std::fmt; @@ -26,10 +27,7 @@ impl MessageDigest { } /// Returns the `MessageDigest` corresponding to an `Nid`. - /// - /// This corresponds to [`EVP_get_digestbynid`]. - /// - /// [`EVP_get_digestbynid`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_DigestInit.html + #[corresponds(EVP_get_digestbynid)] pub fn from_nid(type_: Nid) -> Option { unsafe { let ptr = ffi::EVP_get_digestbynid(type_.as_raw()); diff --git a/boring/src/nid.rs b/boring/src/nid.rs index a3b0f11a..11607626 100644 --- a/boring/src/nid.rs +++ b/boring/src/nid.rs @@ -1,6 +1,7 @@ //! A collection of numerical identifiers for OpenSSL objects. use crate::ffi; use libc::{c_char, c_int}; +use openssl_macros::corresponds; use std::ffi::CStr; use std::str; @@ -61,8 +62,7 @@ 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 { unsafe { @@ -80,9 +80,7 @@ impl Nid { } /// Return the string representation of a `Nid` (long) - /// This corresponds to [`OBJ_nid2ln`] - /// - /// [`OBJ_nid2ln`]: https://www.openssl.org/docs/man1.1.0/crypto/OBJ_nid2ln.html + #[corresponds(OBJ_nid2ln)] #[allow(clippy::trivially_copy_pass_by_ref)] pub fn long_name(&self) -> Result<&'static str, ErrorStack> { unsafe { @@ -92,9 +90,7 @@ impl Nid { } /// Return the string representation of a `Nid` (short) - /// This corresponds to [`OBJ_nid2sn`] - /// - /// [`OBJ_nid2sn`]: https://www.openssl.org/docs/man1.1.0/crypto/OBJ_nid2sn.html + #[corresponds(OBJ_nid2sn)] #[allow(clippy::trivially_copy_pass_by_ref)] pub fn short_name(&self) -> Result<&'static str, ErrorStack> { unsafe { diff --git a/boring/src/pkcs12.rs b/boring/src/pkcs12.rs index 4caec029..8604f6d1 100644 --- a/boring/src/pkcs12.rs +++ b/boring/src/pkcs12.rs @@ -3,6 +3,7 @@ use crate::ffi; use foreign_types::{ForeignType, ForeignTypeRef}; use libc::c_int; +use openssl_macros::corresponds; use std::ffi::CString; use std::ptr; @@ -25,10 +26,7 @@ foreign_type_and_impl_send_sync! { impl Pkcs12Ref { to_der! { /// Serializes the `Pkcs12` to its standard DER encoding. - /// - /// This corresponds to [`i2d_PKCS12`]. - /// - /// [`i2d_PKCS12`]: https://www.openssl.org/docs/manmaster/man3/i2d_PKCS12.html + #[corresponds(i2d_PKCS12)] to_der, ffi::i2d_PKCS12 } @@ -67,10 +65,7 @@ impl Pkcs12Ref { impl Pkcs12 { from_der! { /// Deserializes a DER-encoded PKCS#12 archive. - /// - /// This corresponds to [`d2i_PKCS12`]. - /// - /// [`d2i_PKCS12`]: https://www.openssl.org/docs/man1.1.0/crypto/d2i_PKCS12.html + #[corresponds(d2i_PKCS12)] from_der, Pkcs12, ffi::d2i_PKCS12, diff --git a/boring/src/pkey.rs b/boring/src/pkey.rs index 9897635e..1c4012ca 100644 --- a/boring/src/pkey.rs +++ b/boring/src/pkey.rs @@ -43,6 +43,7 @@ use crate::ffi; use foreign_types::{ForeignType, ForeignTypeRef}; use libc::{c_int, c_long}; +use openssl_macros::corresponds; use std::ffi::CString; use std::fmt; use std::mem; @@ -138,10 +139,7 @@ impl ToOwned for PKeyRef { impl PKeyRef { /// Returns a copy of the internal RSA key. - /// - /// This corresponds to [`EVP_PKEY_get1_RSA`]. - /// - /// [`EVP_PKEY_get1_RSA`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_get1_RSA.html + #[corresponds(EVP_PKEY_get1_RSA)] pub fn rsa(&self) -> Result, ErrorStack> { unsafe { let rsa = cvt_p(ffi::EVP_PKEY_get1_RSA(self.as_ptr()))?; @@ -150,10 +148,7 @@ impl PKeyRef { } /// Returns a copy of the internal DSA key. - /// - /// This corresponds to [`EVP_PKEY_get1_DSA`]. - /// - /// [`EVP_PKEY_get1_DSA`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_get1_DSA.html + #[corresponds(EVP_PKEY_get1_DSA)] pub fn dsa(&self) -> Result, ErrorStack> { unsafe { let dsa = cvt_p(ffi::EVP_PKEY_get1_DSA(self.as_ptr()))?; @@ -162,10 +157,7 @@ impl PKeyRef { } /// Returns a copy of the internal DH key. - /// - /// This corresponds to [`EVP_PKEY_get1_DH`]. - /// - /// [`EVP_PKEY_get1_DH`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_get1_DH.html + #[corresponds(EVP_PKEY_get1_DH)] pub fn dh(&self) -> Result, ErrorStack> { unsafe { let dh = cvt_p(ffi::EVP_PKEY_get1_DH(self.as_ptr()))?; @@ -174,10 +166,7 @@ impl PKeyRef { } /// Returns a copy of the internal elliptic curve key. - /// - /// This corresponds to [`EVP_PKEY_get1_EC_KEY`]. - /// - /// [`EVP_PKEY_get1_EC_KEY`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_get1_EC_KEY.html + #[corresponds(EVP_PKEY_get1_EC_KEY)] pub fn ec_key(&self) -> Result, ErrorStack> { unsafe { let ec_key = cvt_p(ffi::EVP_PKEY_get1_EC_KEY(self.as_ptr()))?; @@ -186,19 +175,13 @@ impl PKeyRef { } /// Returns the `Id` that represents the type of this key. - /// - /// This corresponds to [`EVP_PKEY_id`]. - /// - /// [`EVP_PKEY_id`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_id.html + #[corresponds(EVP_PKEY_id)] pub fn id(&self) -> Id { unsafe { Id::from_raw(ffi::EVP_PKEY_id(self.as_ptr())) } } /// Returns the maximum size of a signature in bytes. - /// - /// This corresponds to [`EVP_PKEY_size`]. - /// - /// [`EVP_PKEY_size`]: https://www.openssl.org/docs/man1.1.1/man3/EVP_PKEY_size.html + #[corresponds(EVP_PKEY_size)] pub fn size(&self) -> usize { unsafe { ffi::EVP_PKEY_size(self.as_ptr()) as usize } } @@ -212,20 +195,14 @@ where /// Serializes the public key into a PEM-encoded SubjectPublicKeyInfo structure. /// /// The output will have a header of `-----BEGIN PUBLIC KEY-----`. - /// - /// This corresponds to [`PEM_write_bio_PUBKEY`]. - /// - /// [`PEM_write_bio_PUBKEY`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_write_bio_PUBKEY.html + #[corresponds(PEM_write_bio_PUBKEY)] public_key_to_pem, ffi::PEM_write_bio_PUBKEY } to_der! { /// Serializes the public key into a DER-encoded SubjectPublicKeyInfo structure. - /// - /// This corresponds to [`i2d_PUBKEY`]. - /// - /// [`i2d_PUBKEY`]: https://www.openssl.org/docs/man1.1.0/crypto/i2d_PUBKEY.html + #[corresponds(i2d_PUBKEY)] public_key_to_der, ffi::i2d_PUBKEY } @@ -255,28 +232,19 @@ where /// Serializes the private key to a PEM-encoded PKCS#8 PrivateKeyInfo structure. /// /// The output will have a header of `-----BEGIN PRIVATE KEY-----`. - /// - /// This corresponds to [`PEM_write_bio_PKCS8PrivateKey`]. - /// - /// [`PEM_write_bio_PKCS8PrivateKey`]: https://www.openssl.org/docs/man1.0.2/crypto/PEM_write_bio_PKCS8PrivateKey.html + #[corresponds(PEM_write_bio_PKCS8PrivateKey)] private_key_to_pem_pkcs8, /// Serializes the private key to a PEM-encoded PKCS#8 EncryptedPrivateKeyInfo structure. /// /// The output will have a header of `-----BEGIN ENCRYPTED PRIVATE KEY-----`. - /// - /// This corresponds to [`PEM_write_bio_PKCS8PrivateKey`]. - /// - /// [`PEM_write_bio_PKCS8PrivateKey`]: https://www.openssl.org/docs/man1.0.2/crypto/PEM_write_bio_PKCS8PrivateKey.html + #[corresponds(PEM_write_bio_PKCS8PrivateKey)] private_key_to_pem_pkcs8_passphrase, ffi::PEM_write_bio_PKCS8PrivateKey } to_der! { /// Serializes the private key to a DER-encoded key type specific format. - /// - /// This corresponds to [`i2d_PrivateKey`]. - /// - /// [`i2d_PrivateKey`]: https://www.openssl.org/docs/man1.0.2/crypto/i2d_PrivateKey.html + #[corresponds(i2d_PrivateKey)] private_key_to_der, ffi::i2d_PrivateKey } @@ -285,16 +253,10 @@ where // "identical to the corresponding PEM function", and it's declared in pem.h. private_key_to_pem! { /// Serializes the private key to a DER-encoded PKCS#8 PrivateKeyInfo structure. - /// - /// This corresponds to [`i2d_PKCS8PrivateKey_bio`]. - /// - /// [`i2d_PKCS8PrivateKey_bio`]: https://www.openssl.org/docs/man1.1.1/man3/i2d_PKCS8PrivateKey_bio.html + #[corresponds(i2d_PKCS8PrivateKey_bio)] private_key_to_der_pkcs8, /// Serializes the private key to a DER-encoded PKCS#8 EncryptedPrivateKeyInfo structure. - /// - /// This corresponds to [`i2d_PKCS8PrivateKey_bio`]. - /// - /// [`i2d_PKCS8PrivateKey_bio`]: https://www.openssl.org/docs/man1.1.1/man3/i2d_PKCS8PrivateKey_bio.html + #[corresponds(i2d_PKCS8PrivateKey_bio)] private_key_to_der_pkcs8_passphrase, ffi::i2d_PKCS8PrivateKey_bio } @@ -325,10 +287,7 @@ impl Clone for PKey { impl PKey { /// Creates a new `PKey` containing an RSA key. - /// - /// This corresponds to [`EVP_PKEY_assign_RSA`]. - /// - /// [`EVP_PKEY_assign_RSA`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_assign_RSA.html + #[corresponds(EVP_PKEY_assign_RSA)] pub fn from_rsa(rsa: Rsa) -> Result, ErrorStack> { unsafe { let evp = cvt_p(ffi::EVP_PKEY_new())?; @@ -344,10 +303,7 @@ impl PKey { } /// Creates a new `PKey` containing an elliptic curve key. - /// - /// This corresponds to [`EVP_PKEY_assign_EC_KEY`]. - /// - /// [`EVP_PKEY_assign_EC_KEY`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_PKEY_assign_EC_KEY.html + #[corresponds(EVP_PKEY_assign_EC_KEY)] pub fn from_ec_key(ec_key: EcKey) -> Result, ErrorStack> { unsafe { let evp = cvt_p(ffi::EVP_PKEY_new())?; @@ -366,26 +322,17 @@ impl PKey { impl PKey { private_key_from_pem! { /// Deserializes a private key from a PEM-encoded key type specific format. - /// - /// This corresponds to [`PEM_read_bio_PrivateKey`]. - /// - /// [`PEM_read_bio_PrivateKey`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_read_bio_PrivateKey.html + #[corresponds(PEM_read_bio_PrivateKey)] private_key_from_pem, /// Deserializes a private key from a PEM-encoded encrypted key type specific format. - /// - /// This corresponds to [`PEM_read_bio_PrivateKey`]. - /// - /// [`PEM_read_bio_PrivateKey`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_read_bio_PrivateKey.html + #[corresponds(PEM_read_bio_PrivateKey)] private_key_from_pem_passphrase, /// Deserializes a private key from a PEM-encoded encrypted key type specific format. /// /// The callback should fill the password into the provided buffer and return its length. - /// - /// This corresponds to [`PEM_read_bio_PrivateKey`]. - /// - /// [`PEM_read_bio_PrivateKey`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_read_bio_PrivateKey.html + #[corresponds(PEM_read_bio_PrivateKey)] private_key_from_pem_callback, PKey, ffi::PEM_read_bio_PrivateKey @@ -397,10 +344,7 @@ impl PKey { /// This function will automatically attempt to detect the underlying key format, and /// supports the unencrypted PKCS#8 PrivateKeyInfo structures as well as key type specific /// formats. - /// - /// This corresponds to [`d2i_AutoPrivateKey`]. - /// - /// [`d2i_AutoPrivateKey`]: https://www.openssl.org/docs/man1.0.2/crypto/d2i_AutoPrivateKey.html + #[corresponds(d2i_AutoPrivateKey)] private_key_from_der, PKey, ffi::d2i_AutoPrivateKey, @@ -481,10 +425,7 @@ impl PKey { /// Decodes a PEM-encoded SubjectPublicKeyInfo structure. /// /// The input should have a header of `-----BEGIN PUBLIC KEY-----`. - /// - /// This corresponds to [`PEM_read_bio_PUBKEY`]. - /// - /// [`PEM_read_bio_PUBKEY`]: https://www.openssl.org/docs/man1.0.2/crypto/PEM_read_bio_PUBKEY.html + #[corresponds(PEM_read_bio_PUBKEY)] public_key_from_pem, PKey, ffi::PEM_read_bio_PUBKEY @@ -492,10 +433,7 @@ impl PKey { from_der! { /// Decodes a DER-encoded SubjectPublicKeyInfo structure. - /// - /// This corresponds to [`d2i_PUBKEY`]. - /// - /// [`d2i_PUBKEY`]: https://www.openssl.org/docs/man1.1.0/crypto/d2i_PUBKEY.html + #[corresponds(d2i_PUBKEY)] public_key_from_der, PKey, ffi::d2i_PUBKEY, diff --git a/boring/src/rsa.rs b/boring/src/rsa.rs index 5b85e9e1..7bb641fb 100644 --- a/boring/src/rsa.rs +++ b/boring/src/rsa.rs @@ -26,6 +26,7 @@ use crate::ffi; use foreign_types::{ForeignType, ForeignTypeRef}; use libc::c_int; +use openssl_macros::corresponds; use std::fmt; use std::mem; use std::ptr; @@ -113,28 +114,19 @@ where /// Serializes the private key to a PEM-encoded PKCS#1 RSAPrivateKey structure. /// /// The output will have a header of `-----BEGIN RSA PRIVATE KEY-----`. - /// - /// This corresponds to [`PEM_write_bio_RSAPrivateKey`]. - /// - /// [`PEM_write_bio_RSAPrivateKey`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_write_bio_RSAPrivateKey.html + #[corresponds(PEM_write_bio_RSAPrivateKey)] private_key_to_pem, /// Serializes the private key to a PEM-encoded encrypted PKCS#1 RSAPrivateKey structure. /// /// The output will have a header of `-----BEGIN RSA PRIVATE KEY-----`. - /// - /// This corresponds to [`PEM_write_bio_RSAPrivateKey`]. - /// - /// [`PEM_write_bio_RSAPrivateKey`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_write_bio_RSAPrivateKey.html + #[corresponds(PEM_write_bio_RSAPrivateKey)] private_key_to_pem_passphrase, ffi::PEM_write_bio_RSAPrivateKey } to_der! { /// Serializes the private key to a DER-encoded PKCS#1 RSAPrivateKey structure. - /// - /// This corresponds to [`i2d_RSAPrivateKey`]. - /// - /// [`i2d_RSAPrivateKey`]: https://www.openssl.org/docs/man1.0.2/crypto/i2d_RSAPrivateKey.html + #[corresponds(i2d_RSAPrivateKey)] private_key_to_der, ffi::i2d_RSAPrivateKey } @@ -194,10 +186,7 @@ where } /// Returns a reference to the private exponent of the key. - /// - /// This corresponds to [`RSA_get0_key`]. - /// - /// [`RSA_get0_key`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_get0_key.html + #[corresponds(RSA_get0_key)] pub fn d(&self) -> &BigNumRef { unsafe { let mut d = ptr::null(); @@ -207,10 +196,7 @@ where } /// Returns a reference to the first factor of the exponent of the key. - /// - /// This corresponds to [`RSA_get0_factors`]. - /// - /// [`RSA_get0_factors`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_get0_key.html + #[corresponds(RSA_get0_factors)] pub fn p(&self) -> Option<&BigNumRef> { unsafe { let mut p = ptr::null(); @@ -224,10 +210,7 @@ where } /// Returns a reference to the second factor of the exponent of the key. - /// - /// This corresponds to [`RSA_get0_factors`]. - /// - /// [`RSA_get0_factors`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_get0_key.html + #[corresponds(RSA_get0_factors)] pub fn q(&self) -> Option<&BigNumRef> { unsafe { let mut q = ptr::null(); @@ -241,10 +224,7 @@ where } /// Returns a reference to the first exponent used for CRT calculations. - /// - /// This corresponds to [`RSA_get0_crt_params`]. - /// - /// [`RSA_get0_crt_params`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_get0_key.html + #[corresponds(RSA_get0_crt_params)] pub fn dmp1(&self) -> Option<&BigNumRef> { unsafe { let mut dp = ptr::null(); @@ -258,10 +238,7 @@ where } /// Returns a reference to the second exponent used for CRT calculations. - /// - /// This corresponds to [`RSA_get0_crt_params`]. - /// - /// [`RSA_get0_crt_params`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_get0_key.html + #[corresponds(RSA_get0_crt_params)] pub fn dmq1(&self) -> Option<&BigNumRef> { unsafe { let mut dq = ptr::null(); @@ -275,10 +252,7 @@ where } /// Returns a reference to the coefficient used for CRT calculations. - /// - /// This corresponds to [`RSA_get0_crt_params`]. - /// - /// [`RSA_get0_crt_params`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_get0_key.html + #[corresponds(RSA_get0_crt_params)] pub fn iqmp(&self) -> Option<&BigNumRef> { unsafe { let mut qi = ptr::null(); @@ -292,10 +266,7 @@ where } /// Validates RSA parameters for correctness - /// - /// This corresponds to [`RSA_check_key`]. - /// - /// [`RSA_check_key`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_check_key.html + #[corresponds(RSA_check_key)] #[allow(clippy::unnecessary_cast)] pub fn check_key(&self) -> Result { unsafe { @@ -317,20 +288,14 @@ where /// Serializes the public key into a PEM-encoded SubjectPublicKeyInfo structure. /// /// The output will have a header of `-----BEGIN PUBLIC KEY-----`. - /// - /// This corresponds to [`PEM_write_bio_RSA_PUBKEY`]. - /// - /// [`PEM_write_bio_RSA_PUBKEY`]: https://www.openssl.org/docs/man1.0.2/crypto/pem.html + #[corresponds(PEM_write_bio_RSA_PUBKEY)] public_key_to_pem, ffi::PEM_write_bio_RSA_PUBKEY } to_der! { /// Serializes the public key into a DER-encoded SubjectPublicKeyInfo structure. - /// - /// This corresponds to [`i2d_RSA_PUBKEY`]. - /// - /// [`i2d_RSA_PUBKEY`]: https://www.openssl.org/docs/man1.1.0/crypto/i2d_RSA_PUBKEY.html + #[corresponds(i2d_RSA_PUBKEY)] public_key_to_der, ffi::i2d_RSA_PUBKEY } @@ -339,29 +304,20 @@ where /// Serializes the public key into a PEM-encoded PKCS#1 RSAPublicKey structure. /// /// The output will have a header of `-----BEGIN RSA PUBLIC KEY-----`. - /// - /// This corresponds to [`PEM_write_bio_RSAPublicKey`]. - /// - /// [`PEM_write_bio_RSAPublicKey`]: https://www.openssl.org/docs/man1.0.2/crypto/pem.html + #[corresponds(PEM_write_bio_RSAPublicKey)] public_key_to_pem_pkcs1, ffi::PEM_write_bio_RSAPublicKey } to_der! { /// Serializes the public key into a DER-encoded PKCS#1 RSAPublicKey structure. - /// - /// This corresponds to [`i2d_RSAPublicKey`]. - /// - /// [`i2d_RSAPublicKey`]: https://www.openssl.org/docs/man1.0.2/crypto/i2d_RSAPublicKey.html + #[corresponds(i2d_RSAPublicKey)] public_key_to_der_pkcs1, ffi::i2d_RSAPublicKey } /// Returns the size of the modulus in bytes. - /// - /// This corresponds to [`RSA_size`]. - /// - /// [`RSA_size`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_size.html + #[corresponds(RSA_size)] #[allow(clippy::unnecessary_cast)] pub fn size(&self) -> u32 { unsafe { ffi::RSA_size(self.as_ptr()) as u32 } @@ -420,10 +376,7 @@ where } /// Returns a reference to the modulus of the key. - /// - /// This corresponds to [`RSA_get0_key`]. - /// - /// [`RSA_get0_key`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_get0_key.html + #[corresponds(RSA_get0_key)] pub fn n(&self) -> &BigNumRef { unsafe { let mut n = ptr::null(); @@ -433,10 +386,7 @@ where } /// Returns a reference to the public exponent of the key. - /// - /// This corresponds to [`RSA_get0_key`]. - /// - /// [`RSA_get0_key`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_get0_key.html + #[corresponds(RSA_get0_key)] pub fn e(&self) -> &BigNumRef { unsafe { let mut e = ptr::null(); @@ -451,10 +401,7 @@ impl Rsa { /// /// `n` is the modulus common to both public and private key. /// `e` is the public exponent. - /// - /// This corresponds to [`RSA_new`] and uses [`RSA_set0_key`]. - /// - /// [`RSA_new`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_new.html + #[corresponds(RSA_new)] /// [`RSA_set0_key`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_set0_key.html pub fn from_public_components(n: BigNum, e: BigNum) -> Result, ErrorStack> { unsafe { @@ -469,10 +416,7 @@ impl Rsa { /// Decodes a PEM-encoded SubjectPublicKeyInfo structure containing an RSA key. /// /// The input should have a header of `-----BEGIN PUBLIC KEY-----`. - /// - /// This corresponds to [`PEM_read_bio_RSA_PUBKEY`]. - /// - /// [`PEM_read_bio_RSA_PUBKEY`]: https://www.openssl.org/docs/man1.0.2/crypto/PEM_read_bio_RSA_PUBKEY.html + #[corresponds(PEM_read_bio_RSA_PUBKEY)] public_key_from_pem, Rsa, ffi::PEM_read_bio_RSA_PUBKEY @@ -482,10 +426,7 @@ impl Rsa { /// Decodes a PEM-encoded PKCS#1 RSAPublicKey structure. /// /// The input should have a header of `-----BEGIN RSA PUBLIC KEY-----`. - /// - /// This corresponds to [`PEM_read_bio_RSAPublicKey`]. - /// - /// [`PEM_read_bio_RSAPublicKey`]: https://www.openssl.org/docs/man1.0.2/crypto/PEM_read_bio_RSAPublicKey.html + #[corresponds(PEM_read_bio_RSAPublicKey)] public_key_from_pem_pkcs1, Rsa, ffi::PEM_read_bio_RSAPublicKey @@ -493,10 +434,7 @@ impl Rsa { from_der! { /// Decodes a DER-encoded SubjectPublicKeyInfo structure containing an RSA key. - /// - /// This corresponds to [`d2i_RSA_PUBKEY`]. - /// - /// [`d2i_RSA_PUBKEY`]: https://www.openssl.org/docs/man1.0.2/crypto/d2i_RSA_PUBKEY.html + #[corresponds(d2i_RSA_PUBKEY)] public_key_from_der, Rsa, ffi::d2i_RSA_PUBKEY, @@ -505,10 +443,7 @@ impl Rsa { from_der! { /// Decodes a DER-encoded PKCS#1 RSAPublicKey structure. - /// - /// This corresponds to [`d2i_RSAPublicKey`]. - /// - /// [`d2i_RSAPublicKey`]: https://www.openssl.org/docs/man1.0.2/crypto/d2i_RSA_PUBKEY.html + #[corresponds(d2i_RSAPublicKey)] public_key_from_der_pkcs1, Rsa, ffi::d2i_RSAPublicKey, @@ -525,10 +460,7 @@ impl RsaPrivateKeyBuilder { /// /// `n` is the modulus common to both public and private key. /// `e` is the public exponent and `d` is the private exponent. - /// - /// This corresponds to [`RSA_new`] and uses [`RSA_set0_key`]. - /// - /// [`RSA_new`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_new.html + #[corresponds(RSA_new)] /// [`RSA_set0_key`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_set0_key.html pub fn new(n: BigNum, e: BigNum, d: BigNum) -> Result { unsafe { @@ -545,10 +477,8 @@ impl RsaPrivateKeyBuilder { /// /// `p` and `q` are the first and second factors of `n`. /// - /// This correspond to [`RSA_set0_factors`]. - /// - /// [`RSA_set0_factors`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_set0_factors.html // FIXME should be infallible + #[corresponds(RSA_set0_factors)] pub fn set_factors(self, p: BigNum, q: BigNum) -> Result { unsafe { RSA_set0_factors(self.rsa.as_ptr(), p.as_ptr(), q.as_ptr()); @@ -562,10 +492,8 @@ impl RsaPrivateKeyBuilder { /// `dmp1`, `dmq1`, and `iqmp` are the exponents and coefficient for /// CRT calculations which is used to speed up RSA operations. /// - /// This correspond to [`RSA_set0_crt_params`]. - /// - /// [`RSA_set0_crt_params`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_set0_crt_params.html // FIXME should be infallible + #[corresponds(RSA_set0_crt_params)] pub fn set_crt_params( self, dmp1: BigNum, @@ -615,10 +543,7 @@ impl Rsa { /// Generates a public/private key pair with the specified size. /// /// The public exponent will be 65537. - /// - /// This corresponds to [`RSA_generate_key_ex`]. - /// - /// [`RSA_generate_key_ex`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_generate_key_ex.html + #[corresponds(RSA_generate_key_ex)] pub fn generate(bits: u32) -> Result, ErrorStack> { let e = BigNum::from_u32(ffi::RSA_F4 as u32)?; Rsa::generate_with_e(bits, &e) @@ -627,10 +552,7 @@ impl Rsa { /// Generates a public/private key pair with the specified size and a custom exponent. /// /// Unless you have specific needs and know what you're doing, use `Rsa::generate` instead. - /// - /// This corresponds to [`RSA_generate_key_ex`]. - /// - /// [`RSA_generate_key_ex`]: https://www.openssl.org/docs/man1.1.0/crypto/RSA_generate_key_ex.html + #[corresponds(RSA_generate_key_ex)] pub fn generate_with_e(bits: u32, e: &BigNumRef) -> Result, ErrorStack> { unsafe { let rsa = Rsa::from_ptr(cvt_p(ffi::RSA_new())?); @@ -647,26 +569,17 @@ impl Rsa { // FIXME these need to identify input formats private_key_from_pem! { /// Deserializes a private key from a PEM-encoded PKCS#1 RSAPrivateKey structure. - /// - /// This corresponds to [`PEM_read_bio_RSAPrivateKey`]. - /// - /// [`PEM_read_bio_RSAPrivateKey`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_read_bio_RSAPrivateKey.html + #[corresponds(PEM_read_bio_RSAPrivateKey)] private_key_from_pem, /// Deserializes a private key from a PEM-encoded encrypted PKCS#1 RSAPrivateKey structure. - /// - /// This corresponds to [`PEM_read_bio_RSAPrivateKey`]. - /// - /// [`PEM_read_bio_RSAPrivateKey`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_read_bio_RSAPrivateKey.html + #[corresponds(PEM_read_bio_RSAPrivateKey)] private_key_from_pem_passphrase, /// Deserializes a private key from a PEM-encoded encrypted PKCS#1 RSAPrivateKey structure. /// /// The callback should fill the password into the provided buffer and return its length. - /// - /// This corresponds to [`PEM_read_bio_RSAPrivateKey`]. - /// - /// [`PEM_read_bio_RSAPrivateKey`]: https://www.openssl.org/docs/man1.1.0/crypto/PEM_read_bio_RSAPrivateKey.html + #[corresponds(PEM_read_bio_RSAPrivateKey)] private_key_from_pem_callback, Rsa, ffi::PEM_read_bio_RSAPrivateKey @@ -674,10 +587,7 @@ impl Rsa { from_der! { /// Decodes a DER-encoded PKCS#1 RSAPrivateKey structure. - /// - /// This corresponds to [`d2i_RSAPrivateKey`]. - /// - /// [`d2i_RSAPrivateKey`]: https://www.openssl.org/docs/man1.0.2/crypto/d2i_RSA_PUBKEY.html + #[corresponds(d2i_RSAPrivateKey)] private_key_from_der, Rsa, ffi::d2i_RSAPrivateKey, diff --git a/boring/src/sign.rs b/boring/src/sign.rs index ee68bc7d..89e7ba1c 100644 --- a/boring/src/sign.rs +++ b/boring/src/sign.rs @@ -37,6 +37,7 @@ use crate::ffi; use foreign_types::ForeignTypeRef; use libc::c_int; +use openssl_macros::corresponds; use std::io::{self, Write}; use std::marker::PhantomData; use std::ptr; @@ -96,10 +97,7 @@ impl<'a> Signer<'a> { /// /// 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(type_: MessageDigest, pkey: &'a PKeyRef) -> Result, ErrorStack> where T: HasPrivate, @@ -111,10 +109,7 @@ impl<'a> Signer<'a> { /// /// 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(pkey: &'a PKeyRef) -> Result, ErrorStack> where T: HasPrivate, @@ -159,8 +154,7 @@ impl<'a> Signer<'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 { unsafe { let mut pad = 0; @@ -172,10 +166,7 @@ impl<'a> Signer<'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/man1.1.0/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( @@ -189,10 +180,7 @@ impl<'a> Signer<'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/man1.1.0/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( @@ -206,10 +194,7 @@ impl<'a> Signer<'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( @@ -224,10 +209,7 @@ impl<'a> Signer<'a> { /// /// 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( @@ -243,10 +225,7 @@ impl<'a> Signer<'a> { /// /// 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/man1.1.0/crypto/EVP_DigestSignFinal.html + #[corresponds(EVP_DigestSignFinal)] pub fn len(&self) -> Result { self.len_intern() } @@ -269,10 +248,7 @@ impl<'a> Signer<'a> { /// /// 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/man1.1.0/crypto/EVP_DigestSignFinal.html + #[corresponds(EVP_DigestSignFinal)] pub fn sign(&self, buf: &mut [u8]) -> Result { unsafe { let mut len = buf.len(); @@ -303,10 +279,7 @@ impl<'a> Signer<'a> { /// /// 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)] pub fn sign_oneshot( &mut self, sig_buf: &mut [u8], @@ -372,10 +345,7 @@ impl<'a> Verifier<'a> { /// /// This cannot be used with Ed25519 or Ed448 keys. Please refer to /// `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(type_: MessageDigest, pkey: &'a PKeyRef) -> Result, ErrorStack> where T: HasPublic, @@ -386,10 +356,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(pkey: &'a PKeyRef) -> Result, ErrorStack> where T: HasPublic, @@ -434,8 +401,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 { unsafe { let mut pad = 0; @@ -447,10 +413,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/man1.1.0/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( @@ -464,10 +427,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/man1.1.0/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( @@ -481,10 +441,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( @@ -499,10 +456,7 @@ impl<'a> Verifier<'a> { /// /// Please note that PureEdDSA (Ed25519 and Ed448 keys) do not support streaming. /// Use `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( @@ -515,10 +469,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 { unsafe { let r = @@ -535,10 +486,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)] pub fn verify_oneshot(&mut self, signature: &[u8], buf: &[u8]) -> Result { unsafe { let r = ffi::EVP_DigestVerify( diff --git a/boring/src/ssl/mod.rs b/boring/src/ssl/mod.rs index abf92716..9d136388 100644 --- a/boring/src/ssl/mod.rs +++ b/boring/src/ssl/mod.rs @@ -801,10 +801,6 @@ impl SslCurve { pub const P256_KYBER768_DRAFT00: SslCurve = SslCurve(ffi::SSL_CURVE_P256_KYBER768_DRAFT00 as _); /// Returns the curve name - /// - /// 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 { @@ -881,10 +877,8 @@ impl CompliancePolicy { /// /// It will select the first protocol supported by the server which is also supported by the client. /// -/// This corresponds to [`SSL_select_next_proto`]. -/// /// [`SslContextBuilder::set_alpn_protos`]: struct.SslContextBuilder.html#method.set_alpn_protos -/// [`SSL_select_next_proto`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_alpn_protos.html +#[corresponds(SSL_select_next_proto)] pub fn select_next_proto<'a>(server: &[u8], client: &'a [u8]) -> Option<&'a [u8]> { if server.is_empty() || client.is_empty() { return None; @@ -2287,10 +2281,7 @@ pub struct ClientHello<'ssl>(&'ssl ffi::SSL_CLIENT_HELLO); impl ClientHello<'_> { /// Returns the data of a given extension, if present. - /// - /// This corresponds to [`SSL_early_callback_ctx_extension_get`]. - /// - /// [`SSL_early_callback_ctx_extension_get`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_early_callback_ctx_extension_get + #[corresponds(SSL_early_callback_ctx_extension_get)] pub fn get_extension(&self, ext_type: ExtensionType) -> Option<&[u8]> { unsafe { let mut ptr = ptr::null(); @@ -2509,10 +2500,7 @@ impl Clone for SslSession { impl SslSession { from_der! { /// Deserializes a DER-encoded session structure. - /// - /// This corresponds to [`d2i_SSL_SESSION`]. - /// - /// [`d2i_SSL_SESSION`]: https://www.openssl.org/docs/man1.0.2/ssl/d2i_SSL_SESSION.html + #[corresponds(d2i_SSL_SESSION)] from_der, SslSession, ffi::d2i_SSL_SESSION, @@ -2583,10 +2571,7 @@ impl SslSessionRef { to_der! { /// Serializes the session into a DER-encoded structure. - /// - /// This corresponds to [`i2d_SSL_SESSION`]. - /// - /// [`i2d_SSL_SESSION`]: https://www.openssl.org/docs/man1.0.2/ssl/i2d_SSL_SESSION.html + #[corresponds(i2d_SSL_SESSION)] to_der, ffi::i2d_SSL_SESSION } @@ -2928,10 +2913,7 @@ impl SslRef { } /// Configures whether ClientHello extensions should be permuted. - /// - /// This corresponds to [`SSL_set_permute_extensions`]. - /// - /// [`SSL_set_permute_extensions`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_set_permute_extensions + #[corresponds(SSL_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. @@ -3720,10 +3702,7 @@ impl MidHandshakeSslStream { } /// 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, HandshakeError> { let ret = unsafe { ffi::SSL_do_handshake(self.stream.ssl.as_ptr()) }; if ret > 0 { diff --git a/boring/src/symm.rs b/boring/src/symm.rs index 6e230f0d..1df9a77c 100644 --- a/boring/src/symm.rs +++ b/boring/src/symm.rs @@ -54,6 +54,7 @@ use crate::ffi; use libc::{c_int, c_uint}; +use openssl_macros::corresponds; use std::cmp; use std::ptr; @@ -77,10 +78,7 @@ pub struct Cipher(*const ffi::EVP_CIPHER); impl Cipher { /// Looks up the cipher for a certain nid. - /// - /// This corresponds to [`EVP_get_cipherbynid`] - /// - /// [`EVP_get_cipherbynid`]: https://www.openssl.org/docs/man1.0.2/crypto/EVP_get_cipherbyname.html + #[corresponds(EVP_get_cipherbynid)] pub fn from_nid(nid: Nid) -> Option { let ptr = unsafe { ffi::EVP_get_cipherbyname(ffi::OBJ_nid2sn(nid.as_raw())) }; if ptr.is_null() { diff --git a/boring/src/x509/mod.rs b/boring/src/x509/mod.rs index c09f4df8..f4a44ee5 100644 --- a/boring/src/x509/mod.rs +++ b/boring/src/x509/mod.rs @@ -864,10 +864,7 @@ impl X509NameBuilder { } /// Add a field entry by str. - /// - /// This corresponds to [`X509_NAME_add_entry_by_txt`]. - /// - /// [`X509_NAME_add_entry_by_txt`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_NAME_add_entry_by_txt.html + #[corresponds(X509_NAME_add_entry_by_txt)] pub fn append_entry_by_text(&mut self, field: &str, value: &str) -> Result<(), ErrorStack> { unsafe { let field = CString::new(field).unwrap(); @@ -886,10 +883,7 @@ impl X509NameBuilder { } /// Add a field entry by str with a specific type. - /// - /// This corresponds to [`X509_NAME_add_entry_by_txt`]. - /// - /// [`X509_NAME_add_entry_by_txt`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_NAME_add_entry_by_txt.html + #[corresponds(X509_NAME_add_entry_by_txt)] pub fn append_entry_by_text_with_type( &mut self, field: &str, @@ -913,10 +907,7 @@ impl X509NameBuilder { } /// Add a field entry by NID. - /// - /// This corresponds to [`X509_NAME_add_entry_by_NID`]. - /// - /// [`X509_NAME_add_entry_by_NID`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_NAME_add_entry_by_NID.html + #[corresponds(X509_NAME_add_entry_by_NID)] pub fn append_entry_by_nid(&mut self, field: Nid, value: &str) -> Result<(), ErrorStack> { unsafe { assert!(value.len() <= ValueLen::MAX as usize); @@ -934,10 +925,7 @@ impl X509NameBuilder { } /// Add a field entry by NID with a specific type. - /// - /// This corresponds to [`X509_NAME_add_entry_by_NID`]. - /// - /// [`X509_NAME_add_entry_by_NID`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_NAME_add_entry_by_NID.html + #[corresponds(X509_NAME_add_entry_by_NID)] pub fn append_entry_by_nid_with_type( &mut self, field: Nid, @@ -997,10 +985,7 @@ impl X509Name { from_der! { /// Deserializes a DER-encoded X509 name structure. - /// - /// This corresponds to [`d2i_X509_NAME`]. - /// - /// [`d2i_X509_NAME`]: https://www.openssl.org/docs/manmaster/man3/d2i_X509_NAME.html + #[corresponds(d2i_X509_NAME)] from_der, X509Name, ffi::d2i_X509_NAME, @@ -1047,10 +1032,7 @@ impl X509NameRef { to_der! { /// Serializes the certificate into a DER-encoded X509 name structure. - /// - /// This corresponds to [`i2d_X509_NAME`]. - /// - /// [`i2d_X509_NAME`]: https://www.openssl.org/docs/man1.1.0/crypto/i2d_X509_NAME.html + #[corresponds(i2d_X509_NAME)] to_der, ffi::i2d_X509_NAME } @@ -1110,10 +1092,7 @@ foreign_type_and_impl_send_sync! { impl X509NameEntryRef { /// Returns the field value of an `X509NameEntry`. - /// - /// This corresponds to [`X509_NAME_ENTRY_get_data`]. - /// - /// [`X509_NAME_ENTRY_get_data`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_NAME_ENTRY_get_data.html + #[corresponds(X509_NAME_ENTRY_get_data)] pub fn data(&self) -> &Asn1StringRef { unsafe { let data = ffi::X509_NAME_ENTRY_get_data(self.as_ptr()); @@ -1123,10 +1102,7 @@ impl X509NameEntryRef { /// Returns the `Asn1Object` value of an `X509NameEntry`. /// This is useful for finding out about the actual `Nid` when iterating over all `X509NameEntries`. - /// - /// This corresponds to [`X509_NAME_ENTRY_get_object`]. - /// - /// [`X509_NAME_ENTRY_get_object`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_NAME_ENTRY_get_object.html + #[corresponds(X509_NAME_ENTRY_get_object)] pub fn object(&self) -> &Asn1ObjectRef { unsafe { let object = ffi::X509_NAME_ENTRY_get_object(self.as_ptr()); @@ -1167,10 +1143,7 @@ impl X509ReqBuilder { } /// Set the issuer name. - /// - /// This corresponds to [`X509_REQ_set_subject_name`]. - /// - /// [`X509_REQ_set_subject_name`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_REQ_set_subject_name.html + #[corresponds(X509_REQ_set_subject_name)] pub fn set_subject_name(&mut self, subject_name: &X509NameRef) -> Result<(), ErrorStack> { unsafe { cvt(ffi::X509_REQ_set_subject_name( @@ -1182,10 +1155,7 @@ impl X509ReqBuilder { } /// Set the public key. - /// - /// This corresponds to [`X509_REQ_set_pubkey`]. - /// - /// [`X509_REQ_set_pubkey`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_REQ_set_pubkey.html + #[corresponds(X509_REQ_set_pubkey)] pub fn set_pubkey(&mut self, key: &PKeyRef) -> Result<(), ErrorStack> where T: HasPublic, @@ -1232,10 +1202,7 @@ impl X509ReqBuilder { } /// Sign the request using a private key. - /// - /// This corresponds to [`X509_REQ_sign`]. - /// - /// [`X509_REQ_sign`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_REQ_sign.html + #[corresponds(X509_REQ_sign)] pub fn sign(&mut self, key: &PKeyRef, hash: MessageDigest) -> Result<(), ErrorStack> where T: HasPrivate, @@ -1274,10 +1241,7 @@ impl X509Req { /// Deserializes a PEM-encoded PKCS#10 certificate request structure. /// /// The input should have a header of `-----BEGIN CERTIFICATE REQUEST-----`. - /// - /// This corresponds to [`PEM_read_bio_X509_REQ`]. - /// - /// [`PEM_read_bio_X509_REQ`]: https://www.openssl.org/docs/man1.0.2/crypto/PEM_read_bio_X509_REQ.html + #[corresponds(PEM_read_bio_X509_REQ)] from_pem, X509Req, ffi::PEM_read_bio_X509_REQ @@ -1285,10 +1249,7 @@ impl X509Req { from_der! { /// Deserializes a DER-encoded PKCS#10 certificate request structure. - /// - /// This corresponds to [`d2i_X509_REQ`]. - /// - /// [`d2i_X509_REQ`]: https://www.openssl.org/docs/man1.1.0/crypto/d2i_X509_REQ.html + #[corresponds(d2i_X509_REQ)] from_der, X509Req, ffi::d2i_X509_REQ, @@ -1301,38 +1262,26 @@ impl X509ReqRef { /// Serializes the certificate request to a PEM-encoded PKCS#10 structure. /// /// The output will have a header of `-----BEGIN CERTIFICATE REQUEST-----`. - /// - /// This corresponds to [`PEM_write_bio_X509_REQ`]. - /// - /// [`PEM_write_bio_X509_REQ`]: https://www.openssl.org/docs/man1.0.2/crypto/PEM_write_bio_X509_REQ.html + #[corresponds(PEM_write_bio_X509_REQ)] to_pem, ffi::PEM_write_bio_X509_REQ } to_der! { /// Serializes the certificate request to a DER-encoded PKCS#10 structure. - /// - /// This corresponds to [`i2d_X509_REQ`]. - /// - /// [`i2d_X509_REQ`]: https://www.openssl.org/docs/man1.0.2/crypto/i2d_X509_REQ.html + #[corresponds(i2d_X509_REQ)] to_der, ffi::i2d_X509_REQ } /// Returns the numerical value of the version field of the certificate request. - /// - /// This corresponds to [`X509_REQ_get_version`] - /// - /// [`X509_REQ_get_version`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_REQ_get_version.html + #[corresponds(X509_REQ_get_version)] pub fn version(&self) -> i32 { unsafe { X509_REQ_get_version(self.as_ptr()) as i32 } } /// Returns the subject name of the certificate request. - /// - /// This corresponds to [`X509_REQ_get_subject_name`] - /// - /// [`X509_REQ_get_subject_name`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_REQ_get_subject_name.html + #[corresponds(X509_REQ_get_subject_name)] pub fn subject_name(&self) -> &X509NameRef { unsafe { let name = X509_REQ_get_subject_name(self.as_ptr()); @@ -1423,10 +1372,7 @@ impl X509VerifyError { } /// Return a human readable error string from the verification error. - /// - /// This corresponds to [`X509_verify_cert_error_string`]. - /// - /// [`X509_verify_cert_error_string`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_verify_cert_error_string.html + #[corresponds(X509_verify_cert_error_string)] #[allow(clippy::trivially_copy_pass_by_ref)] pub fn error_string(&self) -> &'static str { ffi::init(); diff --git a/boring/src/x509/store.rs b/boring/src/x509/store.rs index 068c759c..0f626838 100644 --- a/boring/src/x509/store.rs +++ b/boring/src/x509/store.rs @@ -105,10 +105,7 @@ impl X509StoreBuilderRef { } /// Returns a mutable reference to the X509 verification configuration. - /// - /// This corresponds to [`X509_STORE_get0_param`]. - /// - /// [`SSL_get0_param`]: https://www.openssl.org/docs/manmaster/man3/X509_STORE_get0_param.html + #[corresponds(X509_STORE_get0_param)] pub fn verify_param_mut(&mut self) -> &mut X509VerifyParamRef { unsafe { X509VerifyParamRef::from_ptr_mut(ffi::X509_STORE_get0_param(self.as_ptr())) } }