Tech-invite3GPPspaceIETF RFCsSIP
929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 4880

OpenPGP Message Format

Pages: 90
Proposed Standard
Errata
Obsoletes:  19912440
Updated by:  5581
Part 4 of 5 – Pages 59 to 70
First   Prev   Next

Top   ToC   RFC4880 - Page 59   prevText

7. Cleartext Signature Framework

It is desirable to be able to sign a textual octet stream without ASCII armoring the stream itself, so the signed text is still readable without special software. In order to bind a signature to such a cleartext, this framework is used. (Note that this framework is not intended to be reversible. RFC 3156 [RFC3156] defines another way to sign cleartext messages for environments that support MIME.)
Top   ToC   RFC4880 - Page 60
   The cleartext signed message consists of:

     - The cleartext header '-----BEGIN PGP SIGNED MESSAGE-----' on a
       single line,

     - One or more "Hash" Armor Headers,

     - Exactly one empty line not included into the message digest,

     - The dash-escaped cleartext that is included into the message
       digest,

     - The ASCII armored signature(s) including the '-----BEGIN PGP
       SIGNATURE-----' Armor Header and Armor Tail Lines.

   If the "Hash" Armor Header is given, the specified message digest
   algorithm(s) are used for the signature.  If there are no such
   headers, MD5 is used.  If MD5 is the only hash used, then an
   implementation MAY omit this header for improved V2.x compatibility.
   If more than one message digest is used in the signature, the "Hash"
   armor header contains a comma-delimited list of used message digests.

   Current message digest names are described below with the algorithm
   IDs.

   An implementation SHOULD add a line break after the cleartext, but
   MAY omit it if the cleartext ends with a line break.  This is for
   visual clarity.

7.1. Dash-Escaped Text

The cleartext content of the message must also be dash-escaped. Dash-escaped cleartext is the ordinary cleartext where every line starting with a dash '-' (0x2D) is prefixed by the sequence dash '-' (0x2D) and space ' ' (0x20). This prevents the parser from recognizing armor headers of the cleartext itself. An implementation MAY dash-escape any line, SHOULD dash-escape lines commencing "From" followed by a space, and MUST dash-escape any line commencing in a dash. The message digest is computed using the cleartext itself, not the dash-escaped form. As with binary signatures on text documents, a cleartext signature is calculated on the text using canonical <CR><LF> line endings. The line ending (i.e., the <CR><LF>) before the '-----BEGIN PGP SIGNATURE-----' line that terminates the signed text is not considered part of the signed text.
Top   ToC   RFC4880 - Page 61
   When reversing dash-escaping, an implementation MUST strip the string
   "- " if it occurs at the beginning of a line, and SHOULD warn on "-"
   and any character other than a space at the beginning of a line.

   Also, any trailing whitespace -- spaces (0x20) and tabs (0x09) -- at
   the end of any line is removed when the cleartext signature is
   generated.

8. Regular Expressions

A regular expression is zero or more branches, separated by '|'. It matches anything that matches one of the branches. A branch is zero or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc. A piece is an atom possibly followed by '*', '+', or '?'. An atom followed by '*' matches a sequence of 0 or more matches of the atom. An atom followed by '+' matches a sequence of 1 or more matches of the atom. An atom followed by '?' matches a match of the atom, or the null string. An atom is a regular expression in parentheses (matching a match for the regular expression), a range (see below), '.' (matching any single character), '^' (matching the null string at the beginning of the input string), '$' (matching the null string at the end of the input string), a '\' followed by a single character (matching that character), or a single character with no other significance (matching that character). A range is a sequence of characters enclosed in '[]'. It normally matches any single character from the sequence. If the sequence begins with '^', it matches any single character not from the rest of the sequence. If two characters in the sequence are separated by '-', this is shorthand for the full list of ASCII characters between them (e.g., '[0-9]' matches any decimal digit). To include a literal ']' in the sequence, make it the first character (following a possible '^'). To include a literal '-', make it the first or last character.

