From f64940feff7fb8020c5cbd6d69c9eb28d61a8898 Mon Sep 17 00:00:00 2001 From: Justus Winter Date: Mon, 27 Jul 2020 16:04:25 +0200 Subject: openpgp: Document parse::Dearmor. - Fixes #471. --- openpgp/src/parse.rs | 10 ++++++++++ openpgp/src/parse/packet_parser_builder.rs | 25 +++++++++++++++++++++++-- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/openpgp/src/parse.rs b/openpgp/src/parse.rs index 835d5399..0bfa4e49 100644 --- a/openpgp/src/parse.rs +++ b/openpgp/src/parse.rs @@ -119,6 +119,16 @@ //! [`Decryptor`]: stream/struct.Decryptor.html //! [`Verifier`]: stream/struct.Verifier.html //! +//! # ASCII armored data +//! +//! The [`PacketParser`] will by default automatically detect and +//! remove any ASCII armor encoding (see [Section 6 of RFC 4880]). +//! This automatism can be disabled and fine-tuned using +//! [`PacketParserBuilder::dearmor`]. +//! +//! [Section 6 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-6 +//! [`PacketParserBuilder::dearmor`]: struct.PacketParserBuilder.html#method.dearmor +//! //! # Security Considerations //! //! In general, OpenPGP data must be considered attacker controlled diff --git a/openpgp/src/parse/packet_parser_builder.rs b/openpgp/src/parse/packet_parser_builder.rs index e2df1ad5..ddb663d0 100644 --- a/openpgp/src/parse/packet_parser_builder.rs +++ b/openpgp/src/parse/packet_parser_builder.rs @@ -15,19 +15,40 @@ use crate::parse::Cookie; use crate::armor; use crate::packet; -/// How to decode the input. +/// Controls transparent stripping of ASCII armor when parsing. +/// +/// When parsing OpenPGP data streams, the [`PacketParser`] will by +/// default automatically detect and remove any ASCII armor encoding +/// (see [Section 6 of RFC 4880]). This automatism can be disabled +/// and fine-tuned using [`PacketParserBuilder::dearmor`]. +/// +/// [`PacketParser`]: struct.PacketParser.html +/// [Section 6 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-6 +/// [`PacketParserBuilder::dearmor`]: struct.PacketParserBuilder.html#method.dearmor #[derive(PartialEq)] pub enum Dearmor { /// Unconditionally treat the input as if it were an OpenPGP /// message encoded using ASCII armor. + /// + /// Parsing a binary encoded OpenPGP message using this mode will + /// fail. The [`ReaderMode`] allow further customization of the + /// ASCII armor parser. + /// + /// [`ReaderMode`]: ../armor/enum.ReaderMode.html Enabled(armor::ReaderMode), /// Unconditionally treat the input as if it were a binary OpenPGP /// message. + /// + /// Parsing an ASCII armor encoded OpenPGP message using this mode will + /// fail. Disabled, /// If input does not appear to be a binary encoded OpenPGP /// message, treat it as if it were encoded using ASCII armor. /// - /// This is the default. + /// This is the default. The [`ReaderMode`] allow further + /// customization of the ASCII armor parser. + /// + /// [`ReaderMode`]: ../armor/enum.ReaderMode.html Auto(armor::ReaderMode), } -- cgit v1.2.3