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
|
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
[`CertParser`] that parses OpenPGP Certificates ([`Cert`]s), all
down to the actual OpenPGP [`PacketParser`].
[`CertParser`]: ../../sequoia_openpgp/cert/struct.CertParser.html
[`Cert`]: ../../sequoia_openpgp/cert/struct.Cert.html
[`PacketParser`]: ../../sequoia_openpgp/parse/struct.PacketParser.html
# Parsing Certs
First, we will start with a string that presumably contains a
OpenPGP Certificate, and feed it into the [`CertParser`]. On
success, we can use or examine the resulting [`Cert`]:
```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 cert = openpgp::Cert::from_bytes(KEY.as_bytes()).unwrap();
assert_eq!(cert.fingerprint().to_string(),
"C087 4478 A65C 540A 1F73 72B4 A22E AD61 4D11 744A");
// Iterate over UserIDs.
assert_eq!(cert.userids().count(), 1);
assert_eq!(cert.userids().nth(0).unwrap().to_string(), "Ἀριστοτέλης");
// Iterate over subkeys.
assert_eq!(cert.keys().subkeys().count(), 2);
assert_eq!(cert.keys().subkeys().nth(0).unwrap().key().fingerprint().to_string(),
"67A4 8753 A380 A6B3 B7DF 7DC5 E6C6 897A 4CEF 8924");
assert_eq!(cert.keys().subkeys().nth(1).unwrap().key().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().unwrap().body(), "صداقة".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 [`Cert`]s using
[`Message::try_from`] or [`Cert::try_from`], or just
turned into a vector of [`Packet`]s:
[`PacketPile`]: ../../sequoia_openpgp/struct.PacketPile.html
[`Packet`]: ../../sequoia_openpgp/enum.Packet.html
[`Cert::try_from`]: ../../sequoia_openpgp/cert/struct.Cert.html#method.try_from
[`Message::try_from`]: ../../sequoia_openpgp/struct.Message.html#method.try_from
```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(), "صداقة".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
}
```
|