9. Constants

This section describes the constants used in OpenPGP. Note that these tables are not exhaustive lists; an implementation MAY implement an algorithm not on these lists, so long as the algorithm numbers are chosen from the private or experimental algorithm range.
Top   ToC   RFC4880 - Page 62
   See the section "Notes on Algorithms" below for more discussion of
   the algorithms.

9.1. Public-Key Algorithms

ID Algorithm -- --------- 1 - RSA (Encrypt or Sign) [HAC] 2 - RSA Encrypt-Only [HAC] 3 - RSA Sign-Only [HAC] 16 - Elgamal (Encrypt-Only) [ELGAMAL] [HAC] 17 - DSA (Digital Signature Algorithm) [FIPS186] [HAC] 18 - Reserved for Elliptic Curve 19 - Reserved for ECDSA 20 - Reserved (formerly Elgamal Encrypt or Sign) 21 - Reserved for Diffie-Hellman (X9.42, as defined for IETF-S/MIME) 100 to 110 - Private/Experimental algorithm Implementations MUST implement DSA for signatures, and Elgamal for encryption. Implementations SHOULD implement RSA keys (1). RSA Encrypt-Only (2) and RSA Sign-Only are deprecated and SHOULD NOT be generated, but may be interpreted. See Section 13.5. See Section 13.8 for notes on Elliptic Curve (18), ECDSA (19), Elgamal Encrypt or Sign (20), and X9.42 (21). Implementations MAY implement any other algorithm.

9.2. Symmetric-Key Algorithms

ID Algorithm -- --------- 0 - Plaintext or unencrypted data 1 - IDEA [IDEA] 2 - TripleDES (DES-EDE, [SCHNEIER] [HAC] - 168 bit key derived from 192) 3 - CAST5 (128 bit key, as per [RFC2144]) 4 - Blowfish (128 bit key, 16 rounds) [BLOWFISH] 5 - Reserved 6 - Reserved 7 - AES with 128-bit key [AES] 8 - AES with 192-bit key 9 - AES with 256-bit key 10 - Twofish with 256-bit key [TWOFISH] 100 to 110 - Private/Experimental algorithm Implementations MUST implement TripleDES. Implementations SHOULD implement AES-128 and CAST5. Implementations that interoperate with
Top   ToC   RFC4880 - Page 63
   PGP 2.6 or earlier need to support IDEA, as that is the only
   symmetric cipher those versions use.  Implementations MAY implement
   any other algorithm.

9.3. Compression Algorithms

ID Algorithm -- --------- 0 - Uncompressed 1 - ZIP [RFC1951] 2 - ZLIB [RFC1950] 3 - BZip2 [BZ2] 100 to 110 - Private/Experimental algorithm Implementations MUST implement uncompressed data. Implementations SHOULD implement ZIP. Implementations MAY implement any other algorithm.

9.4. Hash Algorithms

ID Algorithm Text Name -- --------- --------- 1 - MD5 [HAC] "MD5" 2 - SHA-1 [FIPS180] "SHA1" 3 - RIPE-MD/160 [HAC] "RIPEMD160" 4 - Reserved 5 - Reserved 6 - Reserved 7 - Reserved 8 - SHA256 [FIPS180] "SHA256" 9 - SHA384 [FIPS180] "SHA384" 10 - SHA512 [FIPS180] "SHA512" 11 - SHA224 [FIPS180] "SHA224" 100 to 110 - Private/Experimental algorithm Implementations MUST implement SHA-1. Implementations MAY implement other algorithms. MD5 is deprecated.

10. IANA Considerations

OpenPGP is highly parameterized, and consequently there are a number of considerations for allocating parameters for extensions. This section describes how IANA should look at extensions to the protocol as described in this document.
Top   ToC   RFC4880 - Page 64

10.1. New String-to-Key Specifier Types

