Module sequoia_openpgp::packet

Packet-related data types.

OpenPGP data structures are packet based. This module defines the corresponding data structures.

Most users of this library will not need to generate these packets themselves. Instead, the packets are instantiated as a side effect of parsing a message, or creating a message. The main current exception are Signature packets. Working with Signature packets is, however, simplified by using the SignatureBuilder.

Data Types

Many OpenPGP packets include a version field. Versioning is used to make it easier to change the standard. For instance, using versioning, it is possible to remove a field from a packet without introducing a new packet type, which would also require changing the grammar. Versioning also enables a degree of forward compatibility when a new version of a packet can be safely ignored. For instance, there are currently two versions of the Signature packet with completely different layouts: v3 and v4. An implementation that does not understand the latest version of the packet can still parse and display a message using them; it will just be unable to verify that signature.

In Sequoia, packets that have a version field are represented by enums, and each supported version of the packet has a variant, and a corresponding struct. This is the case even when only one version of the packet is currently defined, as is the case with the OnePassSig packet. The enums implement forwarders for common operations. As such, users of this library can often ignore that there are multiple versions of a given packet.

Unknown Packets

Sequoia gracefully handles unsupported packets by storing them as Unknown packets. There are several types of unknown packets:

• Packets that are known, but explicitly not supported.

  The two major examples are the SED packet type and v3 Signature packets, which have both been considered insecure for well over a decade.

  Note: future versions of Sequoia may add limited support for these packets to enable parsing archived messages.

• Packets that are known about, but that use unsupported options, e.g., a Compressed Data packet using an unknown or unsupported algorithm.

• Packets that are unknown, e.g., future or private extensions.

When Sequoia parses a message containing these packets, it doesn’t fail. Instead, Sequoia stores them in the Unknown data structure. This allows applications to not only continue to process such messages (albeit with degraded performance), but to losslessly reserialize the messages, should that be required.

Containers

Packets can be divided into two categories: containers and non-containers. A container is a packet that contains other OpenPGP packets. For instance, by definition, a Compressed Data packet contains an OpenPGP Message. It is possible to iterate over a container’s descendants using the Container::descendants method. (Note: Containers Deref to Container.)

Packet Headers and Bodies

Conceptually, packets have zero or more headers and an optional body. The headers are small, and have a known upper bound. The version field is, for instance, 4 bytes, and although Signature SubpacketArea areas are variable in size, they are limited to 64 KB. In contrast the body, can be unbounded in size.

To limit memory use, and enable streaming processing (i.e., ensuring that processing a message can be done using a fixed size buffer), Sequoia does not require that a packet’s body be present in memory. For instance, the body of a literal data packet may be streamed. And, at the end, a Literal packet is still returned. This allows the caller to examine the message structure, and the message headers in in toto even when streaming. It is even possible to compare two streamed version of a packet: Sequoia stores a hash of the body. See the Body data structure for more details.

Equality

There are several reasonable ways to define equality for Packets. Unfortunately, none of them are appropriate in all situations. This makes choosing a general-purpose equality function for Eq difficult.

Consider defining Eq as the equivalence of two Packets’ serialized forms. If an application naively deduplicates signatures, then an attacker can potentially perform a denial of service attack by causing the application to process many cryptographically-valid Signatures by varying the content of one cryptographically-valid Signature’s unhashed area. This attack can be prevented by only comparing data that is protected by the signature. But this means that naively deduplicating Signature packets will return in “a random” variant being used. So, again, an attacker could create variants of a cryptographically-valid Signature to get the implementation to incorrectly drop a useful one.

These issues are also relevant when comparing Keys: should the secret key material be compared? Usually we want to merge the secret key material. But, again, if done naively, the incorrect secret key material may be retained or dropped completely.

Instead of trying to come up with a definition of equality that is reasonable for all situations, we use a conservative definition: two packets are considered equal if the serialized forms of their packet bodies as defined by RFC 4880 are equal. That is, two packets are considered equal if and only if their serialized forms are equal modulo the OpenPGP framing (CTB and length style, potential partial body encoding). This definition will avoid unintentionally dropping information when naively deduplicating packets, but it will result in potential redundancies.

For some packets, we provide additional variants of equality. For instance, Key::public_cmp compares just the public parts of two keys.

Re-exports

• pub use self::header::Header;
• pub use self::user_attribute::UserAttribute;

Modules

• aed
  AEAD encrypted data packets.
• header
  OpenPGP packet headers.
• key
  Key-related functionality.
• one_pass_sig
  One-pass signature packets.
• pkesk
  PublicKey-Encrypted Session Key packets.
• prelude
  Brings the most relevant types and traits into scope for working with packets.
• seip
  Symmetrically Encrypted Integrity Protected data packets.
• signature
  Signature-related functionality.
• skesk
  Symmetric-Key Encrypted Session Key Packets.
• user_attribute
  User Attribute packets and subpackets.

Structs

• Common
  Fields used by multiple packet types.
• CompressedData
  Holds a compressed data packet.
• Container
  Holds packet bodies.
• Iter
  An iterator over the contents of a packet in depth-first order.
• Literal
  Holds a literal packet.
• MDC
  Holds an MDC packet.
• Marker
  Holds a Marker packet.
• Trust
  Holds a Trust packet.
• Unknown
  Holds an unknown packet.
• UserID
  Holds a UserID packet.

Enums

• AED
  Holds an AEAD encrypted data packet.
• Body
  A packet’s body holds either unprocessed bytes, processed bytes, or packets.
• Key
  Holds a public key, public subkey, private key or private subkey packet.
• OnePassSig
  Holds a one-pass signature packet.
• PKESK
  Holds an asymmetrically encrypted session key.
• Packet
  Enumeration of packet types.
• SEIP
  Holds a SEIP packet.
• SKESK
  Holds a symmetrically encrypted session key.
• Signature
  Holds a signature packet.
• Tag
  The OpenPGP packet tags as defined in Section 4.3 of RFC 4880.

Traits

• Any
  Convenient downcasting from Packets to Packet Bodies.