diff options
Diffstat (limited to 'openpgp/src/packet/header/mod.rs')
-rw-r--r-- | openpgp/src/packet/header/mod.rs | 60 |
1 files changed, 42 insertions, 18 deletions
diff --git a/openpgp/src/packet/header/mod.rs b/openpgp/src/packet/header/mod.rs index 6144f03c..bb0a7f34 100644 --- a/openpgp/src/packet/header/mod.rs +++ b/openpgp/src/packet/header/mod.rs @@ -1,4 +1,17 @@ -//! OpenPGP Header. +//! OpenPGP packet headers. +//! +//! An OpenPGP packet header contains packet meta-data. Specifically, +//! it includes the [packet's type] (its so-called *tag*), and the +//! [packet's length]. +//! +//! Decades ago, when OpenPGP was conceived, saving even a few bits +//! was considered important. As such, OpenPGP uses very compact +//! encodings. The encoding schemes have evolved so that there are +//! now two families: the so-called old format, and new format +//! encodings. +//! +//! [packet's type]: https://tools.ietf.org/html/rfc4880#section-4.3 +//! [packet's length]: https://tools.ietf.org/html/rfc4880#section-4.2.1 use crate::{ Error, @@ -13,7 +26,11 @@ pub use self::ctb::{ PacketLengthType, }; -/// An OpenPGP packet's header. +/// A packet's header. +/// +/// See [Section 4.2 of RFC 4880] for details. +/// +/// [Section 4.2 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-4.2 #[derive(Clone, Debug)] pub struct Header { /// The packet's CTB. @@ -28,29 +45,34 @@ impl Header { Header { ctb, length } } - /// Returns the packet's CTB. + /// Returns the header's CTB. pub fn ctb(&self) -> &CTB { &self.ctb } - /// Returns the packet's length. + /// Returns the header's length. pub fn length(&self) -> &BodyLength { &self.length } - /// Syntax checks the header. + /// Checks the header for validity. /// /// A header is consider invalid if: /// - /// - The tag is Tag::Reserved. - /// - The tag is unknown (if future_compatible is false). - /// - The [length encoding] is invalid for the packet. + /// - The tag is [`Tag::Reserved`]. + /// - The tag is [`Tag::Unknown`] or [`Tag::Private`] and + /// `future_compatible` is false. + /// - The [length encoding] is invalid for the packet (e.g., + /// partial body encoding may not be used for [`PKESK`] packets) /// - The lengths are unreasonable for a packet (e.g., a - /// PKESK or SKESK larger than 10 kb). + /// `PKESK` or [`SKESK`] larger than 10 KB). /// + /// [`Tag::Reserved`]: ../enum.Tag.html#variant.Reserved + /// [`Tag::Unknown`]: ../enum.Tag.html#variant.Unknown + /// [`Tag::Private`]: ../enum.Tag.html#variant.Private /// [length encoding]: https://tools.ietf.org/html/rfc4880#section-4.2.2.4 - /// - /// This function does not check the packet's content. + /// [`PKESK`]: ../enum.PKESK.html + /// [`SKESK`]: ../enum.SKESK.html // Note: To check the packet's content, use // `PacketParser::plausible`. pub fn valid(&self, future_compatible: bool) -> Result<()> { @@ -202,12 +224,12 @@ impl Header { } } -/// The size of a packet. +/// A packet's size. /// /// A packet's size can be expressed in three different ways. Either -/// the size of the packet is fully known (Full), the packet is -/// chunked using OpenPGP's partial body encoding (Partial), or the -/// packet extends to the end of the file (Indeterminate). See +/// the size of the packet is fully known (`Full`), the packet is +/// chunked using OpenPGP's partial body encoding (`Partial`), or the +/// packet extends to the end of the file (`Indeterminate`). See /// [Section 4.2 of RFC 4880] for more details. /// /// [Section 4.2 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-4.2 @@ -216,12 +238,14 @@ impl Header { #[derive(PartialEq)] #[derive(Clone, Copy)] pub enum BodyLength { - /// Packet size is fully known. + /// The packet's size is known. Full(u32), /// The parameter is the number of bytes in the current chunk. + /// /// This type is only used with new format packets. Partial(u32), - /// The packet extends until an EOF is encountered. This type is - /// only used with old format packets. + /// The packet extends until an EOF is encountered. + /// + /// This type is only used with old format packets. Indeterminate, } |