OpenPGP S2K specifiers contain a mechanism for new algorithms to turn a string into a key. This specification creates a registry of S2K specifier types. The registry includes the S2K type, the name of the S2K, and a reference to the defining specification. The initial values for this registry can be found in Section 3.7.1. Adding a new S2K specifier MUST be done through the IETF CONSENSUS method, as described in [RFC2434].

10.2. New Packets

Major new features of OpenPGP are defined through new packet types. This specification creates a registry of packet types. The registry includes the packet type, the name of the packet, and a reference to the defining specification. The initial values for this registry can be found in Section 4.3. Adding a new packet type MUST be done through the IETF CONSENSUS method, as described in [RFC2434].

10.2.1. User Attribute Types

The User Attribute packet permits an extensible mechanism for other types of certificate identification. This specification creates a registry of User Attribute types. The registry includes the User Attribute type, the name of the User Attribute, and a reference to the defining specification. The initial values for this registry can be found in Section 5.12. Adding a new User Attribute type MUST be done through the IETF CONSENSUS method, as described in [RFC2434].
10.2.1.1. Image Format Subpacket Types
Within User Attribute packets, there is an extensible mechanism for other types of image-based user attributes. This specification creates a registry of Image Attribute subpacket types. The registry includes the Image Attribute subpacket type, the name of the Image Attribute subpacket, and a reference to the defining specification. The initial values for this registry can be found in Section 5.12.1. Adding a new Image Attribute subpacket type MUST be done through the IETF CONSENSUS method, as described in [RFC2434].

10.2.2. New Signature Subpackets

OpenPGP signatures contain a mechanism for signed (or unsigned) data to be added to them for a variety of purposes in the Signature subpackets as discussed in Section 5.2.3.1. This specification creates a registry of Signature subpacket types. The registry includes the Signature subpacket type, the name of the subpacket, and a reference to the defining specification. The initial values for
Top   ToC   RFC4880 - Page 65
   this registry can be found in Section 5.2.3.1.  Adding a new
   Signature subpacket MUST be done through the IETF CONSENSUS method,
   as described in [RFC2434].

10.2.2.1. Signature Notation Data Subpackets
OpenPGP signatures further contain a mechanism for extensions in signatures. These are the Notation Data subpackets, which contain a key/value pair. Notations contain a user space that is completely unmanaged and an IETF space. This specification creates a registry of Signature Notation Data types. The registry includes the Signature Notation Data type, the name of the Signature Notation Data, its allowed values, and a reference to the defining specification. The initial values for this registry can be found in Section 5.2.3.16. Adding a new Signature Notation Data subpacket MUST be done through the EXPERT REVIEW method, as described in [RFC2434].
10.2.2.2. Key Server Preference Extensions
OpenPGP signatures contain a mechanism for preferences to be specified about key servers. This specification creates a registry of key server preferences. The registry includes the key server preference, the name of the preference, and a reference to the defining specification. The initial values for this registry can be found in Section 5.2.3.17. Adding a new key server preference MUST be done through the IETF CONSENSUS method, as described in [RFC2434].
10.2.2.3. Key Flags Extensions
OpenPGP signatures contain a mechanism for flags to be specified about key usage. This specification creates a registry of key usage flags. The registry includes the key flags value, the name of the flag, and a reference to the defining specification. The initial values for this registry can be found in Section 5.2.3.21. Adding a new key usage flag MUST be done through the IETF CONSENSUS method, as described in [RFC2434].
10.2.2.4. Reason for Revocation Extensions
OpenPGP signatures contain a mechanism for flags to be specified about why a key was revoked. This specification creates a registry of "Reason for Revocation" flags. The registry includes the "Reason for Revocation" flags value, the name of the flag, and a reference to the defining specification. The initial values for this registry can be found in Section 5.2.3.23. Adding a new feature flag MUST be done through the IETF CONSENSUS method, as described in [RFC2434].
Top   ToC   RFC4880 - Page 66
10.2.2.5. Implementation Features
OpenPGP signatures contain a mechanism for flags to be specified stating which optional features an implementation supports. This specification creates a registry of feature-implementation flags. The registry includes the feature-implementation flags value, the name of the flag, and a reference to the defining specification. The initial values for this registry can be found in Section 5.2.3.24. Adding a new feature-implementation flag MUST be done through the IETF CONSENSUS method, as described in [RFC2434]. Also see Section 13.12 for more information about when feature flags are needed.

