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.)

   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.

   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.

   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

   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.

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

   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].

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].

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

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

   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

   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.