1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
//! Describes how to use some of Sequoia's parsers.
//! 
//! Sequoia contains and exposes several parsers.  In this chapter, we
//! will cover some of them, starting from a high level parser, the
//! [`TPKParser`] that parses transferable public keys ([`TPK`]s), all
//! down to the actual OpenPGP [`PacketParser`].
//! 
//! [`TPKParser`]: ../../sequoia_openpgp/tpk/struct.TPKParser.html
//! [`TPK`]: ../../sequoia_openpgp/struct.TPK.html
//! [`PacketParser`]: ../../sequoia_openpgp/parse/struct.PacketParser.html
//! 
//! # Parsing TPKs
//! 
//! First, we will start with a string that presumably contains a
//! transferable public key, and feed it into the [`TPKParser`].  On
//! success, we can use or examine the resulting [`TPK`]:
//! 
//! ```rust
//! extern crate sequoia_openpgp as openpgp;
//! use openpgp::parse::Parse;
//! 
//! const KEY: &str =
//!     "-----BEGIN PGP PUBLIC KEY BLOCK-----
//! 
//!      xjMEXAfmvxYJKwYBBAHaRw8BAQdAVNM03IK1KDgDNCbf4XcARhfqzyx425FEJMQ5
//!      qF+DrwHNF+G8iM+BzrnPg8+Ezr/PhM6tzrvOt8+CwoQEExYKADYCHgMCmwEFglwH
//!      5r8FiQWfpgAWIQTAh0R4plxUCh9zcrSiLq1hTRF0SgkQoi6tYU0RdEoCFQoAALip
//!      AP4sSVgNJogb/v0Qst0+WlmrJ6upG8Ynao5mnRFmfx2LjAEAyGJJBaEBB+x4kOse
//!      9uACwAXFhBRLN9zGgbyySQ3fRwjOMwRcB+a/FgkrBgEEAdpHDwEBB0BXBFWMeVd1
//!      nNn/VqTVEgY3wknX/KkKfMWhslFJoyZ4L8LAOAQYFgoAMwKbAgWCXAfmvwWJBZ+m
//!      ABYhBMCHRHimXFQKH3NytKIurWFNEXRKCRCiLq1hTRF0SgIVCgB3dqAEGRYKACcF
//!      glwH5r8WIQRnpIdTo4Cms7fffcXmxol6TO+JJAkQ5saJekzviSQAAMuvAQDdRfbM
//!      u2bDtVqNLIP/0WD/5X0us49r1yXMH+Ilg5NEEQEAuSQ1pY+reS62ETUS0uKYhxxv
//!      7OOsr8YM/ZMQ0exZsw/u+QEAuakAXrR7uFmWyigopQ7qMYfnK5zNfQNykvony5tS
//!      HpEBAJs3ZwHq+Q0ziAZNgcvdp0mklx8IXd8x59NjiP1t3mUBzjgEXAfmvxIKKwYB
//!      BAGXVQEFAQEHQJuIvcDm3Sh0+ZOE5hj7jCBas2xOCqYiG6+bWWieoxRrAwEICcKB
//!      BBgWCgAzApsMBYJcB+a/BYkFn6YAFiEEwIdEeKZcVAofc3K0oi6tYU0RdEoJEKIu
//!      rWFNEXRKAgsJAADx4wD/VrXZ7I/hBC37lzhyVEcCaHcorVXVn8ACCiyRmgmNbY4A
//!      /1lJmQJoDlpYlx3BAJ6RYuXRJoyU5KpcBf5afBPn8ncB
//!      =MHBq
//!      -----END PGP PUBLIC KEY BLOCK-----";
//! 
//! fn main() {
//!     let tpk = openpgp::TPK::from_bytes(KEY.as_bytes()).unwrap();
//! 
//!     assert_eq!(tpk.fingerprint().to_string(),
//!                "C087 4478 A65C 540A 1F73  72B4 A22E AD61 4D11 744A");
//! 
//!     // Iterate over UserIDs.
//!     assert_eq!(tpk.userids().count(), 1);
//!     assert_eq!(tpk.userids().nth(0).unwrap().userid(),
//!                &"Ἀριστοτέλης".into());
//! 
//!     // Iterate over subkeys.
//!     assert_eq!(tpk.subkeys().count(), 2);
//!     assert_eq!(tpk.subkeys().nth(0).unwrap().subkey().fingerprint().to_string(),
//!                "67A4 8753 A380 A6B3 B7DF  7DC5 E6C6 897A 4CEF 8924");
//!     assert_eq!(tpk.subkeys().nth(1).unwrap().subkey().fingerprint().to_string(),
//!                "185C DAA1 2723 0423 19E4  7F67 108F 2CAF 9034 356D");
//! }
//! ```
//! 
//! # Parsing OpenPGP messages
//! 
//! Not all sequences of OpenPGP packets are in valid OpenPGP
//! [`Message`]s, only those accepted by [this grammar] are.  Sequoia
//! contains a parser that parses packets and verifies the message
//! structure using this grammar:
//! 
//! [this grammar]: https://tools.ietf.org/html/rfc4880#section-11.3
//! [`Message`]: ../../sequoia_openpgp/struct.Message.html
//! 
//! ```rust
//! extern crate sequoia_openpgp as openpgp;
//! use openpgp::parse::Parse;
//! 
//! const MESSAGE: &str =
//!     "-----BEGIN PGP MESSAGE-----
//! 
//!      xA0DAAoW5saJekzviSQByxBiAAAAAADYtdiv2KfZgtipwnUEABYKACcFglwJHYoW
//!      IQRnpIdTo4Cms7fffcXmxol6TO+JJAkQ5saJekzviSQAAIJ6APwK6FxtHXn8txDl
//!      tBFsIXlOSLOs4BvArlZzZSMomIyFLAEAwCLJUChMICDxWXRlHxORqU5x6hlO3DdW
//!      sl/1DAbnRgI=
//!      =AqoO
//!      -----END PGP MESSAGE-----";
//! 
//! fn main() {
//!     let message = openpgp::Message::from_bytes(MESSAGE.as_bytes()).unwrap();
//! 
//!     assert_eq!(message.body().and_then(|literal| literal.body()),
//!                Some("صداقة".as_bytes()));
//! }
//! ```
//! 
//! # Parsing packets into packet piles
//! 
//! [`PacketPile`]s are unstructured sequences of OpenPGP packets.  Packet
//! piles can be inspected, manipulated, validated using a formal grammar
//! and thereby turned into [`Message`]s or [`TPK`]s using
//! [`Message::from_packet_pile`] or [`TPK::from_packet_pile`], or just
//! turned into a vector of [`Packet`]s:
//! 
//! [`PacketPile`]: ../../sequoia_openpgp/struct.PacketPile.html
//! [`Packet`]: ../../sequoia_openpgp/enum.Packet.html
//! [`TPK::from_packet_pile`]: ../../sequoia_openpgp/struct.TPK.html#method.from_packet_pile
//! [`Message::from_packet_pile`]: ../../sequoia_openpgp/struct.Message.html#method.from_packet_pile
//! 
//! ```rust
//! extern crate sequoia_openpgp as openpgp;
//! use openpgp::parse::Parse;
//! 
//! const MESSAGE: &str =
//!     "-----BEGIN PGP MESSAGE-----
//! 
//!      xA0DAAoW5saJekzviSQByxBiAAAAAADYtdiv2KfZgtipwnUEABYKACcFglwJHYoW
//!      IQRnpIdTo4Cms7fffcXmxol6TO+JJAkQ5saJekzviSQAAIJ6APwK6FxtHXn8txDl
//!      tBFsIXlOSLOs4BvArlZzZSMomIyFLAEAwCLJUChMICDxWXRlHxORqU5x6hlO3DdW
//!      sl/1DAbnRgI=
//!      =AqoO
//!      -----END PGP MESSAGE-----";
//! 
//! fn main() {
//!     let pile = openpgp::PacketPile::from_bytes(MESSAGE.as_bytes()).unwrap();
//! 
//!     // For simplicity, turn the pile into a vector of packets.
//!     let packets: Vec<openpgp::Packet> = pile.into_children().collect();
//! 
//!     // There are three packets in that message.
//!     assert_eq!(packets.len(), 3);
//! 
//!     // First, we expect an one pass signature packet.
//!     if let openpgp::Packet::OnePassSig(ref ops) = packets[0] {
//!         assert_eq!(ops.issuer().to_string(), "E6C6 897A 4CEF 8924");
//!     } else {
//!         panic!("expected one pass signature packet");
//!     }
//! 
//!     // The second packet is the literal data packet.
//!     if let openpgp::Packet::Literal(ref literal) = packets[1] {
//!         assert_eq!(literal.body(), Some("صداقة".as_bytes()));
//!     } else {
//!         panic!("expected literal data packet");
//!     }
//! 
//!     // Finally, we expect the signature itself.
//!     if let openpgp::Packet::Signature(ref signature) = packets[2] {
//!         assert_eq!(signature.issuer_fingerprint().unwrap().to_string(),
//!                    "67A4 8753 A380 A6B3 B7DF  7DC5 E6C6 897A 4CEF 8924");
//!     } else {
//!         panic!("expected signature packet");
//!     }
//! }
//! ```
//! 
//! # Streaming packet parsing
//! 
//! Both the [`Message`]parser and the [`PacketPile`]parser build a tree
//! structure in memory, and more importantly, they buffer the bodies of
//! literal data packets.  Both properties can be undesirable if a large
//! number of packets is parsed, or the data contained in the message
//! large.  This problem is exacerbated by the fact that OpenPGP messages
//! can be compressed, so that processing even small messages can lead to
//! an unbounded amount of memory being allocated.
//! 
//! To alleviate this problem, Sequoia features streaming interfaces that
//! implement [`io::Read`] and [`io::Write`].  These interfaces allow
//! processing of OpenPGP packets in constant space.
//! 
//! [`io::Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
//! [`io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
//! 
//! The core of Sequoia is our [`PacketParser`], upon which all higher
//! level interfaces are built.  It is the most flexible interface for
//! processing OpenPGP packets, and it is the foundation for our streaming
//! interfaces.  Most of the time, it is not necessary to use this
//! interface, but nevertheless, our parser is exposed as part of our API
//! and can be used to quickly process large amounts of OpenPGP packets,
//! e.g. for collecting statistics about the SKS keyserver dump.  For a
//! complete example, see [`openpgp/examples/statistics.rs`].
//! 
//! [`PacketParser`]: ../../sequoia_openpgp/parse/struct.PacketParser.html
//! [`openpgp/examples/statistics.rs`]: https://gitlab.com/sequoia-pgp/sequoia/blob/master/openpgp/examples/statistics.rs
//! 
//! ```rust
//! use std::io::Read;
//! 
//! extern crate sequoia_openpgp as openpgp;
//! use openpgp::parse::*;
//! 
//! const MESSAGE: &str =
//!     "-----BEGIN PGP MESSAGE-----
//! 
//!      yMACA0JaaDYxQVkmU1nHKJOZA6l4wQTAABAAAAgACCAAUGaaCalNNxCUkepFQEtY
//!      hKSO3zFBWSZTWTYaxwsA6l5AAMAAAAggADCATUZBKSNSCUkcxQVkmU1k2GscLAOp
//!      eQADAAAAIIAAwgE1GQSkjUglJHMUFZJlNZNhrHCwDqXkAAwAAACCAAMIBNRkEpI1
//!      IJSRzFBWSZTWUmfJVgAWotAANkAAAggAFBmgClRjNkhJTMqEqoN9JCSnC7kinChI
//!      H89bU4A=
//!      =eySo
//!      -----END PGP MESSAGE-----";
//! 
//! fn main() {
//!     let mut bytes_read = 0;
//!     let mut buf = vec![0; 1024 * 1024];
//! 
//!     let mut ppr = PacketParser::from_bytes(MESSAGE.as_bytes()).unwrap();
//!     while let PacketParserResult::Some(mut pp) = ppr {
//!         // Match on the kind of packet here while it is in the parser.
//!         if let openpgp::Packet::Literal(_) = pp.packet {
//!             // Stream the content of the literal packet.
//!             while let Ok(_) = pp.read_exact(&mut buf) {
//!                 bytes_read += buf.len();
//!             }
//!         }
//! 
//!         // Start parsing the next packet.
//!         ppr = pp.recurse().unwrap().1;
//!     }
//! 
//!     assert_eq!(bytes_read, 128 * 1024 * 1024);    // 128 megabytes
//! }
//! ```