10.2.3. New Packet Versions

The core OpenPGP packets all have version numbers, and can be revised by introducing a new version of an existing packet. This specification creates a registry of packet types. The registry includes the packet type, the number of the version, and a reference to the defining specification. The initial values for this registry can be found in Section 5. Adding a new packet version MUST be done through the IETF CONSENSUS method, as described in [RFC2434].

10.3. New Algorithms

Section 9 lists the core algorithms that OpenPGP uses. Adding in a new algorithm is usually simple. For example, adding in a new symmetric cipher usually would not need anything more than allocating a constant for that cipher. If that cipher had other than a 64-bit or 128-bit block size, there might need to be additional documentation describing how OpenPGP-CFB mode would be adjusted. Similarly, when DSA was expanded from a maximum of 1024-bit public keys to 3072-bit public keys, the revision of FIPS 186 contained enough information itself to allow implementation. Changes to this document were made mainly for emphasis.

10.3.1. Public-Key Algorithms

OpenPGP specifies a number of public-key algorithms. This specification creates a registry of public-key algorithm identifiers. The registry includes the algorithm name, its key sizes and parameters, and a reference to the defining specification. The initial values for this registry can be found in Section 9. Adding a new public-key algorithm MUST be done through the IETF CONSENSUS method, as described in [RFC2434].
Top   ToC   RFC4880 - Page 67

10.3.2. Symmetric-Key Algorithms

OpenPGP specifies a number of symmetric-key algorithms. This specification creates a registry of symmetric-key algorithm identifiers. The registry includes the algorithm name, its key sizes and block size, and a reference to the defining specification. The initial values for this registry can be found in Section 9. Adding a new symmetric-key algorithm MUST be done through the IETF CONSENSUS method, as described in [RFC2434].

10.3.3. Hash Algorithms

OpenPGP specifies a number of hash algorithms. This specification creates a registry of hash algorithm identifiers. The registry includes the algorithm name, a text representation of that name, its block size, an OID hash prefix, and a reference to the defining specification. The initial values for this registry can be found in Section 9 for the algorithm identifiers and text names, and Section 5.2.2 for the OIDs and expanded signature prefixes. Adding a new hash algorithm MUST be done through the IETF CONSENSUS method, as described in [RFC2434].

10.3.4. Compression Algorithms

OpenPGP specifies a number of compression algorithms. This specification creates a registry of compression algorithm identifiers. The registry includes the algorithm name and a reference to the defining specification. The initial values for this registry can be found in Section 9.3. Adding a new compression key algorithm MUST be done through the IETF CONSENSUS method, as described in [RFC2434].

11. Packet Composition

OpenPGP packets are assembled into sequences in order to create messages and to transfer keys. Not all possible packet sequences are meaningful and correct. This section describes the rules for how packets should be placed into sequences.

11.1. Transferable Public Keys

