Merge pull request #54 from nepalez/master

Support `ZeroizeOnDrop` for `BazeIban`

Author: ThomasdenH

iban_validate/Cargo.toml

@@ -21,10 +21,11 @@ path = "src/lib.rs"
 
 [features]
 default = []
+zeroize = ["dep:zeroize", "dep:zeroize_derive"]
 
 # Enables all features when building documentation
 [package.metadata.docs.rs]
-features = ["serde"]
+features = ["serde", "zeroize"]
 
 [dependencies.serde]
 version = "1"
@@ -36,6 +37,16 @@ features = ["derive"]
 version = "0.7"
 default-features = false
 
+[dependencies.zeroize]
+version = "1"
+optional = true
+default-features = false
+
+[dependencies.zeroize_derive]
+version = "1"
+optional = true
+default-features = false
+
 [dev-dependencies]
 proptest = "1"
 static_assertions = "1"

iban_validate/README.md

@@ -37,6 +37,7 @@ fn main() -> Result<(), ParseIbanError> {
 - A flexible API that is useful even when the country is not in the Swift registry (using [`BaseIban`]). Instead of using panic, the crate provides typed errors with what went wrong.
 - All functionality can be used in a `no_std` environment.
 - Optional serialization and deserialization via [`serde`](https://crates.io/crates/serde).
+- Optional memory zeroization when [`BaseIban`] is dropped via [`zeroize`](https://crates.io/crates/zeroize).
 - CI tested results via the Swift provided and custom test cases, as well as proptest.
 - `#![forbid(unsafe_code)]`, making sure all code is written in safe Rust.
 
@@ -55,6 +56,7 @@ iban_validate = "5"
 The following features can be used to configure the crate:
 
 - _serde_: Enable `serde` support for [`Iban`] and [`BaseIban`].
+- _zeroize_: Support `ZeroizeOnDrop` for the [`BaseIban`].
 
 ## Contributing
 

iban_validate/src/base_iban.rs

@@ -7,6 +7,8 @@ use core::str::FromStr;
 use core::{convert::TryFrom, error::Error};
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
+#[cfg(feature = "zeroize")]
+use zeroize_derive::ZeroizeOnDrop;
 
 /// The size of a group of characters in the paper format.
 const PAPER_GROUP_SIZE: usize = 4;
@@ -85,7 +87,19 @@ const MAX_IBAN_LEN: usize = 34;
 /// assert_eq!(&format!("{}", iban), "RO66 BACX 0000 0012 3456 7890");
 /// # Ok::<(), ParseBaseIbanError>(())
 /// ```
-#[derive(Copy, Clone, Eq, PartialEq, Hash)]
+///
+/// ## Zeroization
+/// If the `zeroize` feature is enabled, then both `BaseIban` itself
+/// and temporary objects used during parsing will be zeroed
+/// when they go out of scope. This can help to
+/// prevent sensitive data from lingering in memory.
+///
+/// NOTICE that zeroization is NOT compatible to `Copy` trait,
+/// that's why the `BaseIban` does not implement `Copy`
+/// when the "zeroize" feature is enabled.
+#[derive(Clone, Eq, PartialEq, Hash)]
+#[cfg_attr(not(feature = "zeroize"), derive(Copy))]
+#[cfg_attr(feature = "zeroize", derive(ZeroizeOnDrop))]
 pub struct BaseIban {
     /// The string representing the IBAN. The string contains only uppercase
     /// ASCII and digits and no whitespace. It starts with two letters followed
@@ -261,13 +275,16 @@ impl BaseIban {
     /// Parse a standardized IBAN string from an iterator. We iterate through
     /// bytes, not characters. When a character is not ASCII, the IBAN is
     /// automatically invalid.
-    fn try_form_string_from_electronic<T>(
-        mut chars: T,
-    ) -> Result<ArrayString<MAX_IBAN_LEN>, ParseBaseIbanError>
+    ///
+    /// SECURITY: If the `zeroized` feature is turned on, then all temporary
+    /// objects are zeroized in the memory.
+    fn try_form_string_from_electronic<T>(mut chars: T) -> Result<Self, ParseBaseIbanError>
     where
         T: Iterator<Item = u8>,
     {
-        let mut address_no_spaces = ArrayString::<MAX_IBAN_LEN>::new();
+        let mut output = Self {
+            s: ArrayString::<MAX_IBAN_LEN>::new(),
+        };
 
         // First expect exactly two uppercase letters and append them to the
         // string.
@@ -276,7 +293,8 @@ impl BaseIban {
                 .next()
                 .filter(u8::is_ascii_uppercase)
                 .ok_or(ParseBaseIbanError::InvalidFormat)?;
-            address_no_spaces
+            output
+                .s
                 .try_push(c as char)
                 .map_err(|_| ParseBaseIbanError::InvalidFormat)?;
         }
@@ -287,7 +305,8 @@ impl BaseIban {
                 .next()
                 .filter(u8::is_ascii_digit)
                 .ok_or(ParseBaseIbanError::InvalidFormat)?;
-            address_no_spaces
+            output
+                .s
                 .try_push(c as char)
                 .map_err(|_| ParseBaseIbanError::InvalidFormat)?;
         }
@@ -298,21 +317,20 @@ impl BaseIban {
         // destination string.
         for c in chars {
             if c.is_ascii_alphanumeric() {
-                address_no_spaces
+                output
+                    .s
                     .try_push(c.to_ascii_uppercase() as char)
                     .map_err(|_| ParseBaseIbanError::InvalidFormat)?;
             } else {
                 return Err(ParseBaseIbanError::InvalidFormat);
             }
         }
 
-        Ok(address_no_spaces)
+        Ok(output)
     }
 
     /// Parse a pretty print 'paper' IBAN from a `str`.
-    fn try_form_string_from_pretty_print(
-        s: &str,
-    ) -> Result<ArrayString<MAX_IBAN_LEN>, ParseBaseIbanError> {
+    fn try_form_string_from_pretty_print(s: &str) -> Result<Self, ParseBaseIbanError> {
         // The pretty print format consists of a number of groups of four
         // characters, separated by a space.
 
@@ -357,17 +375,14 @@ impl FromStr for BaseIban {
     /// invalid, an [`ParseBaseIbanError`](crate::ParseBaseIbanError) will be
     /// returned.
     fn from_str(address: &str) -> Result<Self, Self::Err> {
-        let address_no_spaces =
-            BaseIban::try_form_string_from_electronic(address.as_bytes().iter().copied())
-                .or_else(|_| BaseIban::try_form_string_from_pretty_print(address))?;
+        let output = BaseIban::try_form_string_from_electronic(address.as_bytes().iter().copied())
+            .or_else(|_| BaseIban::try_form_string_from_pretty_print(address))?;
 
-        if !BaseIban::validate_checksum(&address_no_spaces) {
-            return Err(ParseBaseIbanError::InvalidChecksum);
+        if BaseIban::validate_checksum(&output.s) {
+            Ok(output)
+        } else {
+            Err(ParseBaseIbanError::InvalidChecksum)
         }
-
-        Ok(BaseIban {
-            s: address_no_spaces,
-        })
     }
 }
 

iban_validate/src/lib.rs

@@ -235,7 +235,16 @@ impl Display for Iban {
 /// # Ok::<(), ParseIbanError>(())
 /// ```
 /// [`parse()`]: https://doc.rust-lang.org/std/primitive.str.html#method.parse
-#[derive(Clone, Copy, Eq, PartialEq, Hash)]
+///
+/// ## Zeroization
+/// If the `zeroize` feature is enabled, then a `BaseIban`
+/// wrapped by the `Iban` will be zeroed upon a drop.
+///
+/// NOTICE that zeroization is NOT compatible to `Copy` trait,
+/// that's why the `Iban` does not implement `Copy`
+/// when the "zeroize" feature is enabled.
+#[derive(Clone, Eq, PartialEq, Hash)]
+#[cfg_attr(not(feature = "zeroize"), derive(Copy))]
 pub struct Iban {
     /// The inner IBAN, which has been checked.
     base_iban: BaseIban,
@@ -257,13 +266,22 @@ pub struct Iban {
 /// // The following IBAN doesn't follow the country format
 /// let base_iban: BaseIban = "AL84212110090000AB023569874".parse()?;
 /// assert_eq!(
-///     Iban::try_from(base_iban),
+///     Iban::try_from(base_iban.clone()),
 ///     Err(ParseIbanError::InvalidBban(base_iban))
 /// );
 /// # Ok::<(), ParseBaseIbanError>(())
 /// ```
-#[derive(Copy, Clone, Eq, PartialEq, Debug, Hash)]
+///
+/// ## Zeroization
+/// If the `zeroize` feature is enabled, then the `BaseIban`
+/// wrapped by the `ParseIbanError` will be zeroed upon a drop.
+///
+/// NOTICE that zeroization is NOT compatible to `Copy` trait,
+/// that's why the `ParseIbanError` does not implement `Copy`
+/// when the "zeroize" feature is enabled.
+#[derive(Clone, Eq, PartialEq, Debug, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[cfg_attr(not(feature = "zeroize"), derive(Copy))]
 pub enum ParseIbanError {
     /// This variant indicates that the basic IBAN structure was not followed.
     InvalidBaseIban {
@@ -357,15 +375,24 @@ impl TryFrom<BaseIban> for Iban {
     /// access to some basic functionality nonetheless.
     fn try_from(base_iban: BaseIban) -> Result<Iban, ParseIbanError> {
         use countries::Matchable;
-        generated::country_pattern(base_iban.country_code())
-            .ok_or(ParseIbanError::UnknownCountry(base_iban))
-            .and_then(|matcher: &[(usize, _)]| {
-                if matcher.match_str(base_iban.bban_unchecked()) {
-                    Ok(Iban { base_iban })
-                } else {
-                    Err(ParseIbanError::InvalidBban(base_iban))
-                }
-            })
+
+        #[cfg(not(feature = "zeroize"))]
+        let pattern = generated::country_pattern(base_iban.country_code())
+            .ok_or(ParseIbanError::UnknownCountry(base_iban));
+
+        #[cfg(feature = "zeroize")]
+        let binding = base_iban.clone();
+        #[cfg(feature = "zeroize")]
+        let pattern = generated::country_pattern(binding.country_code())
+            .ok_or(ParseIbanError::UnknownCountry(base_iban.clone()));
+
+        pattern.and_then(|matcher: &[(usize, _)]| {
+            if matcher.match_str(base_iban.bban_unchecked()) {
+                Ok(Iban { base_iban })
+            } else {
+                Err(ParseIbanError::InvalidBban(base_iban))
+            }
+        })
     }
 }
 

iban_validate/tests/as_ref.rs

@@ -13,7 +13,7 @@ fn test_as_ref() -> Result<(), Box<dyn Error>> {
         base_iban.to_string()
     }
 
-    let s = pretty_format(iban);
+    let s = pretty_format(&iban);
     assert_eq!(s.as_str(), "KW81 CBKU 0000 0000 0000 1234 5601 01");
     assert_eq!(iban.to_string(), s);
 

iban_validate/tests/impls.rs

@@ -5,10 +5,11 @@ use core::hash::Hash;
 use core::str::FromStr;
 use iban::{BaseIban, Iban, ParseBaseIbanError, ParseIbanError};
 use static_assertions::assert_impl_all;
+#[cfg(feature = "zeroize")]
+use zeroize::ZeroizeOnDrop;
 
 assert_impl_all!(
-    BaseIban: Copy,
-    Clone,
+    BaseIban: Clone,
     Eq,
     PartialEq,
     Hash,
@@ -23,8 +24,7 @@ assert_impl_all!(
     AsMut<BaseIban>
 );
 assert_impl_all!(
-    Iban: Copy,
-    Clone,
+    Iban: Clone,
     Eq,
     PartialEq,
     Hash,
@@ -43,8 +43,7 @@ assert_impl_all!(
     AsMut<Iban>
 );
 assert_impl_all!(
-    ParseBaseIbanError: Copy,
-    Clone,
+    ParseBaseIbanError: Clone,
     Eq,
     PartialEq,
     Hash,
@@ -57,8 +56,7 @@ assert_impl_all!(
     AsMut<ParseBaseIbanError>
 );
 assert_impl_all!(
-    ParseIbanError: Copy,
-    Clone,
+    ParseIbanError: Clone,
     Eq,
     PartialEq,
     Hash,
@@ -74,6 +72,17 @@ assert_impl_all!(
 assert_impl_all!(ParseBaseIbanError: core::error::Error);
 assert_impl_all!(ParseIbanError: core::error::Error);
 
+#[cfg(not(feature = "zeroize"))]
+assert_impl_all!(BaseIban: Copy);
+#[cfg(not(feature = "zeroize"))]
+assert_impl_all!(Iban: Copy);
+#[cfg(not(feature = "zeroize"))]
+assert_impl_all!(ParseBaseIbanError: Copy);
+#[cfg(not(feature = "zeroize"))]
+assert_impl_all!(ParseIbanError: Copy);
+#[cfg(feature = "zeroize")]
+assert_impl_all!(BaseIban: ZeroizeOnDrop);
+
 #[cfg(feature = "serde")]
 mod impls_serde {
     use super::{assert_impl_all, BaseIban, Iban};

iban_validate/tests/zeroize.rs

@@ -0,0 +1,23 @@
+#![cfg(feature = "zeroize")]
+
+use iban::{BaseIban, IbanLike};
+use zeroize::Zeroize;
+
+#[test]
+fn zeroize() {
+    let mut base_iban = "DE44500105175407324931"
+        .parse::<BaseIban>()
+        .expect("valid IBAN");
+
+    assert_eq!(
+        base_iban.electronic_str(),
+        String::from("DE44500105175407324931")
+    );
+
+    base_iban.zeroize();
+
+    assert_eq!(
+        base_iban.electronic_str(),
+        String::from("\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0")
+    );
+}