[ Contents ]
4. Packet Syntax
This section describes the packets used by OpenPGP.
4.1. Overview
An OpenPGP message is constructed from a number of records that are
traditionally called packets. A packet is a chunk of data that has a
tag specifying its meaning. An OpenPGP message, keyring, certificate,
and so forth consists of a number of packets. Some of those packets
may contain other OpenPGP packets (for example, a compressed data
packet, when uncompressed, contains OpenPGP packets).
Each packet consists of a packet header, followed by the packet body.
The packet header is of variable length.
4.2. Packet Headers
The first octet of the packet header is called the "Packet Tag." It
determines the format of the header and denotes the packet contents.
The remainder of the packet header is the length of the packet.
Note that the most significant bit is the left-most bit, called bit
7. A mask for this bit is 0x80 in hexadecimal.
+---------------+
PTag |7 6 5 4 3 2 1 0|
+---------------+
Bit 7 -- Always one
Bit 6 -- New packet format if set
PGP 2.6.x only uses old format packets. Thus, software that
interoperates with those versions of PGP must only use old format
packets. If interoperability is not an issue, either format may be
used. Note that old format packets have four bits of content tags,
and new format packets have six; some features cannot be used and
still be backward-compatible.
Old format packets contain:
Bits 5-2 -- content tag
Bits 1-0 - length-type
New format packets contain:
Bits 5-0 -- content tag
4.2.1. Old-Format Packet Lengths
The meaning of the length-type in old-format packets is:
0 - The packet has a one-octet length. The header is 2 octets long.
1 - The packet has a two-octet length. The header is 3 octets long.
2 - The packet has a four-octet length. The header is 5 octets long.
3 - The packet is of indeterminate length. The header is 1 octet
long, and the implementation must determine how long the packet
is. If the packet is in a file, this means that the packet
extends until the end of the file. In general, an implementation
SHOULD NOT use indeterminate length packets except where the end
of the data will be clear from the context, and even then it is
better to use a definite length, or a new-format header. The
new-format headers described below have a mechanism for precisely
encoding data of indeterminate length.
4.2.2. New-Format Packet Lengths
New format packets have four possible ways of encoding length:
1. A one-octet Body Length header encodes packet lengths of up to
191 octets.
2. A two-octet Body Length header encodes packet lengths of 192 to
8383 octets.
3. A five-octet Body Length header encodes packet lengths of up to
4,294,967,295 (0xFFFFFFFF) octets in length. (This actually
encodes a four-octet scalar number.)
4. When the length of the packet body is not known in advance by the
issuer, Partial Body Length headers encode a packet of
indeterminate length, effectively making it a stream.
4.2.2.1. One-Octet Lengths
A one-octet Body Length header encodes a length of from 0 to 191
octets. This type of length header is recognized because the one
octet value is less than 192. The body length is equal to:
bodyLen = 1st_octet;
4.2.2.2. Two-Octet Lengths
A two-octet Body Length header encodes a length of from 192 to 8383
octets. It is recognized because its first octet is in the range 192
to 223. The body length is equal to:
bodyLen = ((1st_octet - 192) << 8) + (2nd_octet) + 192
4.2.2.3. Five-Octet Lengths
A five-octet Body Length header consists of a single octet holding
the value 255, followed by a four-octet scalar. The body length is
equal to:
bodyLen = (2nd_octet << 24) | (3rd_octet << 16) |
(4th_octet << 8) | 5th_octet
4.2.2.4. Partial Body Lengths
A Partial Body Length header is one octet long and encodes the length
of only part of the data packet. This length is a power of 2, from 1
to 1,073,741,824 (2 to the 30th power). It is recognized by its one
octet value that is greater than or equal to 224, and less than 255.
The partial body length is equal to:
partialBodyLen = 1 << (1st_octet & 0x1f);
Each Partial Body Length header is followed by a portion of the
packet body data. The Partial Body Length header specifies this
portion's length. Another length header (of one of the three types --
one octet, two-octet, or partial) follows that portion. The last
length header in the packet MUST NOT be a partial Body Length header.
Partial Body Length headers may only be used for the non-final parts
of the packet.
4.2.3. Packet Length Examples
These examples show ways that new-format packets might encode the
packet lengths.
A packet with length 100 may have its length encoded in one octet:
0x64. This is followed by 100 octets of data.
A packet with length 1723 may have its length coded in two octets:
0xC5, 0xFB. This header is followed by the 1723 octets of data.
A packet with length 100000 may have its length encoded in five
octets: 0xFF, 0x00, 0x01, 0x86, 0xA0.
It might also be encoded in the following octet stream: 0xEF, first
32768 octets of data; 0xE1, next two octets of data; 0xE0, next one
octet of data; 0xF0, next 65536 octets of data; 0xC5, 0xDD, last 1693
octets of data. This is just one possible encoding, and many
variations are possible on the size of the Partial Body Length
headers, as long as a regular Body Length header encodes the last
portion of the data. Note also that the last Body Length header can
be a zero-length header.
An implementation MAY use Partial Body Lengths for data packets, be
they literal, compressed, or encrypted. The first partial length MUST
be at least 512 octets long. Partial Body Lengths MUST NOT be used
for any other packet types.
Please note that in all of these explanations, the total length of
the packet is the length of the header(s) plus the length of the
body.
4.3. Packet Tags
The packet tag denotes what type of packet the body holds. Note that
old format headers can only have tags less than 16, whereas new
format headers can have tags as great as 63. The defined tags (in
decimal) are:
0 -- Reserved - a packet tag must not have this value
1 -- Public-Key Encrypted Session Key Packet
2 -- Signature Packet
3 -- Symmetric-Key Encrypted Session Key Packet
4 -- One-Pass Signature Packet
5 -- Secret Key Packet
6 -- Public Key Packet
7 -- Secret Subkey Packet
8 -- Compressed Data Packet
9 -- Symmetrically Encrypted Data Packet
10 -- Marker Packet
11 -- Literal Data Packet
12 -- Trust Packet
13 -- User ID Packet
14 -- Public Subkey Packet
60 to 63 -- Private or Experimental Values
Updated: 1999-09-30 wkoch