Rust wrapper: support optional heap and dev_id parameters

Author: holtrop-wolfssl

wrapper/rust/wolfssl/src/wolfcrypt/aes.rs

@@ -34,7 +34,7 @@ use wolfssl_sys as ws;
 /// # Example
 /// ```rust
 /// use wolfssl::wolfcrypt::aes::CBC;
-/// let mut cbc = CBC::new().expect("Failed to create CBC");
+/// let mut cbc = CBC::new(None, None).expect("Failed to create CBC");
 /// let key: &[u8; 16] = b"0123456789abcdef";
 /// let iv: &[u8; 16] = b"1234567890abcdef";
 /// let msg: [u8; 16] = [
@@ -60,12 +60,17 @@ pub struct CBC {
 impl CBC {
     /// Create a new `CBC` instance.
     ///
+    /// # Parameters
+    ///
+    /// * `heap`: Optional heap hint.
+    /// * `dev_id` Optional device ID to use with crypto callbacks or async hardware.
+    ///
     /// # Returns
     ///
     /// A Result which is Ok(CBC) on success or an Err containing the wolfSSL
     /// library return code on failure.
-    pub fn new() -> Result<Self, i32> {
-        let ws_aes = new_ws_aes()?;
+    pub fn new(heap: Option<*mut std::os::raw::c_void>, dev_id: Option<i32>) -> Result<Self, i32> {
+        let ws_aes = new_ws_aes(heap, dev_id)?;
         let cbc = CBC {ws_aes};
         Ok(cbc)
     }
@@ -225,7 +230,7 @@ impl Drop for CBC {
 ///     0x17, 0xe8, 0xd1, 0x2c, 0xfd, 0xf9, 0x26, 0xe0
 /// ];
 ///
-/// let mut ccm = CCM::new().expect("Failed to create CCM");
+/// let mut ccm = CCM::new(None, None).expect("Failed to create CCM");
 /// ccm.init(&key).expect("Error with init()");
 /// let mut auth_tag_out: [u8; 8] = [0; 8];
 /// let mut cipher_out: [u8; 23] = [0; 23];
@@ -245,12 +250,17 @@ pub struct CCM {
 impl CCM {
     /// Create a new `CCM` instance.
     ///
+    /// # Parameters
+    ///
+    /// * `heap`: Optional heap hint.
+    /// * `dev_id` Optional device ID to use with crypto callbacks or async hardware.
+    ///
     /// # Returns
     ///
     /// A Result which is Ok(CCM) on success or an Err containing the wolfSSL
     /// library return code on failure.
-    pub fn new() -> Result<Self, i32> {
-        let ws_aes = new_ws_aes()?;
+    pub fn new(heap: Option<*mut std::os::raw::c_void>, dev_id: Option<i32>) -> Result<Self, i32> {
+        let ws_aes = new_ws_aes(heap, dev_id)?;
         let ccm = CCM {ws_aes};
         Ok(ccm)
     }
@@ -380,7 +390,7 @@ impl Drop for CCM {
 /// # Example
 /// ```rust
 /// use wolfssl::wolfcrypt::aes::CFB;
-/// let mut cfb = CFB::new().expect("Failed to create CFB");
+/// let mut cfb = CFB::new(None, None).expect("Failed to create CFB");
 /// let key: [u8; 16] = [
 ///     0x2b,0x7e,0x15,0x16,0x28,0xae,0xd2,0xa6,
 ///     0xab,0xf7,0x15,0x88,0x09,0xcf,0x4f,0x3c
@@ -421,12 +431,17 @@ pub struct CFB {
 impl CFB {
     /// Create a new `CFB` instance.
     ///
+    /// # Parameters
+    ///
+    /// * `heap`: Optional heap hint.
+    /// * `dev_id` Optional device ID to use with crypto callbacks or async hardware.
+    ///
     /// # Returns
     ///
     /// A Result which is Ok(CFB) on success or an Err containing the wolfSSL
     /// library return code on failure.
-    pub fn new() -> Result<Self, i32> {
-        let ws_aes = new_ws_aes()?;
+    pub fn new(heap: Option<*mut std::os::raw::c_void>, dev_id: Option<i32>) -> Result<Self, i32> {
+        let ws_aes = new_ws_aes(heap, dev_id)?;
         let cfb = CFB {ws_aes};
         Ok(cfb)
     }
@@ -690,7 +705,7 @@ impl Drop for CFB {
 ///     0x1e,0x03,0x1d,0xda,0x2f,0xbe,0x03,0xd1,
 ///     0x79,0x21,0x70,0xa0,0xf3,0x00,0x9c,0xee
 /// ];
-/// let mut ctr = CTR::new().expect("Failed to create CTR");
+/// let mut ctr = CTR::new(None, None).expect("Failed to create CTR");
 /// ctr.init(&key, &iv).expect("Error with init()");
 /// let mut outbuf: [u8; 64] = [0; 64];
 /// ctr.encrypt(&msg, &mut outbuf).expect("Error with encrypt()");
@@ -706,12 +721,17 @@ pub struct CTR {
 impl CTR {
     /// Create a new `CTR` instance.
     ///
+    /// # Parameters
+    ///
+    /// * `heap`: Optional heap hint.
+    /// * `dev_id` Optional device ID to use with crypto callbacks or async hardware.
+    ///
     /// # Returns
     ///
     /// A Result which is Ok(CTR) on success or an Err containing the wolfSSL
     /// library return code on failure.
-    pub fn new() -> Result<Self, i32> {
-        let ws_aes = new_ws_aes()?;
+    pub fn new(heap: Option<*mut std::os::raw::c_void>, dev_id: Option<i32>) -> Result<Self, i32> {
+        let ws_aes = new_ws_aes(heap, dev_id)?;
         let ctr = CTR {ws_aes};
         Ok(ctr)
     }
@@ -948,7 +968,7 @@ impl EAX {
 /// # Example
 /// ```rust
 /// use wolfssl::wolfcrypt::aes::ECB;
-/// let mut ecb = ECB::new().expect("Failed to create ECB");
+/// let mut ecb = ECB::new(None, None).expect("Failed to create ECB");
 /// let key_128: &[u8; 16] = b"0123456789abcdef";
 /// let msg: [u8; 16] = [
 ///     0x6e, 0x6f, 0x77, 0x20, 0x69, 0x73, 0x20, 0x74,
@@ -973,12 +993,17 @@ pub struct ECB {
 impl ECB {
     /// Create a new `ECB` instance.
     ///
+    /// # Parameters
+    ///
+    /// * `heap`: Optional heap hint.
+    /// * `dev_id` Optional device ID to use with crypto callbacks or async hardware.
+    ///
     /// # Returns
     ///
     /// A Result which is Ok(ECB) on success or an Err containing the wolfSSL
     /// library return code on failure.
-    pub fn new() -> Result<Self, i32> {
-        let ws_aes = new_ws_aes()?;
+    pub fn new(heap: Option<*mut std::os::raw::c_void>, dev_id: Option<i32>) -> Result<Self, i32> {
+        let ws_aes = new_ws_aes(heap, dev_id)?;
         let ecb = ECB {ws_aes};
         Ok(ecb)
     }
@@ -1137,7 +1162,7 @@ impl Drop for ECB {
 ///     0x54, 0x24, 0x65, 0xef, 0x59, 0x93, 0x16, 0xf7,
 ///     0x3a, 0x7a, 0x56, 0x05, 0x09, 0xa2, 0xd9, 0xf2
 /// ];
-/// let mut gcm = GCM::new().expect("Failed to create GCM");
+/// let mut gcm = GCM::new(None, None).expect("Failed to create GCM");
 /// gcm.init(&key).expect("Error with init()");
 /// let mut cipher: [u8; 32] = [0; 32];
 /// let mut auth_tag: [u8; 16] = [0; 16];
@@ -1154,12 +1179,17 @@ pub struct GCM {
 impl GCM {
     /// Create a new `GCM` instance.
     ///
+    /// # Parameters
+    ///
+    /// * `heap`: Optional heap hint.
+    /// * `dev_id` Optional device ID to use with crypto callbacks or async hardware.
+    ///
     /// # Returns
     ///
     /// A Result which is Ok(GCM) on success or an Err containing the wolfSSL
     /// library return code on failure.
-    pub fn new() -> Result<Self, i32> {
-        let ws_aes = new_ws_aes()?;
+    pub fn new(heap: Option<*mut std::os::raw::c_void>, dev_id: Option<i32>) -> Result<Self, i32> {
+        let ws_aes = new_ws_aes(heap, dev_id)?;
         let gcm = GCM {ws_aes};
         Ok(gcm)
     }
@@ -1333,7 +1363,7 @@ impl Drop for GCM {
 ///     0x76, 0xfc, 0x6e, 0xce, 0x0f, 0x4e, 0x17, 0x68,
 ///     0xcd, 0xdf, 0x88, 0x53, 0xbb, 0x2d, 0x55, 0x1b
 /// ];
-/// let mut gcmstream = GCMStream::new().expect("Failed to create GCMStream");
+/// let mut gcmstream = GCMStream::new(None, None).expect("Failed to create GCMStream");
 /// for chunk_size in 1..=auth.len() {
 ///     gcmstream.init(&key, &iv).expect("Error with init()");
 ///     let mut cipher: [u8; 60] = [0; 60];
@@ -1367,12 +1397,17 @@ pub struct GCMStream {
 impl GCMStream {
     /// Create a new `GCMStream` instance.
     ///
+    /// # Parameters
+    ///
+    /// * `heap`: Optional heap hint.
+    /// * `dev_id` Optional device ID to use with crypto callbacks or async hardware.
+    ///
     /// # Returns
     ///
     /// A Result which is Ok(GCMStream) on success or an Err containing the
     /// wolfSSL library return code on failure.
-    pub fn new() -> Result<Self, i32> {
-        let ws_aes = new_ws_aes()?;
+    pub fn new(heap: Option<*mut std::os::raw::c_void>, dev_id: Option<i32>) -> Result<Self, i32> {
+        let ws_aes = new_ws_aes(heap, dev_id)?;
         let gcmstream = GCMStream {ws_aes};
         Ok(gcmstream)
     }
@@ -1584,7 +1619,7 @@ impl Drop for GCMStream {
 ///     0x04,0x53,0xe1,0x73,0xf5,0x18,0x74,0xae,
 ///     0xfd,0x64,0xa2,0xe1,0xe2,0x76,0x13,0xb0
 /// ];
-/// let mut ofb = OFB::new().expect("Failed to create OFB");
+/// let mut ofb = OFB::new(None, None).expect("Failed to create OFB");
 /// ofb.init(&key, &iv).expect("Error with init()");
 /// let mut cipher: [u8; 48] = [0; 48];
 /// ofb.encrypt(&plain, &mut cipher).expect("Error with encrypt()");
@@ -1600,12 +1635,17 @@ pub struct OFB {
 impl OFB {
     /// Create a new `OFB` instance.
     ///
+    /// # Parameters
+    ///
+    /// * `heap`: Optional heap hint.
+    /// * `dev_id` Optional device ID to use with crypto callbacks or async hardware.
+    ///
     /// # Returns
     ///
     /// A Result which is Ok(OFB) on success or an Err containing the wolfSSL
     /// library return code on failure.
-    pub fn new() -> Result<Self, i32> {
-        let ws_aes = new_ws_aes()?;
+    pub fn new(heap: Option<*mut std::os::raw::c_void>, dev_id: Option<i32>) -> Result<Self, i32> {
+        let ws_aes = new_ws_aes(heap, dev_id)?;
         let ofb = OFB {ws_aes};
         Ok(ofb)
     }
@@ -1749,7 +1789,7 @@ impl Drop for OFB {
 ///     0x77, 0x8a, 0xe8, 0xb4, 0x3c, 0xb9, 0x8d, 0x5a
 /// ];
 ///
-/// let mut xts = XTS::new().expect("Failed to create XTS");
+/// let mut xts = XTS::new(None, None).expect("Failed to create XTS");
 /// xts.init_encrypt(&key).expect("Error with init_encrypt()");
 /// let mut cipher: [u8; 16] = [0; 16];
 /// xts.encrypt(&plain, &mut cipher, &tweak).expect("Error with encrypt()");
@@ -1774,12 +1814,17 @@ pub struct XTS {
 impl XTS {
     /// Create a new `XTS` instance.
     ///
+    /// # Parameters
+    ///
+    /// * `heap`: Optional heap hint.
+    /// * `dev_id` Optional device ID to use with crypto callbacks or async hardware.
+    ///
     /// # Returns
     ///
     /// A Result which is Ok(XTS) on success or an Err containing the wolfSSL
     /// library return code on failure.
-    pub fn new() -> Result<Self, i32> {
-        let ws_xtsaes = new_ws_xtsaes()?;
+    pub fn new(heap: Option<*mut std::os::raw::c_void>, dev_id: Option<i32>) -> Result<Self, i32> {
+        let ws_xtsaes = new_ws_xtsaes(heap, dev_id)?;
         let xts = XTS {ws_xtsaes};
         Ok(xts)
     }
@@ -2100,7 +2145,7 @@ impl Drop for XTS {
 ///     0xB5, 0x5A, 0xDD, 0xCB, 0x80, 0xE0, 0xFC, 0xCD
 /// ];
 ///
-/// let mut xtsstream = XTSStream::new().expect("Failed to create XTSStream");
+/// let mut xtsstream = XTSStream::new(None, None).expect("Failed to create XTSStream");
 /// xtsstream.init_encrypt(&keys, &tweak).expect("Error with init_encrypt()");
 /// let mut cipher: [u8; 40] = [0; 40];
 /// xtsstream.encrypt_update(&plain[0..16], &mut cipher[0..16]).expect("Error with encrypt_update()");
@@ -2120,12 +2165,17 @@ pub struct XTSStream {
 impl XTSStream {
     /// Create a new `XTSStream` instance.
     ///
+    /// # Parameters
+    ///
+    /// * `heap`: Optional heap hint.
+    /// * `dev_id` Optional device ID to use with crypto callbacks or async hardware.
+    ///
     /// # Returns
     ///
     /// A Result which is Ok(XTSStream) on success or an Err containing the
     /// wolfSSL library return code on failure.
-    pub fn new() -> Result<Self, i32> {
-        let ws_xtsaes = new_ws_xtsaes()?;
+    pub fn new(heap: Option<*mut std::os::raw::c_void>, dev_id: Option<i32>) -> Result<Self, i32> {
+        let ws_xtsaes = new_ws_xtsaes(heap, dev_id)?;
         let ws_xtsaesstreamdata: MaybeUninit<ws::XtsAesStreamData> = MaybeUninit::uninit();
         let ws_xtsaesstreamdata = unsafe { ws_xtsaesstreamdata.assume_init() };
         let xtsstream = XTSStream {ws_xtsaes, ws_xtsaesstreamdata};
@@ -2353,10 +2403,18 @@ impl Drop for XTSStream {
     }
 }
 
-fn new_ws_aes() -> Result<ws::Aes, i32> {
+fn new_ws_aes(heap: Option<*mut std::os::raw::c_void>, dev_id: Option<i32>) -> Result<ws::Aes, i32> {
+    let heap = match heap {
+        Some(heap) => heap,
+        None => core::ptr::null_mut(),
+    };
+    let dev_id = match dev_id {
+        Some(dev_id) => dev_id,
+        None => ws::INVALID_DEVID,
+    };
     let mut ws_aes: MaybeUninit<ws::Aes> = MaybeUninit::uninit();
     let rc = unsafe {
-        ws::wc_AesInit(ws_aes.as_mut_ptr(), core::ptr::null_mut(), ws::INVALID_DEVID)
+        ws::wc_AesInit(ws_aes.as_mut_ptr(), heap, dev_id)
     };
     if rc != 0 {
         return Err(rc);
@@ -2365,10 +2423,18 @@ fn new_ws_aes() -> Result<ws::Aes, i32> {
     Ok(ws_aes)
 }
 
-fn new_ws_xtsaes() -> Result<ws::XtsAes, i32> {
+fn new_ws_xtsaes(heap: Option<*mut std::os::raw::c_void>, dev_id: Option<i32>) -> Result<ws::XtsAes, i32> {
+    let heap = match heap {
+        Some(heap) => heap,
+        None => core::ptr::null_mut(),
+    };
+    let dev_id = match dev_id {
+        Some(dev_id) => dev_id,
+        None => ws::INVALID_DEVID,
+    };
     let mut ws_xtsaes: MaybeUninit<ws::XtsAes> = MaybeUninit::uninit();
     let rc = unsafe {
-        ws::wc_AesXtsInit(ws_xtsaes.as_mut_ptr(), core::ptr::null_mut(), ws::INVALID_DEVID)
+        ws::wc_AesXtsInit(ws_xtsaes.as_mut_ptr(), heap, dev_id)
     };
     if rc != 0 {
         return Err(rc);