[ 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. 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; 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 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 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

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

HTML conversion and comments on this are RFC are Copyright (c) 1998 Werner Koch, Remscheider Str. 22, 40215 Düsseldorf, Germany. Verbatim copying and distribution is permitted in any medium, provided this notice is preserved. See here for copyright information on the RFC itself.

Updated: 1999-09-30 wkoch