GnuPG - RFC2440

# RFC2440

[ 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

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-05-23 wkoch