docs: add C / s2n-tls-sys doc references to s2n-tls docs

Author: lrstewart

bindings/rust/extended/s2n-tls/src/callbacks/pkey.rs

@@ -17,6 +17,7 @@ pub enum OperationType {
     Sign(SignatureAlgorithm, HashAlgorithm),
 }
 
+/// Corresponds to [s2n_async_pkey_op].
 pub struct PrivateKeyOperation {
     raw: NonNull<s2n_async_pkey_op>,
     kind: OperationType,
@@ -66,11 +67,15 @@ impl PrivateKeyOperation {
     }
 
     /// Do we need to sign or decrypt with the private key?
+    ///
+    /// Corresponds to [s2n_async_pkey_op_get_op_type].
     pub fn kind(&self) -> Result<&OperationType, Error> {
         Ok(&self.kind)
     }
 
     /// The size of the slice returned by [`input()`]
+    ///
+    /// Corresponds to [s2n_async_pkey_op_get_input_size].
     pub fn input_size(&self) -> Result<usize, Error> {
         let mut size = 0;
         unsafe { s2n_async_pkey_op_get_input_size(self.as_ptr(), &mut size) }.into_result()?;
@@ -81,6 +86,8 @@ impl PrivateKeyOperation {
     ///
     /// If this is an [`OperationType::Sign`] operation, then this input has
     /// already been hashed and is the resultant digest.
+    ///
+    /// Corresponds to [s2n_async_pkey_op_get_input].
     pub fn input(&self, buf: &mut [u8]) -> Result<(), Error> {
         let buf_len: u32 = buf.len().try_into().map_err(|_| Error::INVALID_INPUT)?;
         let buf_ptr = buf.as_ptr() as *mut u8;
@@ -89,6 +96,9 @@ impl PrivateKeyOperation {
     }
 
     /// Sets the output of the operation
+    ///
+    /// Corresponds to [s2n_async_pkey_op_set_output],
+    /// but also automatically calls [s2n_async_pkey_op_apply].
     pub fn set_output(self, conn: &mut Connection, buf: &[u8]) -> Result<(), Error> {
         let buf_len: u32 = buf.len().try_into().map_err(|_| Error::INVALID_INPUT)?;
         let buf_ptr = buf.as_ptr();
@@ -105,6 +115,7 @@ impl PrivateKeyOperation {
 }
 
 impl Drop for PrivateKeyOperation {
+    /// Corresponds to [s2n_async_pkey_op_free].
     fn drop(&mut self) {
         unsafe {
             let _ = s2n_async_pkey_op_free(self.raw.as_ptr());

bindings/rust/extended/s2n-tls/src/callbacks/session_ticket.rs

@@ -31,6 +31,7 @@ impl SessionTicket {
         &self.0 as *const s2n_session_ticket as *mut s2n_session_ticket
     }
 
+    /// Corresponds to [s2n_session_ticket_get_lifetime].
     pub fn lifetime(&self) -> Result<Duration, Error> {
         let mut lifetime = 0;
         unsafe {
@@ -39,6 +40,7 @@ impl SessionTicket {
         Ok(Duration::new(lifetime.into(), 0))
     }
 
+    /// Corresponds to [s2n_session_ticket_get_data_len].
     #[allow(clippy::len_without_is_empty)]
     pub fn len(&self) -> Result<usize, Error> {
         let mut data_len = 0;
@@ -48,6 +50,7 @@ impl SessionTicket {
         Ok(data_len)
     }
 
+    /// Corresponds to [s2n_session_ticket_get_data].
     pub fn data(&self, output: &mut [u8]) -> Result<(), Error> {
         unsafe {
             s2n_session_ticket_get_data(self.deref_mut_ptr(), output.len(), output.as_mut_ptr())

bindings/rust/extended/s2n-tls/src/cert_chain.rs

@@ -41,6 +41,7 @@ impl CertificateChainHandle {
 }
 
 impl Drop for CertificateChainHandle {
+    /// Corresponds to [s2n_cert_chain_and_key_free].
     fn drop(&mut self) {
         // ignore failures since there's not much we can do about it
         if self.is_owned {
@@ -140,6 +141,8 @@ pub struct CertificateChain<'a> {
 
 impl CertificateChain<'_> {
     /// This allocates a new certificate chain from s2n.
+    ///
+    /// Corresponds to [s2n_cert_chain_and_key_new].
     pub(crate) fn allocate_owned() -> Result<CertificateChain<'static>, Error> {
         crate::init::init();
         unsafe {
@@ -178,6 +181,8 @@ impl CertificateChain<'_> {
     ///
     /// Note that the underyling API currently traverses a linked list, so this is a relatively
     /// expensive API to call.
+    ///
+    /// Corresponds to [s2n_cert_chain_get_length].
     pub fn len(&self) -> usize {
         let mut length: u32 = 0;
         let res = unsafe { s2n_cert_chain_get_length(self.as_ptr(), &mut length).into_result() };
@@ -219,6 +224,7 @@ pub struct CertificateChainIter<'a> {
 impl<'a> Iterator for CertificateChainIter<'a> {
     type Item = Result<Certificate<'a>, Error>;
 
+    /// Corresponds to [s2n_cert_chain_get_cert].
     fn next(&mut self) -> Option<Self::Item> {
         let idx = self.idx;
         // u32 fits into usize on platforms we support.
@@ -253,6 +259,7 @@ pub struct Certificate<'a> {
 }
 
 impl Certificate<'_> {
+    /// Corresponds to [s2n_cert_get_der].
     pub fn der(&self) -> Result<&[u8], Error> {
         unsafe {
             let mut buffer = ptr::null();

bindings/rust/extended/s2n-tls/src/client_hello.rs

@@ -22,6 +22,7 @@ use std::fmt;
 pub struct ClientHello(s2n_client_hello);
 
 impl ClientHello {
+    /// Corresponds to [s2n_client_hello_parse_message].
     pub fn parse_client_hello(hello: &[u8]) -> Result<Box<Self>, crate::error::Error> {
         crate::init::init();
         let handle = unsafe {
@@ -56,6 +57,8 @@ impl ClientHello {
         &self.0 as *const s2n_client_hello as *mut s2n_client_hello
     }
 
+    /// Corresponds to [s2n_client_hello_get_session_id], but also
+    /// calls [s2n_client_hello_get_session_id_length].
     pub fn session_id(&self) -> Result<Vec<u8>, Error> {
         let mut session_id_length = 0;
         unsafe {
@@ -77,6 +80,8 @@ impl ClientHello {
         Ok(session_id)
     }
 
+    /// Corresponds to [s2n_client_hello_get_server_name], but also
+    /// calls [s2n_client_hello_get_server_name_length].
     pub fn server_name(&self) -> Result<Vec<u8>, Error> {
         let mut server_name_length = 0;
         unsafe {
@@ -98,6 +103,8 @@ impl ClientHello {
         Ok(server_name)
     }
 
+    /// Corresponds to [s2n_client_hello_get_raw_message], but also
+    /// calls [s2n_client_hello_get_raw_message_length].
     pub fn raw_message(&self) -> Result<Vec<u8>, Error> {
         let message_length =
             unsafe { s2n_client_hello_get_raw_message_length(self.deref_mut_ptr()).into_result()? };
@@ -116,6 +123,7 @@ impl ClientHello {
 }
 
 impl Drop for ClientHello {
+    /// Corresponds to [s2n_client_hello_free].
     fn drop(&mut self) {
         let mut client_hello: *mut s2n_client_hello = &mut self.0;
         // ignore failures. There isn't anything to be done to handle them, but