OpenPGP users may transfer public keys. The essential elements of a transferable public key are as follows: - One Public-Key packet - Zero or more revocation signatures
Top   ToC   RFC4880 - Page 68
     - One or more User ID packets

     - After each User ID packet, zero or more Signature packets
       (certifications)

     - Zero or more User Attribute packets

     - After each User Attribute packet, zero or more Signature packets
       (certifications)

     - Zero or more Subkey packets

     - After each Subkey packet, one Signature packet, plus optionally a
       revocation

   The Public-Key packet occurs first.  Each of the following User ID
   packets provides the identity of the owner of this public key.  If
   there are multiple User ID packets, this corresponds to multiple
   means of identifying the same unique individual user; for example, a
   user may have more than one email address, and construct a User ID
   for each one.

   Immediately following each User ID packet, there are zero or more
   Signature packets.  Each Signature packet is calculated on the
   immediately preceding User ID packet and the initial Public-Key
   packet.  The signature serves to certify the corresponding public key
   and User ID.  In effect, the signer is testifying to his or her
   belief that this public key belongs to the user identified by this
   User ID.

   Within the same section as the User ID packets, there are zero or
   more User Attribute packets.  Like the User ID packets, a User
   Attribute packet is followed by zero or more Signature packets
   calculated on the immediately preceding User Attribute packet and the
   initial Public-Key packet.

   User Attribute packets and User ID packets may be freely intermixed
   in this section, so long as the signatures that follow them are
   maintained on the proper User Attribute or User ID packet.

   After the User ID packet or Attribute packet, there may be zero or
   more Subkey packets.  In general, subkeys are provided in cases where
   the top-level public key is a signature-only key.  However, any V4
   key may have subkeys, and the subkeys may be encryption-only keys,
   signature-only keys, or general-purpose keys.  V3 keys MUST NOT have
   subkeys.
Top   ToC   RFC4880 - Page 69
   Each Subkey packet MUST be followed by one Signature packet, which
   should be a subkey binding signature issued by the top-level key.
   For subkeys that can issue signatures, the subkey binding signature
   MUST contain an Embedded Signature subpacket with a primary key
   binding signature (0x19) issued by the subkey on the top-level key.

   Subkey and Key packets may each be followed by a revocation Signature
   packet to indicate that the key is revoked.  Revocation signatures
   are only accepted if they are issued by the key itself, or by a key
   that is authorized to issue revocations via a Revocation Key
   subpacket in a self-signature by the top-level key.

   Transferable public-key packet sequences may be concatenated to allow
   transferring multiple public keys in one operation.

11.2. Transferable Secret Keys

OpenPGP users may transfer secret keys. The format of a transferable secret key is the same as a transferable public key except that secret-key and secret-subkey packets are used instead of the public key and public-subkey packets. Implementations SHOULD include self- signatures on any user IDs and subkeys, as this allows for a complete public key to be automatically extracted from the transferable secret key. Implementations MAY choose to omit the self-signatures, especially if a transferable public key accompanies the transferable secret key.

11.3. OpenPGP Messages

An OpenPGP message is a packet or sequence of packets that corresponds to the following grammatical rules (comma represents sequential composition, and vertical bar separates alternatives): OpenPGP Message :- Encrypted Message | Signed Message | Compressed Message | Literal Message. Compressed Message :- Compressed Data Packet. Literal Message :- Literal Data Packet. ESK :- Public-Key Encrypted Session Key Packet | Symmetric-Key Encrypted Session Key Packet. ESK Sequence :- ESK | ESK Sequence, ESK. Encrypted Data :- Symmetrically Encrypted Data Packet | Symmetrically Encrypted Integrity Protected Data Packet
Top   ToC   RFC4880 - Page 70
   Encrypted Message :- Encrypted Data | ESK Sequence, Encrypted Data.

   One-Pass Signed Message :- One-Pass Signature Packet,
               OpenPGP Message, Corresponding Signature Packet.

   Signed Message :- Signature Packet, OpenPGP Message |
               One-Pass Signed Message.

   In addition, decrypting a Symmetrically Encrypted Data packet or a
   Symmetrically Encrypted Integrity Protected Data packet as well as
   decompressing a Compressed Data packet must yield a valid OpenPGP
   Message.

11.4. Detached Signatures

Some OpenPGP applications use so-called "detached signatures". For example, a program bundle may contain a file, and with it a second file that is a detached signature of the first file. These detached signatures are simply a Signature packet stored separately from the data for which they are a signature.


(page 70 continued on part 5)

Next Section