diff --git a/der/src/header.rs b/der/src/header.rs index 0addf3a72..00ad66906 100644 --- a/der/src/header.rs +++ b/der/src/header.rs @@ -7,6 +7,27 @@ use crate::{Decode, DerOrd, Encode, Error, ErrorKind, Length, Reader, Result, Ta use core::cmp::Ordering; /// ASN.1 DER headers: tag + length component of TLV-encoded values +/// +/// +/// ## Examples +/// ``` +/// use der::{Decode, Header, Length, Reader, SliceReader, Tag}; +/// +/// let mut reader = SliceReader::new(&[0x04, 0x02, 0x31, 0x32]).unwrap(); +/// let header = Header::decode(&mut reader).expect("valid header"); +/// +/// assert_eq!(header, Header::new(Tag::OctetString, Length::new(2))); +/// +/// assert_eq!(reader.read_slice(2u8.into()).unwrap(), b"12"); +/// ``` +/// +/// ``` +/// use der::{Encode, Header, Length, Tag}; +/// let header = Header::new(Tag::Sequence, Length::new(256)); +/// +/// // Header of 256-byte SEQUENCE is 4-byte long +/// assert_eq!(header.encoded_len(), Ok(Length::new(4))); +/// ``` #[derive(Copy, Clone, Debug, Eq, PartialEq)] pub struct Header { /// Tag representing the type of the encoded value diff --git a/der/src/length.rs b/der/src/length.rs index 90eafe54b..3228903ed 100644 --- a/der/src/length.rs +++ b/der/src/length.rs @@ -18,6 +18,33 @@ use core::{ }; /// ASN.1-encoded length. +/// +/// ## Examples +/// ``` +/// use der::{Decode, Length, SliceReader}; +/// +/// let mut reader = SliceReader::new(&[0x82, 0xAA, 0xBB]).unwrap(); +/// let length = Length::decode(&mut reader).expect("valid length"); +/// +/// assert_eq!(length, Length::new(0xAABB)); +/// ``` +/// +/// 5-byte lengths are supported: +/// ``` +/// use der::{Encode, Length}; +/// let length = Length::new(0x10000000); +/// +/// assert_eq!(length.encoded_len(), Ok(Length::new(5))); +/// ``` +/// +/// Invalid lengths produce an error: +/// ``` +/// use der::{Decode, Length, SliceReader}; +/// +/// let mut reader = SliceReader::new(&[0x81, 0x7F]).unwrap(); +/// +/// Length::decode(&mut reader).expect_err("non-canonical length should be rejected"); +/// ``` #[derive(Copy, Clone, Default, Eq, Hash, PartialEq, PartialOrd, Ord)] pub struct Length { /// Inner length as a `u32`. Note that the decoder and encoder also support a maximum length diff --git a/der/src/tag.rs b/der/src/tag.rs index 5ccdc7c50..12e6262bf 100644 --- a/der/src/tag.rs +++ b/der/src/tag.rs @@ -62,6 +62,34 @@ impl IsConstructed for T { /// - Bits 8/7: [`Class`] /// - Bit 6: primitive (0) or constructed (1) /// - Bits 5-1: tag number +/// +/// ## Examples +/// ``` +/// use der::{Decode, Tag, SliceReader}; +/// +/// let mut reader = SliceReader::new(&[0x30]).unwrap(); +/// let tag = Tag::decode(&mut reader).expect("valid tag"); +/// +/// assert_eq!(tag, Tag::Sequence); +/// ``` +/// +/// Invalid tags produce an error: +/// ``` +/// use der::{Decode, Tag}; +/// +/// // 0x21 is an invalid CONSTRUCTED BOOLEAN +/// Tag::from_der(&[0x21]).expect_err("invalid tag"); +/// ``` +/// +/// `APPLICATION`, `CONTEXT-SPECIFIC` and `PRIVATE` tags are supported: +/// ``` +/// use der::{Decode, Tag, TagNumber}; +/// +/// // `APPLICATION [33] (constructed)` +/// let tag = Tag::from_der(&[0x7F, 0x21]).expect("valid tag"); +/// +/// assert_eq!(tag, Tag::Application { constructed: true, number: TagNumber(33) }); +/// ``` #[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))] #[derive(Copy, Clone, Eq, Hash, PartialEq, PartialOrd, Ord)] #[non_exhaustive]