diff --git a/Cargo.toml b/Cargo.toml index 3836084b..e8bf6e38 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -40,5 +40,6 @@ http = "0.2" hyper = { version = "0.14", default-features = false } linked_hash_set = "0.1" once_cell = "1.0" +openssl-macros = "0.1.1" tower = "0.4" tower-layer = "0.3" diff --git a/boring/Cargo.toml b/boring/Cargo.toml index 0a576ab4..a558eefa 100644 --- a/boring/Cargo.toml +++ b/boring/Cargo.toml @@ -69,6 +69,7 @@ kx-client-nist-required = ["kx-safe-default"] bitflags = { workspace = true } foreign-types = { workspace = true } once_cell = { workspace = true } +openssl-macros = { workspace = true } libc = { workspace = true } boring-sys = { workspace = true } diff --git a/boring/src/ssl/mod.rs b/boring/src/ssl/mod.rs index 83b616a6..12ffedf5 100644 --- a/boring/src/ssl/mod.rs +++ b/boring/src/ssl/mod.rs @@ -57,10 +57,10 @@ //! } //! } //! ``` -use crate::ffi; use foreign_types::{ForeignType, ForeignTypeRef, Opaque}; use libc::{c_char, c_int, c_long, c_uchar, c_uint, c_void}; use once_cell::sync::Lazy; +use openssl_macros::corresponds; use std::any::TypeId; use std::collections::HashMap; use std::convert::TryInto; @@ -82,6 +82,7 @@ use crate::dh::DhRef; use crate::ec::EcKeyRef; use crate::error::ErrorStack; use crate::ex_data::Index; +use crate::ffi; use crate::nid::Nid; use crate::pkey::{HasPrivate, PKeyRef, Params, Private}; use crate::srtp::{SrtpProtectionProfile, SrtpProtectionProfileRef}; @@ -243,9 +244,7 @@ pub struct SslMethod(*const ffi::SSL_METHOD); impl SslMethod { /// Support all versions of the TLS protocol. - /// - /// This corresponds to `TLS_method` on OpenSSL 1.1.0 and `SSLv23_method` - /// on OpenSSL 1.0.x. + #[corresponds(TLS_method)] pub fn tls() -> SslMethod { unsafe { SslMethod(TLS_method()) } } @@ -257,25 +256,19 @@ impl SslMethod { } /// Support all versions of the DTLS protocol. - /// - /// This corresponds to `DTLS_method` on OpenSSL 1.1.0 and `DTLSv1_method` - /// on OpenSSL 1.0.x. + #[corresponds(DTLS_method)] pub fn dtls() -> SslMethod { unsafe { SslMethod(DTLS_method()) } } /// Support all versions of the TLS protocol, explicitly as a client. - /// - /// This corresponds to `TLS_client_method` on OpenSSL 1.1.0 and - /// `SSLv23_client_method` on OpenSSL 1.0.x. + #[corresponds(TLS_client_method)] pub fn tls_client() -> SslMethod { unsafe { SslMethod(TLS_client_method()) } } /// Support all versions of the TLS protocol, explicitly as a server. - /// - /// This corresponds to `TLS_server_method` on OpenSSL 1.1.0 and - /// `SSLv23_server_method` on OpenSSL 1.0.x. + #[corresponds(TLS_server_method)] pub fn tls_server() -> SslMethod { unsafe { SslMethod(TLS_server_method()) } } @@ -285,6 +278,7 @@ impl SslMethod { /// # Safety /// /// The caller must ensure the pointer is valid. + #[corresponds(TLS_server_method)] pub unsafe fn from_ptr(ptr: *const ffi::SSL_METHOD) -> SslMethod { SslMethod(ptr) } @@ -737,6 +731,7 @@ impl SslCurve { /// 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 { let ptr = ffi::SSL_get_curve_name(self.0 as u16); @@ -858,10 +853,7 @@ pub struct SslContextBuilder { #[cfg(feature = "rpk")] impl SslContextBuilder { /// Creates a new `SslContextBuilder` to be used with Raw Public Key. - /// - /// This corresponds to [`SSL_CTX_new`]. - /// - /// [`SSL_CTX_new`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_new.html + #[corresponds(SSL_CTX_new)] pub fn new_rpk() -> Result { unsafe { init(); @@ -901,10 +893,7 @@ impl SslContextBuilder { impl SslContextBuilder { /// Creates a new `SslContextBuilder`. - /// - /// This corresponds to [`SSL_CTX_new`]. - /// - /// [`SSL_CTX_new`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_new.html + #[corresponds(SSL_CTX_new)] pub fn new(method: SslMethod) -> Result { unsafe { init(); @@ -955,10 +944,7 @@ impl SslContextBuilder { } /// Configures the certificate verification method for new connections. - /// - /// This corresponds to [`SSL_CTX_set_verify`]. - /// - /// [`SSL_CTX_set_verify`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_verify.html + #[corresponds(SSL_CTX_set_verify)] pub fn set_verify(&mut self, mode: SslVerifyMode) { #[cfg(feature = "rpk")] assert!(!self.is_rpk, "This API is not supported for RPK"); @@ -981,13 +967,10 @@ impl SslContextBuilder { /// Those callbacks can inspect the peer-sent chain, call [`X509StoreContextRef::verify_cert`] /// and inspect the result, or perform other operations more straightforwardly. /// - /// This corresponds to [`SSL_CTX_set_verify`]. - /// /// # Panics /// /// This method panics if this `Ssl` is associated with a RPK context. - /// - /// [`SSL_CTX_set_verify`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_verify.html + #[corresponds(SSL_CTX_set_verify)] pub fn set_verify_callback(&mut self, mode: SslVerifyMode, callback: F) where F: Fn(bool, &mut X509StoreContextRef) -> bool + 'static + Sync + Send, @@ -1015,6 +998,7 @@ impl SslContextBuilder { /// # Panics /// /// This method panics if this `Ssl` is associated with a RPK context. + #[corresponds(SSL_CTX_set_custom_verify)] pub fn set_custom_verify_callback(&mut self, mode: SslVerifyMode, callback: F) where F: Fn(&mut SslRef) -> Result<(), SslVerifyError> + 'static + Sync + Send, @@ -1040,10 +1024,8 @@ impl SslContextBuilder { /// Obtain the server name with the `servername` method and then set the corresponding context /// with `set_ssl_context` /// - /// This corresponds to [`SSL_CTX_set_tlsext_servername_callback`]. - /// - /// [`SSL_CTX_set_tlsext_servername_callback`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_tlsext_servername_callback.html // FIXME tlsext prefix? + #[corresponds(SSL_CTX_set_tlsext_servername_callback)] pub fn set_servername_callback(&mut self, callback: F) where F: Fn(&mut SslRef, &mut SslAlert) -> Result<(), SniError> + 'static + Sync + Send, @@ -1069,10 +1051,7 @@ impl SslContextBuilder { /// Sets the certificate verification depth. /// /// If the peer's certificate chain is longer than this value, verification will fail. - /// - /// This corresponds to [`SSL_CTX_set_verify_depth`]. - /// - /// [`SSL_CTX_set_verify_depth`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_verify_depth.html + #[corresponds(SSL_CTX_set_verify_depth)] pub fn set_verify_depth(&mut self, depth: u32) { #[cfg(feature = "rpk")] assert!(!self.is_rpk, "This API is not supported for RPK"); @@ -1083,10 +1062,7 @@ impl SslContextBuilder { } /// Sets a custom certificate store for verifying peer certificates. - /// - /// This corresponds to [`SSL_CTX_set0_verify_cert_store`]. - /// - /// [`SSL_CTX_set0_verify_cert_store`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set0_verify_cert_store.html + #[corresponds(SSL_CTX_set0_verify_cert_store)] pub fn set_verify_cert_store(&mut self, cert_store: X509Store) -> Result<(), ErrorStack> { #[cfg(feature = "rpk")] assert!(!self.is_rpk, "This API is not supported for RPK"); @@ -1101,10 +1077,7 @@ impl SslContextBuilder { } /// Replaces the context's certificate store. - /// - /// This corresponds to [`SSL_CTX_set_cert_store`]. - /// - /// [`SSL_CTX_set_cert_store`]: https://www.openssl.org/docs/man1.0.2/man3/SSL_CTX_set_cert_store.html + #[corresponds(SSL_CTX_set_cert_store)] pub fn set_cert_store(&mut self, cert_store: X509Store) { #[cfg(feature = "rpk")] assert!(!self.is_rpk, "This API is not supported for RPK"); @@ -1121,10 +1094,7 @@ impl SslContextBuilder { /// instead of a single record at a time. /// /// It has no effect when used with DTLS. - /// - /// This corresponds to [`SSL_CTX_set_read_ahead`]. - /// - /// [`SSL_CTX_set_read_ahead`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_read_ahead.html + #[corresponds(SSL_CTX_set_read_ahead)] pub fn set_read_ahead(&mut self, read_ahead: bool) { unsafe { ffi::SSL_CTX_set_read_ahead(self.as_ptr(), read_ahead as c_int); @@ -1132,27 +1102,20 @@ impl SslContextBuilder { } /// Sets the mode used by the context, returning the new bit-mask after adding mode. - /// - /// This corresponds to [`SSL_CTX_set_mode`]. - /// - /// [`SSL_CTX_set_mode`]: https://www.openssl.org/docs/man1.0.2/man3/SSL_CTX_set_mode.html + #[corresponds(SSL_CTX_set_mode)] pub fn set_mode(&mut self, mode: SslMode) -> SslMode { let bits = unsafe { ffi::SSL_CTX_set_mode(self.as_ptr(), mode.bits()) }; SslMode::from_bits_retain(bits) } /// Sets the parameters to be used during ephemeral Diffie-Hellman key exchange. - /// - /// This corresponds to [`SSL_CTX_set_tmp_dh`]. - /// - /// [`SSL_CTX_set_tmp_dh`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_tmp_dh.html + #[corresponds(SSL_CTX_set_tmp_dh)] pub fn set_tmp_dh(&mut self, dh: &DhRef) -> Result<(), ErrorStack> { unsafe { cvt(ffi::SSL_CTX_set_tmp_dh(self.as_ptr(), dh.as_ptr()) as c_int).map(|_| ()) } } /// Sets the parameters to be used during ephemeral elliptic curve Diffie-Hellman key exchange. - /// - /// This corresponds to `SSL_CTX_set_tmp_ecdh`. + #[corresponds(SSL_CTX_set_tmp_ecdh)] pub fn set_tmp_ecdh(&mut self, key: &EcKeyRef) -> Result<(), ErrorStack> { unsafe { cvt(ffi::SSL_CTX_set_tmp_ecdh(self.as_ptr(), key.as_ptr()) as c_int).map(|_| ()) } } @@ -1161,10 +1124,7 @@ impl SslContextBuilder { /// /// These locations are read from the `SSL_CERT_FILE` and `SSL_CERT_DIR` environment variables /// if present, or defaults specified at OpenSSL build time otherwise. - /// - /// This corresponds to [`SSL_CTX_set_default_verify_paths`]. - /// - /// [`SSL_CTX_set_default_verify_paths`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_default_verify_paths.html + #[corresponds(SSL_CTX_set_default_verify_paths)] pub fn set_default_verify_paths(&mut self) -> Result<(), ErrorStack> { #[cfg(feature = "rpk")] assert!(!self.is_rpk, "This API is not supported for RPK"); @@ -1175,10 +1135,7 @@ impl SslContextBuilder { /// Loads trusted root certificates from a file. /// /// The file should contain a sequence of PEM-formatted CA certificates. - /// - /// This corresponds to [`SSL_CTX_load_verify_locations`]. - /// - /// [`SSL_CTX_load_verify_locations`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_load_verify_locations.html + #[corresponds(SSL_CTX_load_verify_locations)] pub fn set_ca_file>(&mut self, file: P) -> Result<(), ErrorStack> { #[cfg(feature = "rpk")] assert!(!self.is_rpk, "This API is not supported for RPK"); @@ -1198,10 +1155,7 @@ impl SslContextBuilder { /// /// The CA certificates must still be added to the trust root - they are not automatically set /// as trusted by this method. - /// - /// This corresponds to [`SSL_CTX_set_client_CA_list`]. - /// - /// [`SSL_CTX_set_client_CA_list`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_client_CA_list.html + #[corresponds(SSL_CTX_set_client_CA_list)] pub fn set_client_ca_list(&mut self, list: Stack) { #[cfg(feature = "rpk")] assert!(!self.is_rpk, "This API is not supported for RPK"); @@ -1214,10 +1168,7 @@ impl SslContextBuilder { /// Add the provided CA certificate to the list sent by the server to the client when /// requesting client-side TLS authentication. - /// - /// This corresponds to [`SSL_CTX_add_client_CA`]. - /// - /// [`SSL_CTX_add_client_CA`]: https://www.openssl.org/docs/man1.0.2/man3/SSL_CTX_set_client_CA_list.html + #[corresponds(SSL_CTX_add_client_CA)] pub fn add_client_ca(&mut self, cacert: &X509Ref) -> Result<(), ErrorStack> { #[cfg(feature = "rpk")] assert!(!self.is_rpk, "This API is not supported for RPK"); @@ -1233,10 +1184,7 @@ impl SslContextBuilder { /// /// This value should be set when using client certificates, or each request will fail its /// handshake and need to be restarted. - /// - /// This corresponds to [`SSL_CTX_set_session_id_context`]. - /// - /// [`SSL_CTX_set_session_id_context`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_session_id_context.html + #[corresponds(SSL_CTX_set_session_id_context)] pub fn set_session_id_context(&mut self, sid_ctx: &[u8]) -> Result<(), ErrorStack> { unsafe { assert!(sid_ctx.len() <= c_uint::MAX as usize); @@ -1254,10 +1202,7 @@ impl SslContextBuilder { /// Only a single certificate will be loaded - use `add_extra_chain_cert` to add the remainder /// of the certificate chain, or `set_certificate_chain_file` to load the entire chain from a /// single file. - /// - /// This corresponds to [`SSL_CTX_use_certificate_file`]. - /// - /// [`SSL_CTX_use_certificate_file`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_use_certificate_file.html + #[corresponds(SSL_CTX_use_certificate_file)] pub fn set_certificate_file>( &mut self, file: P, @@ -1282,10 +1227,7 @@ impl SslContextBuilder { /// The file should contain a sequence of PEM-formatted certificates, the first being the leaf /// certificate, and the remainder forming the chain of certificates up to and including the /// trusted root certificate. - /// - /// This corresponds to [`SSL_CTX_use_certificate_chain_file`]. - /// - /// [`SSL_CTX_use_certificate_chain_file`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_use_certificate_file.html + #[corresponds(SSL_CTX_use_certificate_chain_file)] pub fn set_certificate_chain_file>( &mut self, file: P, @@ -1303,10 +1245,7 @@ impl SslContextBuilder { /// Sets the leaf certificate. /// /// Use `add_extra_chain_cert` to add the remainder of the certificate chain. - /// - /// This corresponds to [`SSL_CTX_use_certificate`]. - /// - /// [`SSL_CTX_use_certificate`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_use_certificate_file.html + #[corresponds(SSL_CTX_use_certificate)] pub fn set_certificate(&mut self, cert: &X509Ref) -> Result<(), ErrorStack> { unsafe { cvt(ffi::SSL_CTX_use_certificate(self.as_ptr(), cert.as_ptr())).map(|_| ()) } } @@ -1315,10 +1254,7 @@ impl SslContextBuilder { /// /// This chain should contain all certificates necessary to go from the certificate specified by /// `set_certificate` to a trusted root. - /// - /// This corresponds to [`SSL_CTX_add_extra_chain_cert`]. - /// - /// [`SSL_CTX_add_extra_chain_cert`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_add_extra_chain_cert.html + #[corresponds(SSL_CTX_add_extra_chain_cert)] pub fn add_extra_chain_cert(&mut self, cert: X509) -> Result<(), ErrorStack> { #[cfg(feature = "rpk")] assert!(!self.is_rpk, "This API is not supported for RPK"); @@ -1331,10 +1267,7 @@ impl SslContextBuilder { } /// Loads the private key from a file. - /// - /// This corresponds to [`SSL_CTX_use_PrivateKey_file`]. - /// - /// [`SSL_CTX_use_PrivateKey_file`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_use_PrivateKey_file.html + #[corresponds(SSL_CTX_use_PrivateKey_file)] pub fn set_private_key_file>( &mut self, file: P, @@ -1352,10 +1285,7 @@ impl SslContextBuilder { } /// Sets the private key. - /// - /// This corresponds to [`SSL_CTX_use_PrivateKey`]. - /// - /// [`SSL_CTX_use_PrivateKey`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_use_PrivateKey_file.html + #[corresponds(SSL_CTX_use_PrivateKey)] pub fn set_private_key(&mut self, key: &PKeyRef) -> Result<(), ErrorStack> where T: HasPrivate, @@ -1371,10 +1301,8 @@ impl SslContextBuilder { /// /// See [`ciphers`] for details on the format. /// - /// This corresponds to [`SSL_CTX_set_cipher_list`]. - /// - /// [`ciphers`]: https://www.openssl.org/docs/man1.1.0/apps/ciphers.html - /// [`SSL_CTX_set_cipher_list`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_cipher_list.html + /// [`ciphers`]: https://www.openssl.org/docs/manmaster/apps/ciphers.html + #[corresponds(SSL_CTX_set_cipher_list)] pub fn set_cipher_list(&mut self, cipher_list: &str) -> Result<(), ErrorStack> { let cipher_list = CString::new(cipher_list).unwrap(); unsafe { @@ -1390,44 +1318,33 @@ impl SslContextBuilder { /// /// See [`ciphers`] for details on the format /// - /// This corresponds to [`SSL_CTX_get_ciphers`]. - /// /// [`ciphers`]: https://www.openssl.org/docs/manmaster/man1/ciphers.html - /// [`SSL_CTX_set_cipher_list`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_ciphers.html + #[corresponds(SSL_CTX_get_ciphers)] pub fn ciphers(&self) -> Option<&StackRef> { self.ctx.ciphers() } /// Sets the options used by the context, returning the old set. /// - /// This corresponds to [`SSL_CTX_set_options`]. - /// /// # Note /// /// This *enables* the specified options, but does not disable unspecified options. Use /// `clear_options` for that. - /// - /// [`SSL_CTX_set_options`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_options.html + #[corresponds(SSL_CTX_set_options)] pub fn set_options(&mut self, option: SslOptions) -> SslOptions { let bits = unsafe { ffi::SSL_CTX_set_options(self.as_ptr(), option.bits()) }; SslOptions::from_bits_retain(bits) } /// Returns the options used by the context. - /// - /// This corresponds to [`SSL_CTX_get_options`]. - /// - /// [`SSL_CTX_get_options`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_options.html + #[corresponds(SSL_CTX_get_options)] pub fn options(&self) -> SslOptions { let bits = unsafe { ffi::SSL_CTX_get_options(self.as_ptr()) }; SslOptions::from_bits_retain(bits) } /// Clears the options used by the context, returning the old set. - /// - /// This corresponds to [`SSL_CTX_clear_options`]. - /// - /// [`SSL_CTX_clear_options`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_options.html + #[corresponds(SSL_CTX_clear_options)] pub fn clear_options(&mut self, option: SslOptions) -> SslOptions { let bits = unsafe { ffi::SSL_CTX_clear_options(self.as_ptr(), option.bits()) }; SslOptions::from_bits_retain(bits) @@ -1437,10 +1354,7 @@ impl SslContextBuilder { /// /// If version is `None`, the default minimum version is used. For BoringSSL this defaults to /// TLS 1.0. - /// - /// This corresponds to [`SSL_CTX_set_min_proto_version`]. - /// - /// [`SSL_CTX_set_min_proto_version`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_min_proto_version.html + #[corresponds(SSL_CTX_set_min_proto_version)] pub fn set_min_proto_version(&mut self, version: Option) -> Result<(), ErrorStack> { unsafe { cvt(ffi::SSL_CTX_set_min_proto_version( @@ -1454,10 +1368,7 @@ impl SslContextBuilder { /// Sets the maximum supported protocol version. /// /// If version is `None`, the default maximum version is used. For BoringSSL this is TLS 1.3. - /// - /// This corresponds to [`SSL_CTX_set_max_proto_version`]. - /// - /// [`SSL_CTX_set_max_proto_version`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_max_proto_version.html + #[corresponds(SSL_CTX_set_max_proto_version)] pub fn set_max_proto_version(&mut self, version: Option) -> Result<(), ErrorStack> { unsafe { cvt(ffi::SSL_CTX_set_max_proto_version( @@ -1469,10 +1380,7 @@ impl SslContextBuilder { } /// Gets the minimum supported protocol version. - /// - /// This corresponds to [`SSL_CTX_get_min_proto_version`]. - /// - /// [`SSL_CTX_get_min_proto_version`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_min_proto_version.html + #[corresponds(SSL_CTX_get_min_proto_version)] pub fn min_proto_version(&mut self) -> Option { unsafe { let r = ffi::SSL_CTX_get_min_proto_version(self.as_ptr()); @@ -1485,10 +1393,7 @@ impl SslContextBuilder { } /// Gets the maximum supported protocol version. - /// - /// This corresponds to [`SSL_CTX_get_max_proto_version`]. - /// - /// [`SSL_CTX_get_max_proto_version`]: https://www.openssl.org/docs/man3.1/man3/SSL_CTX_get_max_proto_version.html + #[corresponds(SSL_CTX_get_max_proto_version)] pub fn max_proto_version(&mut self) -> Option { unsafe { let r = ffi::SSL_CTX_get_max_proto_version(self.as_ptr()); @@ -1506,10 +1411,7 @@ impl SslContextBuilder { /// names prefixed by their byte length. For example, the protocol list consisting of `spdy/1` /// and `http/1.1` is encoded as `b"\x06spdy/1\x08http/1.1"`. The protocols are ordered by /// preference. - /// - /// This corresponds to [`SSL_CTX_set_alpn_protos`]. - /// - /// [`SSL_CTX_set_alpn_protos`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_alpn_protos.html + #[corresponds(SSL_CTX_set_alpn_protos)] pub fn set_alpn_protos(&mut self, protocols: &[u8]) -> Result<(), ErrorStack> { unsafe { #[cfg_attr(not(feature = "fips"), allow(clippy::unnecessary_cast))] @@ -1531,10 +1433,7 @@ impl SslContextBuilder { } /// Enables the DTLS extension "use_srtp" as defined in RFC5764. - /// - /// This corresponds to [`SSL_CTX_set_tlsext_use_srtp`]. - /// - /// [`SSL_CTX_set_tlsext_use_srtp`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_tlsext_use_srtp.html + #[corresponds(SSL_CTX_set_tlsext_use_srtp)] pub fn set_tlsext_use_srtp(&mut self, protocols: &str) -> Result<(), ErrorStack> { unsafe { let cstr = CString::new(protocols).unwrap(); @@ -1557,11 +1456,9 @@ impl SslContextBuilder { /// of those protocols on success. The [`select_next_proto`] function implements the standard /// protocol selection algorithm. /// - /// This corresponds to [`SSL_CTX_set_alpn_select_cb`]. - /// /// [`SslContextBuilder::set_alpn_protos`]: struct.SslContextBuilder.html#method.set_alpn_protos /// [`select_next_proto`]: fn.select_next_proto.html - /// [`SSL_CTX_set_alpn_select_cb`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_alpn_protos.html + #[corresponds(SSL_CTX_set_alpn_select_cb)] pub fn set_alpn_select_callback(&mut self, callback: F) where F: for<'a> Fn(&mut SslRef, &'a [u8]) -> Result<&'a [u8], AlpnError> + 'static + Sync + Send, @@ -1579,10 +1476,7 @@ impl SslContextBuilder { /// Sets a callback that is called before most ClientHello processing and before the decision whether /// to resume a session is made. The callback may inspect the ClientHello and configure the /// connection. - /// - /// This corresponds to [`SSL_CTX_set_select_certificate_cb`]. - /// - /// [`SSL_CTX_set_select_certificate_cb`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_select_certificate_cb.html + #[corresponds(SSL_CTX_set_select_certificate_cb)] pub fn set_select_certificate_callback(&mut self, callback: F) where F: Fn(ClientHello<'_>) -> Result<(), SelectCertError> + Sync + Send + 'static, @@ -1599,10 +1493,7 @@ impl SslContextBuilder { /// Configures a custom private key method on the context. /// /// See [`PrivateKeyMethod`] for more details. - /// - /// This corresponds to [`SSL_CTX_set_private_key_method`] - /// - /// [`SSL_CTX_set_private_key_method`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_set_private_key_method + #[corresponds(SSL_CTX_set_private_key_method)] pub fn set_private_key_method(&mut self, method: M) where M: PrivateKeyMethod, @@ -1622,19 +1513,13 @@ impl SslContextBuilder { } /// Checks for consistency between the private key and certificate. - /// - /// This corresponds to [`SSL_CTX_check_private_key`]. - /// - /// [`SSL_CTX_check_private_key`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_check_private_key.html + #[corresponds(SSL_CTX_check_private_key)] pub fn check_private_key(&self) -> Result<(), ErrorStack> { unsafe { cvt(ffi::SSL_CTX_check_private_key(self.as_ptr())).map(|_| ()) } } /// Returns a shared reference to the context's certificate store. - /// - /// This corresponds to [`SSL_CTX_get_cert_store`]. - /// - /// [`SSL_CTX_get_cert_store`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_get_cert_store.html + #[corresponds(SSL_CTX_get_cert_store)] pub fn cert_store(&self) -> &X509StoreBuilderRef { #[cfg(feature = "rpk")] assert!(!self.is_rpk, "This API is not supported for RPK"); @@ -1643,10 +1528,7 @@ impl SslContextBuilder { } /// Returns a mutable reference to the context's certificate store. - /// - /// This corresponds to [`SSL_CTX_get_cert_store`]. - /// - /// [`SSL_CTX_get_cert_store`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_get_cert_store.html + #[corresponds(SSL_CTX_get_cert_store)] pub fn cert_store_mut(&mut self) -> &mut X509StoreBuilderRef { #[cfg(feature = "rpk")] assert!(!self.is_rpk, "This API is not supported for RPK"); @@ -1666,10 +1548,7 @@ impl SslContextBuilder { /// returned to clients. The status may be set with the `SslRef::set_ocsp_status` method. A /// response of `Ok(true)` indicates that the OCSP status should be returned to the client, and /// `Ok(false)` indicates that the status should not be returned to the client. - /// - /// This corresponds to [`SSL_CTX_set_tlsext_status_cb`]. - /// - /// [`SSL_CTX_set_tlsext_status_cb`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_tlsext_status_cb.html + #[corresponds(SSL_CTX_set_tlsext_status_cb)] pub fn set_status_callback(&mut self, callback: F) -> Result<(), ErrorStack> where F: Fn(&mut SslRef) -> Result + 'static + Sync + Send, @@ -1689,10 +1568,7 @@ impl SslContextBuilder { /// The callback will be called with the SSL context, an identity hint if one was provided /// by the server, a mutable slice for each of the identity and pre-shared key bytes. The /// identity must be written as a null-terminated C string. - /// - /// This corresponds to [`SSL_CTX_set_psk_client_callback`]. - /// - /// [`SSL_CTX_set_psk_client_callback`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_psk_client_callback.html + #[corresponds(SSL_CTX_set_psk_client_callback)] pub fn set_psk_client_callback(&mut self, callback: F) where F: Fn(&mut SslRef, Option<&[u8]>, &mut [u8], &mut [u8]) -> Result @@ -1722,10 +1598,7 @@ impl SslContextBuilder { /// The callback will be called with the SSL context, an identity provided by the client, /// and, a mutable slice for the pre-shared key bytes. The callback returns the number of /// bytes in the pre-shared key. - /// - /// This corresponds to [`SSL_CTX_set_psk_server_callback`]. - /// - /// [`SSL_CTX_set_psk_server_callback`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_psk_server_callback.html + #[corresponds(SSL_CTX_set_psk_server_callback)] pub fn set_psk_server_callback(&mut self, callback: F) where F: Fn(&mut SslRef, Option<&[u8]>, &mut [u8]) -> Result @@ -1750,11 +1623,9 @@ impl SslContextBuilder { /// Note that session caching must be enabled for the callback to be invoked, and it defaults /// off for clients. [`set_session_cache_mode`] controls that behavior. /// - /// This corresponds to [`SSL_CTX_sess_set_new_cb`]. - /// /// [`SslRef::session`]: struct.SslRef.html#method.session /// [`set_session_cache_mode`]: #method.set_session_cache_mode - /// [`SSL_CTX_sess_set_new_cb`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html + #[corresponds(SSL_CTX_sess_set_new_cb)] pub fn set_new_session_callback(&mut self, callback: F) where F: Fn(&mut SslRef, SslSession) + 'static + Sync + Send, @@ -1768,10 +1639,7 @@ impl SslContextBuilder { /// Sets the callback which is called when sessions are removed from the context. /// /// Sessions can be removed because they have timed out or because they are considered faulty. - /// - /// This corresponds to [`SSL_CTX_sess_set_remove_cb`]. - /// - /// [`SSL_CTX_sess_set_remove_cb`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html + #[corresponds(SSL_CTX_sess_set_remove_cb)] pub fn set_remove_session_callback(&mut self, callback: F) where F: Fn(&SslContextRef, &SslSessionRef) + 'static + Sync + Send, @@ -1792,13 +1660,10 @@ impl SslContextBuilder { /// return the session corresponding to that ID if available. This is only used for servers, not /// clients. /// - /// This corresponds to [`SSL_CTX_sess_set_get_cb`]. - /// /// # Safety /// /// The returned [`SslSession`] must not be associated with a different [`SslContext`]. - /// - /// [`SSL_CTX_sess_set_get_cb`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html + #[corresponds(SSL_CTX_sess_set_get_cb)] pub unsafe fn set_get_session_callback(&mut self, callback: F) where F: Fn(&mut SslRef, &[u8]) -> Result, GetSessionPendingError> @@ -1815,10 +1680,7 @@ impl SslContextBuilder { /// The callback is invoked whenever TLS key material is generated, and is passed a line of NSS /// SSLKEYLOGFILE-formatted text. This can be used by tools like Wireshark to decrypt message /// traffic. The line does not contain a trailing newline. - /// - /// This corresponds to [`SSL_CTX_set_keylog_callback`]. - /// - /// [`SSL_CTX_set_keylog_callback`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_keylog_callback.html + #[corresponds(SSL_CTX_set_keylog_callback)] pub fn set_keylog_callback(&mut self, callback: F) where F: Fn(&SslRef, &str) + 'static + Sync + Send, @@ -1832,10 +1694,7 @@ impl SslContextBuilder { /// Sets the session caching mode use for connections made with the context. /// /// Returns the previous session caching mode. - /// - /// This corresponds to [`SSL_CTX_set_session_cache_mode`]. - /// - /// [`SSL_CTX_set_session_cache_mode`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_get_session_cache_mode.html + #[corresponds(SSL_CTX_set_session_cache_mode)] pub fn set_session_cache_mode(&mut self, mode: SslSessionCacheMode) -> SslSessionCacheMode { unsafe { let bits = ffi::SSL_CTX_set_session_cache_mode(self.as_ptr(), mode.bits()); @@ -1848,12 +1707,9 @@ impl SslContextBuilder { /// This can be used to provide data to callbacks registered with the context. Use the /// `SslContext::new_ex_index` method to create an `Index`. /// - /// This corresponds to [`SSL_CTX_set_ex_data`]. - /// /// Note that if this method is called multiple times with the same index, any previous /// value stored in the `SslContextBuilder` will be leaked. - /// - /// [`SSL_CTX_set_ex_data`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_ex_data.html + #[corresponds(SSL_CTX_set_ex_data)] pub fn set_ex_data(&mut self, index: Index, data: T) { unsafe { self.ctx.set_ex_data(index, data); @@ -1865,11 +1721,8 @@ impl SslContextBuilder { /// This can be used to provide data to callbacks registered with the context. Use the /// `Ssl::new_ex_index` method to create an `Index`. /// - /// This corresponds to [`SSL_set_ex_data`]. - /// /// Any previous value will be returned and replaced by the new one. - /// - /// [`SSL_set_ex_data`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_ex_data.html + #[corresponds(SSL_CTX_set_ex_data)] pub fn replace_ex_data(&mut self, index: Index, data: T) -> Option { unsafe { self.ctx.replace_ex_data(index, data) } } @@ -1877,20 +1730,14 @@ impl SslContextBuilder { /// Sets the context's session cache size limit, returning the previous limit. /// /// A value of 0 means that the cache size is unbounded. - /// - /// This corresponds to [`SSL_CTX_sess_get_cache_size`]. - /// - /// [`SSL_CTX_sess_get_cache_size`]: https://www.openssl.org/docs/man1.0.2/man3/SSL_CTX_sess_set_cache_size.html + #[corresponds(SSL_CTX_sess_set_cache_size)] #[allow(clippy::useless_conversion)] pub fn set_session_cache_size(&mut self, size: u32) -> u64 { unsafe { ffi::SSL_CTX_sess_set_cache_size(self.as_ptr(), size.into()).into() } } /// Sets the context's supported signature algorithms. - /// - /// This corresponds to [`SSL_CTX_set1_sigalgs_list`]. - /// - /// [`SSL_CTX_set1_sigalgs_list`]: https://www.openssl.org/docs/man1.1.0/man3/SSL_CTX_set1_sigalgs_list.html + #[corresponds(SSL_CTX_set1_sigalgs_list)] pub fn set_sigalgs_list(&mut self, sigalgs: &str) -> Result<(), ErrorStack> { let sigalgs = CString::new(sigalgs).unwrap(); unsafe { @@ -1900,33 +1747,24 @@ impl SslContextBuilder { } /// Set's whether the context should enable GREASE. - /// - /// This corresponds to [`SSL_CTX_set_grease_enabled`] - /// - /// [`SSL_CTX_set_grease_enabled`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_set_grease_enabled + #[corresponds(SSL_CTX_set_grease_enabled)] pub fn set_grease_enabled(&mut self, enabled: bool) { unsafe { ffi::SSL_CTX_set_grease_enabled(self.as_ptr(), enabled as _) } } /// Configures whether ClientHello extensions should be permuted. /// - /// This corresponds to [`SSL_CTX_set_permute_extensions`]. - /// - /// [`SSL_CTX_set_permute_extensions`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_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. /// Once the submoduled fips commit is upgraded, these gates can be removed. + #[corresponds(SSL_CTX_set_permute_extensions)] #[cfg(not(feature = "fips"))] pub fn set_permute_extensions(&mut self, enabled: bool) { unsafe { ffi::SSL_CTX_set_permute_extensions(self.as_ptr(), enabled as _) } } /// Sets the context's supported signature verification algorithms. - /// - /// This corresponds to [`SSL_CTX_set_verify_algorithm_prefs`] - /// - /// [`SSL_CTX_set_verify_algorithm_prefs`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_set_verify_algorithm_prefs + #[corresponds(SSL_CTX_set_verify_algorithm_prefs)] pub fn set_verify_algorithm_prefs( &mut self, prefs: &[SslSignatureAlgorithm], @@ -1942,32 +1780,23 @@ impl SslContextBuilder { } /// Enables SCT requests on all client SSL handshakes. - /// - /// This corresponds to [`SSL_CTX_enable_signed_cert_timestamps`] - /// - /// [`SSL_CTX_enable_signed_cert_timestamps`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_enable_signed_cert_timestamps + #[corresponds(SSL_CTX_enable_signed_cert_timestamps)] pub fn enable_signed_cert_timestamps(&mut self) { unsafe { ffi::SSL_CTX_enable_signed_cert_timestamps(self.as_ptr()) } } /// Enables OCSP stapling on all client SSL handshakes. - /// - /// This corresponds to [`SSL_CTX_enable_ocsp_stapling`] - /// - /// [`SSL_CTX_enable_ocsp_stapling`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_enable_ocsp_stapling + #[corresponds(SSL_CTX_enable_ocsp_stapling)] pub fn enable_ocsp_stapling(&mut self) { unsafe { ffi::SSL_CTX_enable_ocsp_stapling(self.as_ptr()) } } /// Sets the context's supported curves. - /// - /// This corresponds to [`SSL_CTX_set1_curves`] - /// - /// [`SSL_CTX_set1_curves`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_set1_curves // // If the "kx-*" flags are used to set key exchange preference, then don't allow the user to // set them here. This ensures we don't override the user's preference without telling them: // when the flags are used, the preferences are set just before connecting or accepting. + #[corresponds(SSL_CTX_set1_curves)] #[cfg(not(feature = "kx-safe-default"))] pub fn set_curves(&mut self, curves: &[SslCurve]) -> Result<(), ErrorStack> { let curves: Vec = curves.iter().filter_map(|curve| curve.nid()).collect(); @@ -1984,10 +1813,8 @@ impl SslContextBuilder { /// Sets the context's compliance policy. /// - /// This corresponds to [`SSL_CTX_set_compliance_policy`] - /// - /// [`SSL_CTX_set_compliance_policy`] https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_CTX_set_compliance_policy /// This feature isn't available in the certified version of BoringSSL. + #[corresponds(SSL_CTX_set_compliance_policy)] #[cfg(not(feature = "fips"))] pub fn set_compliance_policy(&mut self, policy: CompliancePolicy) -> Result<(), ErrorStack> { unsafe { cvt_0i(ffi::SSL_CTX_set_compliance_policy(self.as_ptr(), policy.0)).map(|_| ()) } @@ -2044,10 +1871,7 @@ impl SslContext { /// /// Each invocation of this function is guaranteed to return a distinct index. These can be used /// to store data in the context that can be retrieved later by callbacks, for example. - /// - /// This corresponds to [`SSL_CTX_get_ex_new_index`]. - /// - /// [`SSL_CTX_get_ex_new_index`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_get_ex_new_index.html + #[corresponds(SSL_CTX_get_ex_new_index)] pub fn new_ex_index() -> Result, ErrorStack> where T: 'static + Sync + Send, @@ -2078,10 +1902,8 @@ impl SslContext { /// /// See [`ciphers`] for details on the format /// - /// This corresponds to [`SSL_CTX_get_ciphers`]. - /// /// [`ciphers`]: https://www.openssl.org/docs/manmaster/man1/ciphers.html - /// [`SSL_CTX_set_cipher_list`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_ciphers.html + #[corresponds(SSL_CTX_get_ciphers)] pub fn ciphers(&self) -> Option<&StackRef> { unsafe { let ciphers = ffi::SSL_CTX_get_ciphers(self.as_ptr()); @@ -2096,10 +1918,7 @@ impl SslContext { impl SslContextRef { /// Returns the certificate associated with this `SslContext`, if present. - /// - /// This corresponds to [`SSL_CTX_get0_certificate`]. - /// - /// [`SSL_CTX_get0_certificate`]: https://www.openssl.org/docs/man1.1.0/ssl/ssl.html + #[corresponds(SSL_CTX_get0_certificate)] pub fn certificate(&self) -> Option<&X509Ref> { #[cfg(feature = "rpk")] assert!(!self.is_rpk(), "This API is not supported for RPK"); @@ -2115,10 +1934,7 @@ impl SslContextRef { } /// Returns the private key associated with this `SslContext`, if present. - /// - /// This corresponds to [`SSL_CTX_get0_privatekey`]. - /// - /// [`SSL_CTX_get0_privatekey`]: https://www.openssl.org/docs/man1.1.0/ssl/ssl.html + #[corresponds(SSL_CTX_get0_privatekey)] pub fn private_key(&self) -> Option<&PKeyRef> { unsafe { let ptr = ffi::SSL_CTX_get0_privatekey(self.as_ptr()); @@ -2131,10 +1947,7 @@ impl SslContextRef { } /// Returns a shared reference to the certificate store used for verification. - /// - /// This corresponds to [`SSL_CTX_get_cert_store`]. - /// - /// [`SSL_CTX_get_cert_store`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_get_cert_store.html + #[corresponds(SSL_CTX_get_cert_store)] pub fn cert_store(&self) -> &X509StoreRef { #[cfg(feature = "rpk")] assert!(!self.is_rpk(), "This API is not supported for RPK"); @@ -2143,8 +1956,7 @@ impl SslContextRef { } /// Returns a shared reference to the stack of certificates making up the chain from the leaf. - /// - /// This corresponds to `SSL_CTX_get_extra_chain_certs`. + #[corresponds(SSL_CTX_get_extra_chain_certs)] pub fn extra_chain_certs(&self) -> &StackRef { unsafe { let mut chain = ptr::null_mut(); @@ -2155,10 +1967,7 @@ impl SslContextRef { } /// Returns a reference to the extra data at the specified index. - /// - /// This corresponds to [`SSL_CTX_get_ex_data`]. - /// - /// [`SSL_CTX_get_ex_data`]: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_ex_data.html + #[corresponds(SSL_CTX_get_ex_data)] pub fn ex_data(&self, index: Index) -> Option<&T> { unsafe { let data = ffi::SSL_CTX_get_ex_data(self.as_ptr(), index.as_raw()); @@ -2172,6 +1981,7 @@ impl SslContextRef { // Unsafe because SSL contexts are not guaranteed to be unique, we call // this only from SslContextBuilder. + #[corresponds(SSL_CTX_get_ex_data)] unsafe fn ex_data_mut(&mut self, index: Index) -> Option<&mut T> { let data = ffi::SSL_CTX_get_ex_data(self.as_ptr(), index.as_raw()); if data.is_null() { @@ -2183,6 +1993,7 @@ impl SslContextRef { // Unsafe because SSL contexts are not guaranteed to be unique, we call // this only from SslContextBuilder. + #[corresponds(SSL_CTX_set_ex_data)] unsafe fn set_ex_data(&mut self, index: Index, data: T) { unsafe { let data = Box::into_raw(Box::new(data)) as *mut c_void; @@ -2192,6 +2003,7 @@ impl SslContextRef { // Unsafe because SSL contexts are not guaranteed to be unique, we call // this only from SslContextBuilder. + #[corresponds(SSL_CTX_set_ex_data)] unsafe fn replace_ex_data(&mut self, index: Index, data: T) -> Option { if let Some(old) = self.ex_data_mut(index) { return Some(mem::replace(old, data)); @@ -2206,14 +2018,11 @@ impl SslContextRef { /// /// Returns `true` if the session was successfully added to the cache, and `false` if it was already present. /// - /// This corresponds to [`SSL_CTX_add_session`]. - /// /// # Safety /// /// The caller of this method is responsible for ensuring that the session has never been used with another /// `SslContext` than this one. - /// - /// [`SSL_CTX_add_session`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_remove_session.html + #[corresponds(SSL_CTX_add_session)] pub unsafe fn add_session(&self, session: &SslSessionRef) -> bool { ffi::SSL_CTX_add_session(self.as_ptr(), session.as_ptr()) != 0 } @@ -2222,14 +2031,11 @@ impl SslContextRef { /// /// Returns `true` if the session was successfully found and removed, and `false` otherwise. /// - /// This corresponds to [`SSL_CTX_remove_session`]. - /// /// # Safety /// /// The caller of this method is responsible for ensuring that the session has never been used with another /// `SslContext` than this one. - /// - /// [`SSL_CTX_remove_session`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_remove_session.html + #[corresponds(SSL_CTX_remove_session)] pub unsafe fn remove_session(&self, session: &SslSessionRef) -> bool { ffi::SSL_CTX_remove_session(self.as_ptr(), session.as_ptr()) != 0 } @@ -2237,10 +2043,7 @@ impl SslContextRef { /// Returns the context's session cache size limit. /// /// A value of 0 means that the cache size is unbounded. - /// - /// This corresponds to [`SSL_CTX_sess_get_cache_size`]. - /// - /// [`SSL_CTX_sess_get_cache_size`]: https://www.openssl.org/docs/man1.0.2/man3/SSL_CTX_sess_set_cache_size.html + #[corresponds(SSL_CTX_sess_get_cache_size)] #[allow(clippy::useless_conversion)] pub fn session_cache_size(&self) -> u64 { unsafe { ffi::SSL_CTX_sess_get_cache_size(self.as_ptr()).into() } @@ -2248,10 +2051,8 @@ impl SslContextRef { /// Returns the verify mode that was set on this context from [`SslContextBuilder::set_verify`]. /// - /// This corresponds to [`SSL_CTX_get_verify_mode`]. - /// /// [`SslContextBuilder::set_verify`]: struct.SslContextBuilder.html#method.set_verify - /// [`SSL_CTX_get_verify_mode`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_get_verify_mode.html + #[corresponds(SSL_CTX_get_verify_mode)] pub fn verify_mode(&self) -> SslVerifyMode { #[cfg(feature = "rpk")] assert!(!self.is_rpk(), "This API is not supported for RPK"); @@ -2353,6 +2154,7 @@ impl ClientHello<'_> { pub struct SslCipher(*mut ffi::SSL_CIPHER); impl SslCipher { + #[corresponds(SSL_get_cipher_by_value)] pub fn from_value(value: u16) -> Option { unsafe { let ptr = ffi::SSL_get_cipher_by_value(value); @@ -2409,10 +2211,7 @@ unsafe impl ForeignTypeRef for SslCipherRef { impl SslCipherRef { /// Returns the name of the cipher. - /// - /// This corresponds to [`SSL_CIPHER_get_name`]. - /// - /// [`SSL_CIPHER_get_name`]: https://www.openssl.org/docs/manmaster/man3/SSL_CIPHER_get_name.html + #[corresponds(SSL_CIPHER_get_name)] pub fn name(&self) -> &'static str { unsafe { let ptr = ffi::SSL_CIPHER_get_name(self.as_ptr()); @@ -2421,10 +2220,7 @@ impl SslCipherRef { } /// Returns the RFC-standard name of the cipher, if one exists. - /// - /// This corresponds to [`SSL_CIPHER_standard_name`]. - /// - /// [`SSL_CIPHER_standard_name`]: https://www.openssl.org/docs/manmaster/man3/SSL_CIPHER_get_name.html + #[corresponds(SSL_CIPHER_standard_name)] pub fn standard_name(&self) -> Option<&'static str> { unsafe { let ptr = ffi::SSL_CIPHER_standard_name(self.as_ptr()); @@ -2437,10 +2233,7 @@ impl SslCipherRef { } /// Returns the SSL/TLS protocol version that first defined the cipher. - /// - /// This corresponds to [`SSL_CIPHER_get_version`]. - /// - /// [`SSL_CIPHER_get_version`]: https://www.openssl.org/docs/manmaster/man3/SSL_CIPHER_get_name.html + #[corresponds(SSL_CIPHER_get_version)] pub fn version(&self) -> &'static str { let version = unsafe { let ptr = ffi::SSL_CIPHER_get_version(self.as_ptr()); @@ -2451,10 +2244,7 @@ impl SslCipherRef { } /// Returns the number of bits used for the cipher. - /// - /// This corresponds to [`SSL_CIPHER_get_bits`]. - /// - /// [`SSL_CIPHER_get_bits`]: https://www.openssl.org/docs/manmaster/man3/SSL_CIPHER_get_name.html + #[corresponds(SSL_CIPHER_get_bits)] #[allow(clippy::useless_conversion)] pub fn bits(&self) -> CipherBits { unsafe { @@ -2468,10 +2258,7 @@ impl SslCipherRef { } /// Returns a textual description of the cipher. - /// - /// This corresponds to [`SSL_CIPHER_description`]. - /// - /// [`SSL_CIPHER_description`]: https://www.openssl.org/docs/manmaster/man3/SSL_CIPHER_get_name.html + #[corresponds(SSL_CIPHER_description)] pub fn description(&self) -> String { unsafe { // SSL_CIPHER_description requires a buffer of at least 128 bytes. @@ -2482,19 +2269,13 @@ impl SslCipherRef { } /// Returns one if the cipher uses an AEAD cipher. - /// - /// This corresponds to [`SSL_CIPHER_is_aead`]. - /// - /// [`SSL_CIPHER_is_aead`]: https://www.openssl.org/docs/manmaster/man3/SSL_CIPHER_is_aead.html + #[corresponds(SSL_CIPHER_is_aead)] pub fn cipher_is_aead(&self) -> bool { unsafe { ffi::SSL_CIPHER_is_aead(self.as_ptr()) != 0 } } /// Returns the NID corresponding to the cipher's authentication type. - /// - /// This corresponds to [`SSL_CIPHER_get_auth_nid`]. - /// - /// [`SSL_CIPHER_get_auth_nid`]: https://www.openssl.org/docs/manmaster/man3/SSL_CIPHER_get_auth_nid.html + #[corresponds(SSL_CIPHER_get_auth_nid)] pub fn cipher_auth_nid(&self) -> Option { let n = unsafe { ffi::SSL_CIPHER_get_auth_nid(self.as_ptr()) }; if n == 0 { @@ -2505,10 +2286,7 @@ impl SslCipherRef { } /// Returns the NID corresponding to the cipher. - /// - /// This corresponds to [`SSL_CIPHER_get_cipher_nid`]. - /// - /// [`SSL_CIPHER_get_cipher_nid`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CIPHER_get_cipher_nid.html + #[corresponds(SSL_CIPHER_get_cipher_nid)] pub fn cipher_nid(&self) -> Option { let n = unsafe { ffi::SSL_CIPHER_get_cipher_nid(self.as_ptr()) }; if n == 0 { @@ -2562,10 +2340,7 @@ impl ToOwned for SslSessionRef { impl SslSessionRef { /// Returns the SSL session ID. - /// - /// This corresponds to [`SSL_SESSION_get_id`]. - /// - /// [`SSL_SESSION_get_id`]: https://www.openssl.org/docs/manmaster/man3/SSL_SESSION_get_id.html + #[corresponds(SSL_SESSION_get_id)] pub fn id(&self) -> &[u8] { unsafe { let mut len = 0; @@ -2575,10 +2350,7 @@ impl SslSessionRef { } /// Returns the length of the master key. - /// - /// This corresponds to [`SSL_SESSION_get_master_key`]. - /// - /// [`SSL_SESSION_get_master_key`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_SESSION_get_master_key.html + #[corresponds(SSL_SESSION_get_master_key)] pub fn master_key_len(&self) -> usize { unsafe { SSL_SESSION_get_master_key(self.as_ptr(), ptr::null_mut(), 0) } } @@ -2586,19 +2358,13 @@ impl SslSessionRef { /// Copies the master key into the provided buffer. /// /// Returns the number of bytes written, or the size of the master key if the buffer is empty. - /// - /// This corresponds to [`SSL_SESSION_get_master_key`]. - /// - /// [`SSL_SESSION_get_master_key`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_SESSION_get_master_key.html + #[corresponds(SSL_SESSION_get_master_key)] pub fn master_key(&self, buf: &mut [u8]) -> usize { unsafe { SSL_SESSION_get_master_key(self.as_ptr(), buf.as_mut_ptr(), buf.len()) } } /// Returns the time at which the session was established, in seconds since the Unix epoch. - /// - /// This corresponds to [`SSL_SESSION_get_time`]. - /// - /// [`SSL_SESSION_get_time`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_SESSION_get_time.html + #[corresponds(SSL_SESSION_get_time)] #[allow(clippy::useless_conversion)] pub fn time(&self) -> u64 { unsafe { ffi::SSL_SESSION_get_time(self.as_ptr()) } @@ -2607,20 +2373,14 @@ impl SslSessionRef { /// Returns the sessions timeout, in seconds. /// /// A session older than this time should not be used for session resumption. - /// - /// This corresponds to [`SSL_SESSION_get_timeout`]. - /// - /// [`SSL_SESSION_get_timeout`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_SESSION_get_time.html + #[corresponds(SSL_SESSION_get_timeout)] #[allow(clippy::useless_conversion)] pub fn timeout(&self) -> u32 { unsafe { ffi::SSL_SESSION_get_timeout(self.as_ptr()) } } /// Returns the session's TLS protocol version. - /// - /// This corresponds to [`SSL_SESSION_get_protocol_version`]. - /// - /// [`SSL_SESSION_get_protocol_version`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_SESSION_get_protocol_version.html + #[corresponds(SSL_SESSION_get_protocol_version)] pub fn protocol_version(&self) -> SslVersion { unsafe { let version = ffi::SSL_SESSION_get_protocol_version(self.as_ptr()); @@ -2663,10 +2423,7 @@ impl Ssl { /// /// Each invocation of this function is guaranteed to return a distinct index. These can be used /// to store data in the context that can be retrieved later by callbacks, for example. - /// - /// This corresponds to [`SSL_get_ex_new_index`]. - /// - /// [`SSL_get_ex_new_index`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_get_ex_new_index.html + #[corresponds(SSL_get_ex_new_index)] pub fn new_ex_index() -> Result, ErrorStack> where T: 'static + Sync + Send, @@ -2695,10 +2452,8 @@ impl Ssl { /// Creates a new `Ssl`. /// - /// This corresponds to [`SSL_new`]. - /// - /// [`SSL_new`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_new.html // FIXME should take &SslContextRef + #[corresponds(SSL_new)] pub fn new(ctx: &SslContext) -> Result { unsafe { let ptr = cvt_p(ffi::SSL_new(ctx.as_ptr()))?; @@ -2711,10 +2466,9 @@ impl Ssl { /// Creates a new [`Ssl`]. /// - /// This corresponds to [`SSL_new`](`ffi::SSL_new`). - /// /// This function does the same as [`Self:new`] except that it takes &[SslContextRef]. // Both functions exist for backward compatibility (no breaking API). + #[corresponds(SSL_new)] pub fn new_from_ref(ctx: &SslContextRef) -> Result { unsafe { let ptr = cvt_p(ffi::SSL_new(ctx.as_ptr()))?; @@ -2836,6 +2590,7 @@ impl SslRef { unsafe { ffi::SSL_get_rbio(self.as_ptr()) } } + #[corresponds(SSL_set1_curves_list)] #[cfg(feature = "kx-safe-default")] fn set_curves_list(&mut self, curves: &str) -> Result<(), ErrorStack> { let curves = CString::new(curves).unwrap(); @@ -2881,10 +2636,7 @@ impl SslRef { } /// Returns the [`SslCurve`] used for this `SslRef`. - /// - /// This corresponds to [`SSL_get_curve_id`] - /// - /// [`SSL_get_curve_id`]: https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_get_curve_id + #[corresponds(SSL_get_curve_id)] pub fn curve(&self) -> Option { let curve_id = unsafe { ffi::SSL_get_curve_id(self.as_ptr()) }; if curve_id == 0 { @@ -2894,20 +2646,15 @@ impl SslRef { } /// Returns an `ErrorCode` value for the most recent operation on this `SslRef`. - /// - /// This corresponds to [`SSL_get_error`]. - /// - /// [`SSL_get_error`]: https://github.com/google/boringssl/blob/master/include/openssl/ssl.h#L475 + #[corresponds(SSL_get_error)] pub fn error_code(&self, ret: c_int) -> ErrorCode { unsafe { ErrorCode::from_raw(ffi::SSL_get_error(self.as_ptr(), ret)) } } /// Like [`SslContextBuilder::set_verify`]. /// - /// This corresponds to [`SSL_set_verify`]. - /// /// [`SslContextBuilder::set_verify`]: struct.SslContextBuilder.html#method.set_verify - /// [`SSL_set_verify`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_set_verify.html + #[corresponds(SSL_set_verify)] pub fn set_verify(&mut self, mode: SslVerifyMode) { #[cfg(feature = "rpk")] assert!( @@ -2921,10 +2668,7 @@ impl SslRef { /// Sets the certificate verification depth. /// /// If the peer's certificate chain is longer than this value, verification will fail. - /// - /// This corresponds to [`SSL_set_verify_depth`]. - /// - /// [`SSL_set_verify_depth`]: https://docs.openssl.org/1.1.1/man3/SSL_CTX_set_verify/ + #[corresponds(SSL_set_verify_depth)] pub fn set_verify_depth(&mut self, depth: u32) { #[cfg(feature = "rpk")] assert!( @@ -2938,10 +2682,7 @@ impl SslRef { } /// Returns the verify mode that was set using `set_verify`. - /// - /// This corresponds to [`SSL_get_verify_mode`]. - /// - /// [`SSL_get_verify_mode`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_get_verify_mode.html + #[corresponds(SSL_get_verify_mode)] pub fn verify_mode(&self) -> SslVerifyMode { #[cfg(feature = "rpk")] assert!( @@ -2966,13 +2707,10 @@ impl SslRef { /// call [`X509StoreContextRef::verify_cert`] and inspect the result, or perform /// other operations more straightforwardly. /// - /// This corresponds to [`SSL_set_verify`]. - /// /// # Panics /// /// This method panics if this `Ssl` is associated with a RPK context. - /// - /// [`SSL_set_verify`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_set_verify.html + #[corresponds(SSL_set_verify)] pub fn set_verify_callback(&mut self, mode: SslVerifyMode, callback: F) where F: Fn(bool, &mut X509StoreContextRef) -> bool + 'static + Sync + Send, @@ -2995,10 +2733,7 @@ impl SslRef { } /// Sets a custom certificate store for verifying peer certificates. - /// - /// This corresponds to [`SSL_CTX_set0_verify_cert_store`]. - /// - /// [`SSL_set0_verify_cert_store`]: https://docs.openssl.org/1.0.2/man3/SSL_CTX_set1_verify_cert_store/ + #[corresponds(SSL_set0_verify_cert_store)] pub fn set_verify_cert_store(&mut self, cert_store: X509Store) -> Result<(), ErrorStack> { #[cfg(feature = "rpk")] assert!( @@ -3015,11 +2750,10 @@ impl SslRef { /// Like [`SslContextBuilder::set_custom_verify_callback`]. /// - /// This corresponds to [`SSL_set_custom_verify`]. - /// /// # Panics /// /// This method panics if this `Ssl` is associated with a RPK context. + #[corresponds(SSL_set_custom_verify)] pub fn set_custom_verify_callback(&mut self, mode: SslVerifyMode, callback: F) where F: Fn(&mut SslRef) -> Result<(), SslVerifyError> + 'static + Sync + Send, @@ -3043,19 +2777,16 @@ impl SslRef { /// Like [`SslContextBuilder::set_tmp_dh`]. /// - /// This corresponds to [`SSL_set_tmp_dh`]. - /// /// [`SslContextBuilder::set_tmp_dh`]: struct.SslContextBuilder.html#method.set_tmp_dh - /// [`SSL_set_tmp_dh`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_set_tmp_dh.html + #[corresponds(SSL_set_tmp_dh)] pub fn set_tmp_dh(&mut self, dh: &DhRef) -> Result<(), ErrorStack> { unsafe { cvt(ffi::SSL_set_tmp_dh(self.as_ptr(), dh.as_ptr()) as c_int).map(|_| ()) } } /// Like [`SslContextBuilder::set_tmp_ecdh`]. /// - /// This corresponds to `SSL_set_tmp_ecdh`. - /// /// [`SslContextBuilder::set_tmp_ecdh`]: struct.SslContextBuilder.html#method.set_tmp_ecdh + #[corresponds(SSL_set_tmp_ecdh)] pub fn set_tmp_ecdh(&mut self, key: &EcKeyRef) -> Result<(), ErrorStack> { unsafe { cvt(ffi::SSL_set_tmp_ecdh(self.as_ptr(), key.as_ptr()) as c_int).map(|_| ()) } } @@ -3076,10 +2807,8 @@ impl SslRef { /// Like [`SslContextBuilder::set_alpn_protos`]. /// - /// This corresponds to [`SSL_set_alpn_protos`]. - /// /// [`SslContextBuilder::set_alpn_protos`]: struct.SslContextBuilder.html#method.set_alpn_protos - /// [`SSL_set_alpn_protos`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_set_alpn_protos.html + #[corresponds(SSL_set_alpn_protos)] pub fn set_alpn_protos(&mut self, protocols: &[u8]) -> Result<(), ErrorStack> { unsafe { #[cfg_attr(not(feature = "fips"), allow(clippy::unnecessary_cast))] @@ -3101,10 +2830,7 @@ impl SslRef { } /// Returns the stack of available SslCiphers for `SSL`, sorted by preference. - /// - /// This corresponds to [`SSL_get_ciphers`]. - /// - /// [`SSL_get_ciphers`]: https://www.openssl.org/docs/man1.0.2/man3/SSL_get_ciphers.html + #[corresponds(SSL_get_ciphers)] pub fn ciphers(&self) -> &StackRef { unsafe { let cipher_list = ffi::SSL_get_ciphers(self.as_ptr()); @@ -3113,10 +2839,7 @@ impl SslRef { } /// Returns the current cipher if the session is active. - /// - /// This corresponds to [`SSL_get_current_cipher`]. - /// - /// [`SSL_get_current_cipher`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_current_cipher.html + #[corresponds(SSL_get_current_cipher)] pub fn current_cipher(&self) -> Option<&SslCipherRef> { unsafe { let ptr = ffi::SSL_get_current_cipher(self.as_ptr()); @@ -3130,10 +2853,7 @@ impl SslRef { } /// Returns a short string describing the state of the session. - /// - /// This corresponds to [`SSL_state_string`]. - /// - /// [`SSL_state_string`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_state_string.html + #[corresponds(SSL_state_string)] pub fn state_string(&self) -> &'static str { let state = unsafe { let ptr = ffi::SSL_state_string(self.as_ptr()); @@ -3144,10 +2864,7 @@ impl SslRef { } /// Returns a longer string describing the state of the session. - /// - /// This corresponds to [`SSL_state_string_long`]. - /// - /// [`SSL_state_string_long`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_state_string_long.html + #[corresponds(SSL_state_string_long)] pub fn state_string_long(&self) -> &'static str { let state = unsafe { let ptr = ffi::SSL_state_string_long(self.as_ptr()); @@ -3160,10 +2877,7 @@ impl SslRef { /// Sets the host name to be sent to the server for Server Name Indication (SNI). /// /// It has no effect for a server-side connection. - /// - /// This corresponds to [`SSL_set_tlsext_host_name`]. - /// - /// [`SSL_set_tlsext_host_name`]: https://www.openssl.org/docs/manmaster/man3/SSL_get_servername_type.html + #[corresponds(SSL_set_tlsext_host_name)] pub fn set_hostname(&mut self, hostname: &str) -> Result<(), ErrorStack> { let cstr = CString::new(hostname).unwrap(); unsafe { @@ -3173,10 +2887,7 @@ impl SslRef { } /// Returns the peer's certificate, if present. - /// - /// This corresponds to [`SSL_get_peer_certificate`]. - /// - /// [`SSL_get_peer_certificate`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_peer_certificate.html + #[corresponds(SSL_get_peer_certificate)] pub fn peer_certificate(&self) -> Option { #[cfg(feature = "rpk")] assert!( @@ -3198,10 +2909,7 @@ impl SslRef { /// /// On the client side, the chain includes the leaf certificate, but on the server side it does /// not. Fun! - /// - /// This corresponds to [`SSL_get_peer_cert_chain`]. - /// - /// [`SSL_get_peer_cert_chain`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_peer_cert_chain.html + #[corresponds(SSL_get_peer_certificate)] pub fn peer_cert_chain(&self) -> Option<&StackRef> { #[cfg(feature = "rpk")] assert!( @@ -3220,10 +2928,7 @@ impl SslRef { } /// Like [`SslContext::certificate`]. - /// - /// This corresponds to `SSL_get_certificate`. - /// - /// [`SslContext::certificate`]: struct.SslContext.html#method.certificate + #[corresponds(SSL_get_certificate)] pub fn certificate(&self) -> Option<&X509Ref> { #[cfg(feature = "rpk")] assert!( @@ -3242,10 +2947,7 @@ impl SslRef { } /// Like [`SslContext::private_key`]. - /// - /// This corresponds to `SSL_get_privatekey`. - /// - /// [`SslContext::private_key`]: struct.SslContext.html#method.private_key + #[corresponds(SSL_get_privatekey)] pub fn private_key(&self) -> Option<&PKeyRef> { unsafe { let ptr = ffi::SSL_get_privatekey(self.as_ptr()); @@ -3263,10 +2965,7 @@ impl SslRef { } /// Returns the protocol version of the session. - /// - /// This corresponds to [`SSL_version`]. - /// - /// [`SSL_version`]: https://www.openssl.org/docs/manmaster/man3/SSL_version.html + #[corresponds(SSL_version)] pub fn version2(&self) -> Option { unsafe { let r = ffi::SSL_version(self.as_ptr()); @@ -3279,10 +2978,7 @@ impl SslRef { } /// Returns a string describing the protocol version of the session. - /// - /// This corresponds to [`SSL_get_version`]. - /// - /// [`SSL_get_version`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_version.html + #[corresponds(SSL_get_version)] pub fn version_str(&self) -> &'static str { let version = unsafe { let ptr = ffi::SSL_get_version(self.as_ptr()); @@ -3296,10 +2992,7 @@ impl SslRef { /// /// If version is `None`, the default minimum version is used. For BoringSSL this defaults to /// TLS 1.0. - /// - /// This corresponds to [`SSL_set_min_proto_version`]. - /// - /// [`SSL_set_min_proto_version`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_set_min_proto_version.html + #[corresponds(SSL_set_min_proto_version)] pub fn set_min_proto_version(&mut self, version: Option) -> Result<(), ErrorStack> { unsafe { cvt(ffi::SSL_set_min_proto_version( @@ -3313,10 +3006,7 @@ impl SslRef { /// Sets the maximum supported protocol version. /// /// If version is `None`, the default maximum version is used. For BoringSSL this is TLS 1.3. - /// - /// This corresponds to [`SSL_set_max_proto_version`]. - /// - /// [`SSL_set_max_proto_version`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_set_max_proto_version.html + #[corresponds(SSL_set_max_proto_version)] pub fn set_max_proto_version(&mut self, version: Option) -> Result<(), ErrorStack> { unsafe { cvt(ffi::SSL_set_max_proto_version( @@ -3328,10 +3018,7 @@ impl SslRef { } /// Gets the minimum supported protocol version. - /// - /// This corresponds to [`SSL_get_min_proto_version`]. - /// - /// [`SSL_get_min_proto_version`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_set_min_proto_version.html + #[corresponds(SSL_get_min_proto_version)] pub fn min_proto_version(&mut self) -> Option { unsafe { let r = ffi::SSL_get_min_proto_version(self.as_ptr()); @@ -3344,10 +3031,7 @@ impl SslRef { } /// Gets the maximum supported protocol version. - /// - /// This corresponds to [`SSL_get_max_proto_version`]. - /// - /// [`SSL_get_max_proto_version`]: https://www.openssl.org/docs/man3.1/man3/SSL_get_max_proto_version.html + #[corresponds(SSL_get_max_proto_version)] pub fn max_proto_version(&self) -> Option { let r = unsafe { ffi::SSL_get_max_proto_version(self.as_ptr()) }; if r == 0 { @@ -3361,10 +3045,7 @@ impl SslRef { /// /// The protocol's name is returned is an opaque sequence of bytes. It is up to the client /// to interpret it. - /// - /// This corresponds to [`SSL_get0_alpn_selected`]. - /// - /// [`SSL_get0_alpn_selected`]: https://www.openssl.org/docs/manmaster/man3/SSL_get0_next_proto_negotiated.html + #[corresponds(SSL_get0_alpn_selected)] pub fn selected_alpn_protocol(&self) -> Option<&[u8]> { unsafe { let mut data: *const c_uchar = ptr::null(); @@ -3382,10 +3063,7 @@ 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 { let cstr = CString::new(protocols).unwrap(); @@ -3403,10 +3081,7 @@ 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_strp_profiles)] pub fn srtp_profiles(&self) -> Option<&StackRef> { unsafe { let chain = ffi::SSL_get_srtp_profiles(self.as_ptr()); @@ -3422,10 +3097,7 @@ impl SslRef { /// Gets the SRTP profile selected by handshake. /// /// DTLS extension "use_srtp" as defined in RFC5764 has to be enabled. - /// - /// This corresponds to [`SSL_get_selected_srtp_profile`]. - /// - /// [`SSL_get_selected_srtp_profile`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_tlsext_use_srtp.html + #[corresponds(SSL_get_selected_srtp_profile)] pub fn selected_srtp_profile(&self) -> Option<&SrtpProtectionProfileRef> { unsafe { let profile = ffi::SSL_get_selected_srtp_profile(self.as_ptr()); @@ -3442,10 +3114,7 @@ impl SslRef { /// /// If this is greater than 0, the next call to `read` will not call down to the underlying /// stream. - /// - /// This corresponds to [`SSL_pending`]. - /// - /// [`SSL_pending`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_pending.html + #[corresponds(SSL_pending)] pub fn pending(&self) -> usize { unsafe { ffi::SSL_pending(self.as_ptr()) as usize } } @@ -3454,8 +3123,6 @@ impl SslRef { /// /// It is only useful on the server side. /// - /// This corresponds to [`SSL_get_servername`]. - /// /// # Note /// /// While the SNI specification requires that servernames be valid domain names (and therefore @@ -3463,8 +3130,8 @@ impl SslRef { /// is not valid UTF-8, this function will return `None`. The `servername_raw` method returns /// the raw bytes and does not have this restriction. /// - /// [`SSL_get_servername`]: https://www.openssl.org/docs/manmaster/man3/SSL_get_servername.html // FIXME maybe rethink in 0.11? + #[corresponds(SSL_get_servername)] pub fn servername(&self, type_: NameType) -> Option<&str> { self.servername_raw(type_) .and_then(|b| str::from_utf8(b).ok()) @@ -3474,13 +3141,10 @@ impl SslRef { /// /// It is only useful on the server side. /// - /// This corresponds to [`SSL_get_servername`]. - /// /// # Note /// /// Unlike `servername`, this method does not require the name be valid UTF-8. - /// - /// [`SSL_get_servername`]: https://www.openssl.org/docs/manmaster/man3/SSL_get_servername.html + #[corresponds(SSL_get_servername)] pub fn servername_raw(&self, type_: NameType) -> Option<&[u8]> { unsafe { let name = ffi::SSL_get_servername(self.as_ptr(), type_.0); @@ -3495,17 +3159,13 @@ impl SslRef { /// Changes the context corresponding to the current connection. /// /// It is most commonly used in the Server Name Indication (SNI) callback. - /// - /// This corresponds to `SSL_set_SSL_CTX`. + #[corresponds(SSL_set_SSL_CTX)] pub fn set_ssl_context(&mut self, ctx: &SslContextRef) -> Result<(), ErrorStack> { unsafe { cvt_p(ffi::SSL_set_SSL_CTX(self.as_ptr(), ctx.as_ptr())).map(|_| ()) } } /// Returns the context corresponding to the current connection. - /// - /// This corresponds to [`SSL_get_SSL_CTX`]. - /// - /// [`SSL_get_SSL_CTX`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_get_SSL_CTX.html + #[corresponds(SSL_get_SSL_CTX)] pub fn ssl_context(&self) -> &SslContextRef { unsafe { let ssl_ctx = ffi::SSL_get_SSL_CTX(self.as_ptr()); @@ -3514,10 +3174,7 @@ impl SslRef { } /// Returns a mutable reference to the X509 verification configuration. - /// - /// This corresponds to [`SSL_get0_param`]. - /// - /// [`SSL_get0_param`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_get0_param.html + #[corresponds(SSL_get0_param)] pub fn verify_param_mut(&mut self) -> &mut X509VerifyParamRef { #[cfg(feature = "rpk")] assert!( @@ -3534,10 +3191,7 @@ impl SslRef { } /// Returns the certificate verification result. - /// - /// This corresponds to [`SSL_get_verify_result`]. - /// - /// [`SSL_get_verify_result`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_get_verify_result.html + #[corresponds(SSL_get_verify_result)] pub fn verify_result(&self) -> X509VerifyResult { #[cfg(feature = "rpk")] assert!( @@ -3549,10 +3203,7 @@ impl SslRef { } /// Returns a shared reference to the SSL session. - /// - /// This corresponds to [`SSL_get_session`]. - /// - /// [`SSL_get_session`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_session.html + #[corresponds(SSL_get_session)] pub fn session(&self) -> Option<&SslSessionRef> { unsafe { let p = ffi::SSL_get_session(self.as_ptr()); @@ -3568,10 +3219,7 @@ impl SslRef { /// /// Returns the number of bytes copied, or if the buffer is empty, the size of the client_random /// value. - /// - /// This corresponds to [`SSL_get_client_random`]. - /// - /// [`SSL_get_client_random`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_client_random.html + #[corresponds(SSL_get_client_random)] pub fn client_random(&self, buf: &mut [u8]) -> usize { unsafe { ffi::SSL_get_client_random(self.as_ptr(), buf.as_mut_ptr() as *mut c_uchar, buf.len()) @@ -3582,10 +3230,7 @@ impl SslRef { /// /// Returns the number of bytes copied, or if the buffer is empty, the size of the server_random /// value. - /// - /// This corresponds to [`SSL_get_server_random`]. - /// - /// [`SSL_get_server_random`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_client_random.html + #[corresponds(SSL_get_server_random)] pub fn server_random(&self, buf: &mut [u8]) -> usize { unsafe { ffi::SSL_get_server_random(self.as_ptr(), buf.as_mut_ptr() as *mut c_uchar, buf.len()) @@ -3593,10 +3238,7 @@ impl SslRef { } /// Derives keying material for application use in accordance to RFC 5705. - /// - /// This corresponds to [`SSL_export_keying_material`]. - /// - /// [`SSL_export_keying_material`]: https://www.openssl.org/docs/manmaster/man3/SSL_export_keying_material.html + #[corresponds(SSL_export_keying_material)] pub fn export_keying_material( &self, out: &mut [u8], @@ -3628,32 +3270,23 @@ impl SslRef { /// session. If the server is not willing to reuse the session, a new one will be transparently /// negotiated. /// - /// This corresponds to [`SSL_set_session`]. - /// /// # Safety /// /// The caller of this method is responsible for ensuring that the session is associated /// with the same `SslContext` as this `Ssl`. - /// - /// [`SSL_set_session`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_session.html + #[corresponds(SSL_set_session)] pub unsafe fn set_session(&mut self, session: &SslSessionRef) -> Result<(), ErrorStack> { cvt(ffi::SSL_set_session(self.as_ptr(), session.as_ptr())).map(|_| ()) } /// Determines if the session provided to `set_session` was successfully reused. - /// - /// This corresponds to [`SSL_session_reused`]. - /// - /// [`SSL_session_reused`]: https://www.openssl.org/docs/man1.1.0/ssl/SSL_session_reused.html + #[corresponds(SSL_session_reused)] pub fn session_reused(&self) -> bool { unsafe { ffi::SSL_session_reused(self.as_ptr()) != 0 } } /// Sets the status response a client wishes the server to reply with. - /// - /// This corresponds to [`SSL_set_tlsext_status_type`]. - /// - /// [`SSL_set_tlsext_status_type`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_set_tlsext_status_type.html + #[corresponds(SSL_set_tlsext_status_type)] pub fn set_status_type(&mut self, type_: StatusType) -> Result<(), ErrorStack> { unsafe { cvt(ffi::SSL_set_tlsext_status_type(self.as_ptr(), type_.as_raw()) as c_int).map(|_| ()) @@ -3661,10 +3294,7 @@ impl SslRef { } /// Returns the server's OCSP response, if present. - /// - /// This corresponds to [`SSL_get_tlsext_status_ocsp_resp`]. - /// - /// [`SSL_get_tlsext_status_ocsp_resp`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_set_tlsext_status_type.html + #[corresponds(SSL_get_tlsext_status_ocsp_resp)] pub fn ocsp_status(&self) -> Option<&[u8]> { unsafe { let mut p = ptr::null(); @@ -3679,10 +3309,7 @@ impl SslRef { } /// Sets the OCSP response to be returned to the client. - /// - /// This corresponds to [`SSL_set_tlsext_status_ocsp_resp`]. - /// - /// [`SSL_set_tlsext_status_ocsp_resp`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_set_tlsext_status_type.html + #[corresponds(SSL_set_tlsext_status_ocsp_resp)] pub fn set_ocsp_status(&mut self, response: &[u8]) -> Result<(), ErrorStack> { unsafe { assert!(response.len() <= c_int::MAX as usize); @@ -3698,10 +3325,7 @@ impl SslRef { } /// Determines if this `Ssl` is configured for server-side or client-side use. - /// - /// This corresponds to [`SSL_is_server`]. - /// - /// [`SSL_is_server`]: https://www.openssl.org/docs/manmaster/man3/SSL_is_server.html + #[corresponds(SSL_is_server)] pub fn is_server(&self) -> bool { unsafe { SSL_is_server(self.as_ptr()) != 0 } } @@ -3711,12 +3335,9 @@ impl SslRef { /// This can be used to provide data to callbacks registered with the context. Use the /// `Ssl::new_ex_index` method to create an `Index`. /// - /// This corresponds to [`SSL_set_ex_data`]. - /// /// Note that if this method is called multiple times with the same index, any previous /// value stored in the `SslContextBuilder` will be leaked. - /// - /// [`SSL_set_ex_data`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_ex_data.html + #[corresponds(SSL_set_ex_data)] pub fn set_ex_data(&mut self, index: Index, data: T) { if let Some(old) = self.ex_data_mut(index) { *old = data; @@ -3739,11 +3360,8 @@ impl SslRef { /// This can be used to provide data to callbacks registered with the context. Use the /// `Ssl::new_ex_index` method to create an `Index`. /// - /// This corresponds to [`SSL_set_ex_data`]. - /// /// Any previous value will be dropped and replaced by the new one. - /// - /// [`SSL_set_ex_data`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_ex_data.html + #[corresponds(SSL_set_ex_data)] pub fn replace_ex_data(&mut self, index: Index, data: T) -> Option { if let Some(old) = self.ex_data_mut(index) { return Some(mem::replace(old, data)); @@ -3755,10 +3373,7 @@ impl SslRef { } /// Returns a reference to the extra data at the specified index. - /// - /// This corresponds to [`SSL_get_ex_data`]. - /// - /// [`SSL_get_ex_data`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_ex_data.html + #[corresponds(SSL_get_ex_data)] pub fn ex_data(&self, index: Index) -> Option<&T> { unsafe { let data = ffi::SSL_get_ex_data(self.as_ptr(), index.as_raw()); @@ -3771,10 +3386,7 @@ impl SslRef { } /// Returns a mutable reference to the extra data at the specified index. - /// - /// This corresponds to [`SSL_get_ex_data`]. - /// - /// [`SSL_get_ex_data`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_ex_data.html + #[corresponds(SSL_get_ex_data)] pub fn ex_data_mut(&mut self, index: Index) -> Option<&mut T> { unsafe { let data = ffi::SSL_get_ex_data(self.as_ptr(), index.as_raw()); @@ -3790,8 +3402,7 @@ impl SslRef { /// /// The total size of the message is returned, so this can be used to determine the size of the /// buffer required. - /// - /// This corresponds to `SSL_get_finished`. + #[corresponds(SSL_get_finished)] pub fn finished(&self, buf: &mut [u8]) -> usize { unsafe { ffi::SSL_get_finished(self.as_ptr(), buf.as_mut_ptr() as *mut c_void, buf.len()) } } @@ -3801,8 +3412,7 @@ impl SslRef { /// /// The total size of the message is returned, so this can be used to determine the size of the /// buffer required. - /// - /// This corresponds to `SSL_get_peer_finished`. + #[corresponds(SSL_get_peer_finished)] pub fn peer_finished(&self, buf: &mut [u8]) -> usize { unsafe { ffi::SSL_get_peer_finished(self.as_ptr(), buf.as_mut_ptr() as *mut c_void, buf.len()) @@ -3810,26 +3420,19 @@ impl SslRef { } /// Determines if the initial handshake has been completed. - /// - /// This corresponds to [`SSL_is_init_finished`]. - /// - /// [`SSL_is_init_finished`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_is_init_finished.html + #[corresponds(SSL_is_init_finished)] pub fn is_init_finished(&self) -> bool { unsafe { ffi::SSL_is_init_finished(self.as_ptr()) != 0 } } /// Sets the MTU used for DTLS connections. - /// - /// This corresponds to `SSL_set_mtu`. + #[corresponds(SSL_set_mtu)] pub fn set_mtu(&mut self, mtu: u32) -> Result<(), ErrorStack> { unsafe { cvt(ffi::SSL_set_mtu(self.as_ptr(), mtu as c_uint) as c_int).map(|_| ()) } } /// Sets the certificate. - /// - /// This corresponds to [`SSL_use_certificate`]. - /// - /// [`SSL_use_certificate`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_use_certificate.html + #[corresponds(SSL_use_certificate)] pub fn set_certificate(&mut self, cert: &X509Ref) -> Result<(), ErrorStack> { unsafe { cvt(ffi::SSL_use_certificate(self.as_ptr(), cert.as_ptr()))?; @@ -3842,10 +3445,7 @@ impl SslRef { /// /// The CA certificates must still be added to the trust root - they are not automatically set /// as trusted by this method. - /// - /// This corresponds to [`SSL_set_client_CA_list`]. - /// - /// [`SSL_set_client_CA_list`]: https://docs.openssl.org/1.1.1/man3/SSL_CTX_set0_CA_list/ + #[corresponds(SSL_set_client_CA_list)] pub fn set_client_ca_list(&mut self, list: Stack) { #[cfg(feature = "rpk")] assert!( @@ -3858,10 +3458,7 @@ impl SslRef { } /// Sets the private key. - /// - /// This corresponds to [`SSL_use_PrivateKey`]. - /// - /// [`SSL_use_PrivateKey`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_use_PrivateKey.html + #[corresponds(SSL_use_PrivateKey)] pub fn set_private_key(&mut self, key: &PKeyRef) -> Result<(), ErrorStack> where T: HasPrivate, @@ -3871,10 +3468,7 @@ impl SslRef { /// Enables all modes set in `mode` in `SSL`. Returns a bitmask representing the resulting /// enabled modes. - /// - /// This corresponds to [`SSL_set_mode`]. - /// - /// [`SSL_set_mode`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_set_mode.html + #[corresponds(SSL_set_mode)] pub fn set_mode(&mut self, mode: SslMode) -> SslMode { let bits = unsafe { ffi::SSL_set_mode(self.as_ptr(), mode.bits()) }; SslMode::from_bits_retain(bits) @@ -3882,20 +3476,14 @@ impl SslRef { /// Disables all modes set in `mode` in `SSL`. Returns a bitmask representing the resulting /// enabled modes. - /// - /// This corresponds to [`SSL_clear_mode`]. - /// - /// [`SSL_clear_mode`]: https://www.openssl.org/docs/man3.1/man3/SSL_clear_mode.html + #[corresponds(SSL_clear_mode)] pub fn clear_mode(&mut self, mode: SslMode) -> SslMode { let bits = unsafe { ffi::SSL_clear_mode(self.as_ptr(), mode.bits()) }; SslMode::from_bits_retain(bits) } /// Appends `cert` to the chain associated with the current certificate of `SSL`. - /// - /// This corresponds to [`SSL_add1_chain_cert`]. - /// - /// [`SSL_add1_chain_cert`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_add1_chain_cert.html + #[corresponds(SSL_add1_chain_cert)] pub fn add_chain_cert(&mut self, cert: &X509Ref) -> Result<(), ErrorStack> { unsafe { cvt(ffi::SSL_add1_chain_cert(self.as_ptr(), cert.as_ptr())).map(|_| ()) } } @@ -4060,10 +3648,7 @@ impl SslStream { /// /// It is particularly useful with a nonblocking socket, where the error value will identify if /// OpenSSL is waiting on read or write readiness. - /// - /// This corresponds to [`SSL_read`]. - /// - /// [`SSL_read`]: https://www.openssl.org/docs/manmaster/man3/SSL_read.html + #[corresponds(SSL_read)] pub fn ssl_read(&mut self, buf: &mut [u8]) -> Result { // SAFETY: `ssl_read_uninit` does not de-initialize the buffer. unsafe { @@ -4098,10 +3683,7 @@ impl SslStream { /// /// It is particularly useful with a nonblocking socket, where the error value will identify if /// OpenSSL is waiting on read or write readiness. - /// - /// This corresponds to [`SSL_write`]. - /// - /// [`SSL_write`]: https://www.openssl.org/docs/manmaster/man3/SSL_write.html + #[corresponds(SSL_write)] pub fn ssl_write(&mut self, buf: &[u8]) -> Result { if buf.is_empty() { return Ok(0); @@ -4125,10 +3707,7 @@ impl SslStream { /// While the connection may be closed after the first step, it is recommended to fully shut the /// session down. In particular, it must be fully shut down if the connection is to be used for /// further communication in the future. - /// - /// This corresponds to [`SSL_shutdown`]. - /// - /// [`SSL_shutdown`]: https://www.openssl.org/docs/man1.0.2/ssl/SSL_shutdown.html + #[corresponds(SSL_shutdown)] pub fn shutdown(&mut self) -> Result { match unsafe { ffi::SSL_shutdown(self.ssl.as_ptr()) } { 0 => Ok(ShutdownResult::Sent), @@ -4138,10 +3717,7 @@ impl SslStream { } /// Returns the session's shutdown state. - /// - /// This corresponds to [`SSL_get_shutdown`]. - /// - /// [`SSL_get_shutdown`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_set_shutdown.html + #[corresponds(SSL_get_shutdown)] pub fn get_shutdown(&mut self) -> ShutdownState { unsafe { let bits = ffi::SSL_get_shutdown(self.ssl.as_ptr()); @@ -4153,19 +3729,13 @@ impl SslStream { /// /// This can be used to tell OpenSSL that the session should be cached even if a full two-way /// shutdown was not completed. - /// - /// This corresponds to [`SSL_set_shutdown`]. - /// - /// [`SSL_set_shutdown`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_set_shutdown.html + #[corresponds(SSL_set_shutdown)] pub fn set_shutdown(&mut self, state: ShutdownState) { unsafe { ffi::SSL_set_shutdown(self.ssl.as_ptr(), state.bits()) } } /// Initiates a client-side TLS handshake. - /// - /// This corresponds to [`SSL_connect`]. - /// - /// [`SSL_connect`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_connect.html + #[corresponds(SSL_connect)] pub fn connect(&mut self) -> Result<(), Error> { let ret = unsafe { ffi::SSL_connect(self.ssl.as_ptr()) }; if ret > 0 { @@ -4176,10 +3746,7 @@ impl SslStream { } /// Initiates a server-side TLS handshake. - /// - /// This corresponds to [`SSL_accept`]. - /// - /// [`SSL_accept`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_accept.html + #[corresponds(SSL_accept)] pub fn accept(&mut self) -> Result<(), Error> { let ret = unsafe { ffi::SSL_accept(self.ssl.as_ptr()) }; if ret > 0 { @@ -4190,10 +3757,7 @@ impl SslStream { } /// Initiates the handshake. - /// - /// This corresponds to [`SSL_do_handshake`]. - /// - /// [`SSL_do_handshake`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_do_handshake.html + #[corresponds(SSL_do_handshake)] pub fn do_handshake(&mut self) -> Result<(), Error> { let ret = unsafe { ffi::SSL_do_handshake(self.ssl.as_ptr()) }; if ret > 0 { @@ -4326,19 +3890,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()) } } @@ -4408,10 +3966,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(self) -> Result, HandshakeError> { let mut stream = self.inner; let ret = unsafe { ffi::SSL_do_handshake(stream.ssl.as_ptr()) }; diff --git a/boring/src/x509/mod.rs b/boring/src/x509/mod.rs index eb55c305..a90a4934 100644 --- a/boring/src/x509/mod.rs +++ b/boring/src/x509/mod.rs @@ -9,6 +9,7 @@ use foreign_types::{ForeignType, ForeignTypeRef}; use libc::{c_int, c_long, c_void}; +use openssl_macros::corresponds; use std::convert::TryInto; use std::error::Error; use std::ffi::{CStr, CString}; @@ -58,15 +59,13 @@ foreign_type_and_impl_send_sync! { impl X509StoreContext { /// Returns the index which can be used to obtain a reference to the `Ssl` associated with a /// context. + #[corresponds(SSL_get_ex_data_X509_STORE_CTX_idx)] pub fn ssl_idx() -> Result, ErrorStack> { unsafe { cvt_n(ffi::SSL_get_ex_data_X509_STORE_CTX_idx()).map(|idx| Index::from_raw(idx)) } } /// Creates a new `X509StoreContext` instance. - /// - /// This corresponds to [`X509_STORE_CTX_new`]. - /// - /// [`X509_STORE_CTX_new`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_STORE_CTX_new.html + #[corresponds(X509_STORE_CTX_new)] pub fn new() -> Result { unsafe { ffi::init(); @@ -77,10 +76,7 @@ impl X509StoreContext { impl X509StoreContextRef { /// Returns application data pertaining to an `X509` store context. - /// - /// This corresponds to [`X509_STORE_CTX_get_ex_data`]. - /// - /// [`X509_STORE_CTX_get_ex_data`]: https://www.openssl.org/docs/man1.0.2/crypto/X509_STORE_CTX_get_ex_data.html + #[corresponds(X509_STORE_CTX_get_ex_data)] pub fn ex_data(&self, index: Index) -> Option<&T> { unsafe { let data = ffi::X509_STORE_CTX_get_ex_data(self.as_ptr(), index.as_raw()); @@ -93,10 +89,7 @@ impl X509StoreContextRef { } /// Returns the verify result of the context. - /// - /// This corresponds to [`X509_STORE_CTX_get_error`]. - /// - /// [`X509_STORE_CTX_get_error`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_STORE_CTX_get_error.html + #[corresponds(X509_STORE_CTX_get_error)] pub fn verify_result(&self) -> X509VerifyResult { unsafe { X509VerifyError::from_raw(ffi::X509_STORE_CTX_get_error(self.as_ptr())) } } @@ -150,10 +143,7 @@ impl X509StoreContextRef { } /// Returns a mutable reference to the X509 verification configuration. - /// - /// This corresponds to [`X509_STORE_CTX_get0_param`]. - /// - /// [`SSL_get0_param`]: https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_get0_param.html + #[corresponds(X509_STORE_CTX_get0_param)] pub fn verify_param_mut(&mut self) -> &mut X509VerifyParamRef { unsafe { X509VerifyParamRef::from_ptr_mut(ffi::X509_STORE_CTX_get0_param(self.as_ptr())) } } @@ -164,19 +154,13 @@ impl X509StoreContextRef { /// validation error if the certificate was not valid. /// /// This will only work inside of a call to `init`. - /// - /// This corresponds to [`X509_verify_cert`]. - /// - /// [`X509_verify_cert`]: https://www.openssl.org/docs/man1.0.2/crypto/X509_verify_cert.html + #[corresponds(X509_verify_cert)] pub fn verify_cert(&mut self) -> Result { unsafe { cvt_n(ffi::X509_verify_cert(self.as_ptr())).map(|n| n != 0) } } /// Set the verify result of the context. - /// - /// This corresponds to [`X509_STORE_CTX_set_error`]. - /// - /// [`X509_STORE_CTX_set_error`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_STORE_CTX_set_error.html + #[corresponds(X509_STORE_CTX_set_error)] pub fn set_error(&mut self, result: X509VerifyResult) { unsafe { ffi::X509_STORE_CTX_set_error( @@ -191,10 +175,7 @@ impl X509StoreContextRef { /// Returns a reference to the certificate which caused the error or None if /// no certificate is relevant to the error. - /// - /// This corresponds to [`X509_STORE_CTX_get_current_cert`]. - /// - /// [`X509_STORE_CTX_get_current_cert`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_STORE_CTX_get_current_cert.html + #[corresponds(X509_STORE_CTX_get_current_cert)] pub fn current_cert(&self) -> Option<&X509Ref> { unsafe { let ptr = ffi::X509_STORE_CTX_get_current_cert(self.as_ptr()); @@ -210,19 +191,13 @@ impl X509StoreContextRef { /// chain where the error occurred. If it is zero it occurred in the end /// entity certificate, one if it is the certificate which signed the end /// entity certificate and so on. - /// - /// This corresponds to [`X509_STORE_CTX_get_error_depth`]. - /// - /// [`X509_STORE_CTX_get_error_depth`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_STORE_CTX_get_error_depth.html + #[corresponds(X509_STORE_CTX_get_error_depth)] pub fn error_depth(&self) -> u32 { unsafe { ffi::X509_STORE_CTX_get_error_depth(self.as_ptr()) as u32 } } /// Returns a reference to a complete valid `X509` certificate chain. - /// - /// This corresponds to [`X509_STORE_CTX_get0_chain`]. - /// - /// [`X509_STORE_CTX_get0_chain`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_STORE_CTX_get0_chain.html + #[corresponds(X509_STORE_CTX_get0_chain)] pub fn chain(&self) -> Option<&StackRef> { unsafe { let chain = X509_STORE_CTX_get0_chain(self.as_ptr()); @@ -241,6 +216,7 @@ pub struct X509Builder(X509); impl X509Builder { /// Creates a new builder. + #[corresponds(X509_new)] pub fn new() -> Result { unsafe { ffi::init(); @@ -249,11 +225,13 @@ impl X509Builder { } /// Sets the notAfter constraint on the certificate. + #[corresponds(X509_set1_notAfter)] pub fn set_not_after(&mut self, not_after: &Asn1TimeRef) -> Result<(), ErrorStack> { unsafe { cvt(X509_set1_notAfter(self.0.as_ptr(), not_after.as_ptr())).map(|_| ()) } } /// Sets the notBefore constraint on the certificate. + #[corresponds(X509_set1_notBefore)] pub fn set_not_before(&mut self, not_before: &Asn1TimeRef) -> Result<(), ErrorStack> { unsafe { cvt(X509_set1_notBefore(self.0.as_ptr(), not_before.as_ptr())).map(|_| ()) } } @@ -262,11 +240,13 @@ impl X509Builder { /// /// Note that the version is zero-indexed; that is, a certificate corresponding to version 3 of /// the X.509 standard should pass `2` to this method. + #[corresponds(X509_set_version)] pub fn set_version(&mut self, version: i32) -> Result<(), ErrorStack> { unsafe { cvt(ffi::X509_set_version(self.0.as_ptr(), version.into())).map(|_| ()) } } /// Sets the serial number of the certificate. + #[corresponds(X509_set_serialNumber)] pub fn set_serial_number(&mut self, serial_number: &Asn1IntegerRef) -> Result<(), ErrorStack> { unsafe { cvt(ffi::X509_set_serialNumber( @@ -278,6 +258,7 @@ impl X509Builder { } /// Sets the issuer name of the certificate. + #[corresponds(X509_set_issuer_name)] pub fn set_issuer_name(&mut self, issuer_name: &X509NameRef) -> Result<(), ErrorStack> { unsafe { cvt(ffi::X509_set_issuer_name( @@ -306,6 +287,7 @@ impl X509Builder { /// let mut x509 = boring::x509::X509::builder().unwrap(); /// x509.set_subject_name(&x509_name).unwrap(); /// ``` + #[corresponds(X509_set_subject_name)] pub fn set_subject_name(&mut self, subject_name: &X509NameRef) -> Result<(), ErrorStack> { unsafe { cvt(ffi::X509_set_subject_name( @@ -317,6 +299,7 @@ impl X509Builder { } /// Sets the public key associated with the certificate. + #[corresponds(X509_set_pubkey)] pub fn set_pubkey(&mut self, key: &PKeyRef) -> Result<(), ErrorStack> where T: HasPublic, @@ -327,6 +310,7 @@ impl X509Builder { /// Returns a context object which is needed to create certain X509 extension values. /// /// Set `issuer` to `None` if the certificate will be self-signed. + #[corresponds(X509V3_set_ctx)] pub fn x509v3_context<'a>( &'a self, issuer: Option<&'a X509Ref>, @@ -366,10 +350,7 @@ impl X509Builder { } /// Adds an X509 extension value to the certificate. - /// - /// This corresponds to [`X509_add_ext`]. - /// - /// [`X509_add_ext`]: https://www.openssl.org/docs/man1.1.0/man3/X509_get_ext.html + #[corresponds(X509_add_ext)] pub fn append_extension2(&mut self, extension: &X509ExtensionRef) -> Result<(), ErrorStack> { unsafe { cvt(ffi::X509_add_ext(self.0.as_ptr(), extension.as_ptr(), -1))?; @@ -378,6 +359,7 @@ impl X509Builder { } /// Signs the certificate with a private key. + #[corresponds(X509_sign)] pub fn sign(&mut self, key: &PKeyRef, hash: MessageDigest) -> Result<(), ErrorStack> where T: HasPrivate, @@ -401,10 +383,7 @@ foreign_type_and_impl_send_sync! { impl X509Ref { /// Returns this certificate's subject name. - /// - /// This corresponds to [`X509_get_subject_name`]. - /// - /// [`X509_get_subject_name`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_get_subject_name.html + #[corresponds(X509_get_subject_name)] pub fn subject_name(&self) -> &X509NameRef { unsafe { let name = ffi::X509_get_subject_name(self.as_ptr()); @@ -413,17 +392,13 @@ impl X509Ref { } /// Returns the hash of the certificates subject - /// - /// This corresponds to `X509_subject_name_hash`. + #[corresponds(X509_subject_name_hash)] pub fn subject_name_hash(&self) -> u32 { unsafe { ffi::X509_subject_name_hash(self.as_ptr()) as u32 } } /// Returns this certificate's subject alternative name entries, if they exist. - /// - /// This corresponds to [`X509_get_ext_d2i`] called with `NID_subject_alt_name`. - /// - /// [`X509_get_ext_d2i`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_get_ext_d2i.html + #[corresponds(X509_get_ext_d2i)] pub fn subject_alt_names(&self) -> Option> { unsafe { let stack = ffi::X509_get_ext_d2i( @@ -450,10 +425,7 @@ impl X509Ref { } /// Returns this certificate's issuer alternative name entries, if they exist. - /// - /// This corresponds to [`X509_get_ext_d2i`] called with `NID_issuer_alt_name`. - /// - /// [`X509_get_ext_d2i`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_get_ext_d2i.html + #[corresponds(X509_get_ext_d2i)] pub fn issuer_alt_names(&self) -> Option> { unsafe { let stack = ffi::X509_get_ext_d2i( @@ -471,6 +443,7 @@ impl X509Ref { } /// Returns this certificate's subject key id, if it exists. + #[corresponds(X509_get0_subject_key_id)] pub fn subject_key_id(&self) -> Option<&Asn1StringRef> { unsafe { let data = ffi::X509_get0_subject_key_id(self.as_ptr()); @@ -479,6 +452,7 @@ impl X509Ref { } /// Returns this certificate's authority key id, if it exists. + #[corresponds(X509_get0_authority_key_id)] pub fn authority_key_id(&self) -> Option<&Asn1StringRef> { unsafe { let data = ffi::X509_get0_authority_key_id(self.as_ptr());