RFC 4880
OpenPGP Message Format
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.
(page 70 continued on part 5)
