der_derive: add BitString macro (#1720)

* der: add BitString trait for BitString macro

der_derive: add BitString macro

* fix cargo clippy

* docs: BitString macro

Author: dishmaker

der/src/asn1.rs

@@ -5,7 +5,7 @@
 mod internal_macros;
 
 mod any;
-mod bit_string;
+pub(crate) mod bit_string;
 #[cfg(feature = "alloc")]
 mod bmp_string;
 mod boolean;

der/src/asn1/bit_string.rs

@@ -1,5 +1,7 @@
 //! ASN.1 `BIT STRING` support.
 
+pub mod fixed_len_bit_string;
+
 use crate::{
     BytesRef, DecodeValue, DerOrd, EncodeValue, Error, ErrorKind, FixedTag, Header, Length, Reader,
     Result, Tag, ValueOrd, Writer,
@@ -118,6 +120,17 @@ impl<'a> BitStringRef<'a> {
             position: 0,
         }
     }
+
+    /// Returns Some(bit) if index is valid
+    pub fn get(&self, position: usize) -> Option<bool> {
+        if position >= self.bit_len() {
+            return None;
+        }
+
+        let byte = self.raw_bytes().get(position / 8)?;
+        let bitmask = 1u8 << (7 - (position % 8));
+        Some(byte & bitmask != 0)
+    }
 }
 
 impl_any_conversions!(BitStringRef<'a>, 'a);
@@ -309,6 +322,11 @@ mod allocating {
         pub fn bits(&self) -> BitStringIter<'_> {
             BitStringRef::from(self).bits()
         }
+
+        /// Returns Some(bit) if index is valid
+        pub fn get(&self, position: usize) -> Option<bool> {
+            BitStringRef::from(self).get(position)
+        }
     }
 
     impl_any_conversions!(BitString);

der/src/asn1/bit_string/fixed_len_bit_string.rs

@@ -0,0 +1,48 @@
+use core::ops::RangeInclusive;
+
+use crate::{Error, ErrorKind, Tag};
+
+/// Trait on automatically derived by BitString macro.
+/// Used for checking if binary data fits into defined struct.
+///
+/// ```
+/// /// Bit length of 2
+/// struct MyBitString {
+///     flag1: bool,
+///     flag2: bool,
+/// }
+/// ```
+///
+/// ```rust,ignore
+/// use der::BitString;
+///
+/// /// Bit length of 3..=4
+/// #[derive(BitString)]
+/// struct MyBitString {
+///     flag1: bool,
+///     flag2: bool,
+///     flag3: bool,
+///
+///     #[asn1(optional = "true")]
+///     flag4: bool,
+/// }
+/// ```
+pub trait FixedLenBitString {
+    /// Implementer must specify how many bits are allowed
+    const ALLOWED_LEN_RANGE: RangeInclusive<u16>;
+
+    /// Returns an error if the bitstring is not in expected length range
+    fn check_bit_len(bit_len: u16) -> Result<(), Error> {
+        let allowed_len_range = Self::ALLOWED_LEN_RANGE;
+
+        // forces allowed range to eg. 3..=4
+        if !allowed_len_range.contains(&bit_len) {
+            Err(ErrorKind::Length {
+                tag: Tag::BitString,
+            }
+            .into())
+        } else {
+            Ok(())
+        }
+    }
+}

der/src/lib.rs

@@ -365,6 +365,7 @@ mod document;
 mod str_owned;
 
 pub use crate::{
+    asn1::bit_string::fixed_len_bit_string::FixedLenBitString,
     asn1::{AnyRef, Choice, Sequence},
     datetime::DateTime,
     decode::{Decode, DecodeOwned, DecodeValue},
@@ -384,7 +385,7 @@ pub use crate::{
 pub use crate::{asn1::Any, document::Document};
 
 #[cfg(feature = "derive")]
-pub use der_derive::{Choice, Enumerated, Sequence, ValueOrd};
+pub use der_derive::{BitString, Choice, Enumerated, Sequence, ValueOrd};
 
 #[cfg(feature = "flagset")]
 pub use flagset;

der/tests/derive.rs

@@ -627,6 +627,164 @@ mod sequence {
     }
 }
 
+/// Custom derive test cases for the `BitString` macro.
+#[cfg(feature = "std")]
+mod bitstring {
+    use der::BitString;
+    use der::Decode;
+    use der::Encode;
+    use hex_literal::hex;
+
+    const BITSTRING_EXAMPLE: &[u8] = &hex!("03 03 06 03 80");
+
+    // this BitString allows only 10..=10 bits
+    #[derive(BitString)]
+    pub struct MyBitStringTest {
+        pub first_bit: bool,
+        pub second_bit: bool,
+        pub third_bit: bool,
+        pub fourth_bit: bool,
+        pub a: bool,
+        pub b: bool,
+        pub almost_least_significant: bool,
+        pub least_significant_bit: bool,
+
+        // second byte
+        pub second_byte_bit: bool,
+        pub second_byte_bit2: bool,
+    }
+
+    #[test]
+    fn decode_bitstring() {
+        let test_flags = MyBitStringTest::from_der(BITSTRING_EXAMPLE).unwrap();
+
+        assert!(!test_flags.first_bit);
+
+        assert!(test_flags.almost_least_significant);
+        assert!(test_flags.least_significant_bit);
+        assert!(test_flags.second_byte_bit);
+        assert!(!test_flags.second_byte_bit2);
+
+        let reencoded = test_flags.to_der().unwrap();
+
+        assert_eq!(reencoded, BITSTRING_EXAMPLE);
+    }
+
+    /// this BitString will allow only 3..=4 bits
+    #[derive(BitString)]
+    pub struct MyBitString3or4 {
+        pub bit_0: bool,
+        pub bit_1: bool,
+        pub bit_2: bool,
+
+        #[asn1(optional = "true")]
+        pub bit_3: bool,
+    }
+
+    #[test]
+    fn decode_bitstring_3_used_first_lit() {
+        // 5 unused bits, so 3 used
+        let bits_3 = MyBitString3or4::from_der(&hex!("03 02 05 80")).unwrap();
+
+        assert!(bits_3.bit_0);
+        assert!(!bits_3.bit_1);
+        assert!(!bits_3.bit_2);
+        assert!(!bits_3.bit_3);
+    }
+    #[test]
+    fn decode_bitstring_3_used_all_lit() {
+        // 5 unused bits, so 3 used
+        let bits_3 = MyBitString3or4::from_der(&hex!("03 02 05 FF")).unwrap();
+
+        assert!(bits_3.bit_0);
+        assert!(bits_3.bit_1);
+        assert!(bits_3.bit_2);
+        assert!(!bits_3.bit_3);
+    }
+
+    #[test]
+    fn decode_bitstring_4_used_all_lit() {
+        // 4 unused bits, so 4 used
+        let bits_3 = MyBitString3or4::from_der(&hex!("03 02 04 FF")).unwrap();
+
+        assert!(bits_3.bit_0);
+        assert!(bits_3.bit_1);
+        assert!(bits_3.bit_2);
+        assert!(bits_3.bit_3);
+    }
+
+    #[test]
+    fn decode_invalid_bitstring_5_used() {
+        // 3 unused bits, so 5 used
+        assert!(MyBitString3or4::from_der(&hex!("03 02 03 FF")).is_err());
+    }
+
+    #[test]
+    fn decode_invalid_bitstring_2_used() {
+        // 6 unused bits, so 2 used
+        assert!(MyBitString3or4::from_der(&hex!("03 02 06 FF")).is_err());
+    }
+
+    #[test]
+    fn encode_3_zero_bits() {
+        let encoded_3_zeros = MyBitString3or4 {
+            bit_0: false,
+            bit_1: false,
+            bit_2: false,
+            bit_3: false,
+        }
+        .to_der()
+        .unwrap();
+
+        // 3 bits used, 5 unused
+        assert_eq!(encoded_3_zeros, hex!("03 02 05 00"));
+    }
+
+    #[test]
+    fn encode_3_one_bits() {
+        let encoded_3_zeros = MyBitString3or4 {
+            bit_0: true,
+            bit_1: true,
+            bit_2: true,
+            bit_3: false,
+        }
+        .to_der()
+        .unwrap();
+
+        // 3 bits used, 5 unused
+        assert_eq!(encoded_3_zeros, hex!("03 02 05 E0"));
+    }
+
+    #[test]
+    fn encode_4_one_bits() {
+        let encoded_4_zeros = MyBitString3or4 {
+            bit_0: true,
+            bit_1: true,
+            bit_2: true,
+            bit_3: true,
+        }
+        .to_der()
+        .unwrap();
+
+        // 4 bits used, 4 unused
+        assert_eq!(encoded_4_zeros, hex!("03 02 04 F0"));
+    }
+
+    #[test]
+    fn encode_optional_one_4_used() {
+        let encoded_4_zeros = MyBitString3or4 {
+            bit_0: false,
+            bit_1: false,
+            bit_2: false,
+            bit_3: true,
+        }
+        .to_der()
+        .unwrap();
+
+        // 4 bits used, 4 unused
+        assert_eq!(encoded_4_zeros, hex!("03 02 04 10"));
+    }
+}
 mod infer_default {
     //! When another crate might define a PartialEq for another type, the use of
     //! `default="Default::default"` in the der derivation will not provide enough