idnits 2.17.1 draft-ietf-openpgp-formats-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == The page length should not exceed 58 lines per page, but there was 43 longer pages, the longest (page 2) being 59 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 367 has weird spacing: '...her alg use S...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Unrecognized Status in 'Category: INTERNET-DRAFT', assuming Proposed Standard (Expected one of 'Standards Track', 'Full Standard', 'Draft Standard', 'Proposed Standard', 'Best Current Practice', 'Informational', 'Experimental', 'Informational', 'Historic'.) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 248 -- Looks like a reference, but probably isn't: '1' on line 248 -- Looks like a reference, but probably isn't: '2' on line 248 -- Looks like a reference, but probably isn't: '3' on line 249 == Missing Reference: 'ISO10646' is mentioned on line 288, but not defined == Missing Reference: 'Optional' is mentioned on line 1360, but not defined == Unused Reference: 'DONNERHACKE' is defined on line 2134, but no explicit reference was found in the text == Unused Reference: 'ISO-10646' is defined on line 2142, but no explicit reference was found in the text == Unused Reference: 'RFC822' is defined on line 2151, but no explicit reference was found in the text == Unused Reference: 'RFC1423' is defined on line 2154, but no explicit reference was found in the text == Unused Reference: 'RFC1641' is defined on line 2158, but no explicit reference was found in the text == Unused Reference: 'RFC1750' is defined on line 2161, but no explicit reference was found in the text == Unused Reference: 'RFC1951' is defined on line 2164, but no explicit reference was found in the text == Unused Reference: 'RFC1983' is defined on line 2167, but no explicit reference was found in the text == Unused Reference: 'RFC1991' is defined on line 2169, but no explicit reference was found in the text == Unused Reference: 'RFC2015' is defined on line 2172, but no explicit reference was found in the text == Unused Reference: 'RFC2045' is defined on line 2178, but no explicit reference was found in the text == Unused Reference: 'RFC2119' is defined on line 2182, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'DONNERHACKE' -- Possible downref: Non-RFC (?) normative reference: ref. 'ELGAMAL' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-10646' -- Possible downref: Non-RFC (?) normative reference: ref. 'PKCS1' ** Obsolete normative reference: RFC 822 (Obsoleted by RFC 2822) ** Downref: Normative reference to an Historic RFC: RFC 1423 ** Downref: Normative reference to an Experimental RFC: RFC 1641 ** Obsolete normative reference: RFC 1750 (Obsoleted by RFC 4086) ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Downref: Normative reference to an Informational RFC: RFC 1983 ** Obsolete normative reference: RFC 1991 (Obsoleted by RFC 4880) ** Obsolete normative reference: RFC 2044 (Obsoleted by RFC 2279) Summary: 18 errors (**), 0 flaws (~~), 18 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group Jon Callas 2 Category: INTERNET-DRAFT Network Associates 3 draft-ietf-openpgp-formats-01.txt Lutz Donnerhacke 4 Expires Aug 1998 IN-Root-CA Individual Network e.V. 5 March 1997 Hal Finney 6 Network Associates 7 Rodney Thayer 8 Sable Technology 10 OP Formats - OpenPGP Message Format 11 draft-ietf-openpgp-formats-01.txt 13 Copyright 1998 by The Internet Society. All Rights Reserved. 15 Status of this Memo 17 This document is an Internet-Draft. Internet-Drafts are working 18 documents of the Internet Engineering Task Force (IETF), its areas, and 19 its working groups. Note that other groups may also distribute working 20 documents as Internet-Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet- Drafts as reference 25 material or to cite them other than as "work in progress." 27 To view the entire list of current Internet-Drafts, please check the 28 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 29 Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), 30 ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), 31 ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). 33 Abstract 35 This document is maintained in order to publish all necessary 36 information needed to develop interoperable applications based on the 37 OP format. It is not a step-by-step cookbook for writing an 38 application, it describes only the format and methods needed to read, 39 check, generate and write conforming packets crossing any network. It 40 does not deal with storing and implementation questions albeit it is 41 necessary to avoid security flaws. 43 Open-PGP software uses a combination of strong public-key and 44 conventional cryptography to provide security services for electronic 45 communications and data storage. These services include 46 confidentiality, key management, authentication and digital signatures. 47 This document specifies the message formats used in OP. 49 Table of Contents 51 1. Introduction 52 1.1 Terms 53 2. General functions 54 2.1 Confidentiality via Encryption 55 2.2 Authentication via Digital signature 56 2.3 Compression 57 2.4 Conversion to Radix-64 58 3. Data Element Formats 59 3.1 Scalar numbers 60 3.2 Multi-Precision Integers 61 3.3 Key IDs 62 3.4 Text 63 3.5 Time fields 64 3.6 String-to-key (S2K) specifiers 65 3.6.1 String-to-key (S2k) specifier types 66 3.6.1.1 Simple S2K 67 3.6.1.2 Salted S2K 68 3.6.1.3 Iterated and Salted S2K 69 3.6.2 String-to-key usage 70 3.6.2.1 Secret key encryption 71 3.6.2.2 Conventional message encryption 72 3.6.3 String-to-key algorithms 73 3.6.3.1 Simple S2K algorithm 74 3.6.3.2 Salted S2K algorithm 75 3.6.3.3 Iterated-Salted S2K algorithm 76 4. Packet Syntax 77 4.1 Overview 78 4.2 Packet Headers 79 4.3 Packet Tags 80 5. Packet Types 81 5.1 Public-Key Encrypted Session Key Packets (Tag 1) 82 5.2 Signature Packet (Tag 2) 83 5.2.1 Version 3 Signature Packet Format 84 5.2.2 Version 4 Signature Packet Format 85 5.2.2.1 Signature Subpacket Specification 86 5.2.2.2 Signature Subpacket Types 87 5.2.3 Signature Types 88 5.2.4 Computing Signatures 89 5.3 Symmetric-Key Encrypted Session-Key Packets (Tag 3) 90 5.4 One-Pass Signature Packets (Tag 4) 91 5.5 Key Material Packet 92 5.5.1 Key Packet Variants 93 5.5.1.1 Public Key Packet (Tag 6) 94 5.5.1.2 Public Subkey Packet (Tag 14) 95 5.5.1.3 Secret Key Packet (Tag 5) 96 5.5.1.4 Secret Subkey Packet (Tag 7) 97 5.5.2 Public Key Packet Formats 98 5.5.3 Secret Key Packet Formats 99 5.6 Compressed Data Packet (Tag 8) 100 5.7 Symmetrically Encrypted Data Packet (Tag 9) 101 5.8 Marker Packet (Obsolete Literal Packet) (Tag 10) 102 5.9 Literal Data Packet (Tag 11) 103 5.10 Trust Packet (Tag 12) 104 5.11 User ID Packet (Tag 13) 105 6. Radix-64 Conversions 106 6.1 An Implementation of the CRC-24 in "C" 107 6.2 Forming ASCII Armor 108 6.3 Encoding Binary in Radix-64 109 6.4 Decoding Radix-64 110 6.5 Examples of Radix-64 111 6.6 Example of an ASCII Armored Message 112 7. Cleartext signature framework 113 8. Regular expressions 114 9. Constants 115 9.1 Public Key Algorithms 116 9.2 Symmetric Key Algorithms 117 9.3 Compression Algorithms 118 9.4 Hash Algorithms 119 10. Packet Composition 120 10.1 Transferable Public Keys 121 10.2 OP Messages 122 11. Enhanced Key Formats 123 11.1 Key Structures 124 11.2 V4 Key IDs and Fingerprints 125 12. Security Considerations 126 13. Authors and Working Group Chair 127 14. References 128 15. Full Copyright Statement 130 1. Introduction 132 This document provides information on the message-exchange packet 133 formats used by OP to provide encryption, decryption, signing, key 134 management and functions. It builds on the foundation provided RFC 135 1991 "PGP Message Exchange Formats." 137 1.1 Terms 139 OP - OpenPGP. This is a definition for security software that uses PGP 140 5.x as a basis. 142 PGP - Pretty Good Privacy. PGP is a family of software systems 143 developed by Philip R. Zimmermann from which OP is based. 145 PGP 2.6.x - This version of PGP has many variants, hence the term PGP 146 2.6.x. It used only RSA and IDEA for its cryptography. 148 PGP 5.x - This version of PGP is formerly known as "PGP 3" in the 149 community and also in the predecessor of this document, RFC1991. It 150 has new formats and corrects a number of problems in the PGP 2.6.x. It 151 is referred to here as PGP 5.x because that software was the first 152 release of the "PGP 3" code base. 154 "PGP", "Pretty Good", and "Pretty Good Privacy" are trademarks of 155 Network Associates, Inc. 157 2. General functions 159 OP provides data integrity services for messages and data files by 160 using these core technologies: 162 -digital signature 163 -encryption 164 -compression 165 -radix-64 conversion 167 In addition, OP provides key management and certificate services. 169 2.1 Confidentiality via Encryption 171 OP offers two encryption options to provide confidentiality: 172 conventional (symmetric-key) encryption and public key encryption. 173 With public-key encryption, the message is actually encrypted using a 174 conventional encryption algorithm. In this mode, each conventional key 175 is used only once. That is, a new key is generated as a random number 176 for each message. Since it is used only once, the "session key" is 177 bound to the message and transmitted with it. To protect the key, it 178 is encrypted with the receiver's public key. The sequence is as 179 follows: 181 1. The sender creates a message. 182 2. The sending OP generates a random number to be used as a 183 session key for this message only. 184 3. The session key is encrypted using each recipient's public key. 185 These "encrypted session keys" start the message. 186 4. The sending OP encrypts the message using the session key, which 187 forms the remainder of the message. Note that the message is 188 also usually compressed. 189 5. The receiving OP decrypts the session key using the recipient's 190 private key. 191 6. The receiving OP decrypts the message using the session key. 192 If the message was compressed, it will be decompressed. 194 Both digital signature and confidentiality services may be applied to 195 the same message. First, a signature is generated for the message and 196 attached to the message. Then, the message plus signature is encrypted 197 using a conventional session key. Finally, the session key is 198 encrypted using public-key encryption and prepended to the encrypted 199 block. 201 2.2 Authentication via Digital signature 203 The digital signature uses a hash code or message digest algorithm, and 204 a public-key signature algorithm. The sequence is as follows: 206 1. The sender creates a message. 207 2. The sending software generates a hash code of the message 208 3. The sending software generates a signature from the hash code using 209 the sender's private key. 210 4. The binary signature is attached to the message. 211 5. The receiving software keeps a copy of the message signature. 212 6. The receiving software generates a new hash code for the received 213 message and verifies it using the message's signature. If the 214 verification is successful, the message is accepted as authentic. 216 2.3 Compression 218 OP implementations MAY compress the message after applying the 219 signature but before encryption. 221 2.4 Conversion to Radix-64 223 OP's underlying native representation for encrypted messages, signature 224 certificates, and keys is a stream of arbitrary octets. Some systems 225 only permit the use of blocks consisting of seven-bit, printable text. 226 For transporting OP's native raw binary octets through channels that 227 are not safe to raw binary data, a printable encoding of these binary 228 octets is needed. OP provides the service of converting the raw 8-bit 229 binary octet stream to a stream of printable ASCII characters, called 230 Radix-64 encoding or ASCII Armor. 232 Implementations SHOULD provide Radix-64 conversions. 234 Note that many applications, particularly messaging applications, will 235 want more advanced features as described in the OpenPGP-MIME document, 236 RFC2015. An application that implements OP for messaging SHOULD also 237 implement OpenPGP-MIME. 239 3. Data Element Formats 241 This section describes the data elements used by OP. 243 3.1 Scalar numbers 245 Scalar numbers are unsigned, and are always stored in big-endian 246 format. Using n[k] to refer to the kth octet being interpreted, the 247 value of a two-octet scalar is ((n[0] << 8) + n[1]). The value of a 248 four-octet scalar is ((n[0] << 24) + (n[1] << 16) + (n[2] << 8) + 249 n[3]). 251 3.2 Multi-Precision Integers 253 Multi-Precision Integers (also called MPIs) are unsigned integers used 254 to hold large integers such as the ones used in cryptographic 255 calculations. 257 An MPI consists of two pieces: a two-octet scalar that is the length of 258 the MPI in bits followed by a string of octets that contain the actual 259 integer. 261 These octets form a big-endian number; a big-endian number can be made 262 into an MPI by prefixing it with the appropriate length. 264 Examples: 266 (all numbers are in hexadecimal) 268 The string of octets [00 01 01] forms an MPI with the value 1. The 269 string [00 09 01 FF] forms an MPI with the value of 511. 271 Additional rules: 273 The size of an MPI is ((MPI.length + 7) / 8) + 2. 275 The length field of an MPI describes the length starting from its most 276 significant non-zero bit. Thus, the MPI [00 02 01] is not formed 277 correctly. It should be [00 01 01]. 279 3.3 Key IDs 281 A Key ID is an eight-octet number that identifies a key. 282 Implementations SHOULD NOT assume that Key IDs are unique. The 283 section, "Enhanced Key Formats" below describes how Key IDs are formed. 285 3.4 Text 287 The default character set for text is the UTF-8 [RFC2044] encoding of 288 Unicode [ISO10646]. 290 3.5 Time fields 292 A time field is an unsigned four-octet number containing the number of 293 seconds elapsed since midnight, 1 January 1970 UTC. 295 3.6 String-to-key (S2K) specifiers 297 String-to-key (S2K) specifiers are used to convert passphrase strings 298 into conventional encryption/decryption keys. They are used in two 299 places, currently: to encrypt the secret part of private keys in the 300 private keyring, and to convert passphrases to encryption keys for 301 conventionally encrypted messages. 303 3.6.1 String-to-key (S2k) specifier types 305 There are three types of S2K specifiers currently supported, as 306 follows: 308 3.6.1.1 Simple S2K 310 This directly hashes the string to produce the key data. See below for 311 how this hashing is done. 313 Octet 0: 0x00 314 Octet 1: hash algorithm 316 3.6.1.2 Salted S2K 318 This includes a "salt" value in the S2K specifier -- some arbitrary 319 data -- that gets hashed along with the passphrase string, to help 320 prevent dictionary attacks. 322 Octet 0: 0x01 323 Octet 1: hash algorithm 324 Octets 2-9: 8-octet salt value 326 3.6.1.3 Iterated and Salted S2K 328 This includes both a salt and an octet count. The salt is combined 329 with the passphrase and the resulting value is hashed repeatedly. This 330 further increases the amount of work an attacker must do to try 331 dictionary attacks. 333 Octet 0: 0x04 334 Octet 1: hash algorithm 335 Octets 2-9: 8-octet salt value 336 Octets 10-13: count, a four-octet, unsigned value 338 Note that the value 0x03 for octet 0 of a S2K specifier is reserved; it 339 denotes an obsolete form of the Interated and Salted S2K. 341 3.6.2 String-to-key usage 343 Implementations SHOULD use salted or iterated-and-salted S2K 344 specifiers, as simple S2K specifiers are more vulnerable to dictionary 345 attacks. 347 3.6.2.1 Secret key encryption 349 An S2K specifier can be stored in the secret keyring to specify how to 350 convert the passphrase to a key that unlocks the secret data. Older 351 versions of PGP just stored a cipher algorithm octet preceding the 352 secret data or a zero to indicate that the secret data was unencrypted. 353 The MD5 hash function was always used to convert the passphrase to a 354 key for the specified cipher algorithm. 356 For compatibility, when an S2K specifier is used, the special value 255 357 is stored in the position where the hash algorithm octet would have 358 been in the old data structure. This is then followed immediately by a 359 one-octet algorithm identifier, and then by the S2K specifier as 360 encoded above. 362 Therefore, preceding the secret data there will be one of these 363 possibilities: 365 0 secret data is unencrypted (no pass phrase) 366 255 followed by algorithm octet and S2K specifier 367 Cipher alg use Simple S2K algorithm using MD5 hash 369 This last possibility, the cipher algorithm number with an implicit use 370 of MD5 is provided for backward compatibility; it should be understood, 371 but not generated. 373 These are followed by an 8-octet Initial Vector for the decryption of 374 the secret values, if they are encrypted, and then the secret key 375 values themselves. 377 3.6.2.2 Conventional message encryption 379 PGP 2.X always used IDEA with Simple string-to-key conversion when 380 conventionally encrypting a message. PGP 5 can create a Conventional 381 Encrypted Session Key packet at the front of a message. This can be 382 used to allow S2K specifiers to be used for the passphrase conversion, 383 to allow other ciphers than IDEA to be used, or to create messages with 384 a mix of conventional ESKs and public key ESKs. This allows a message 385 to be decrypted either with a passphrase or a public key. 387 3.6.3 String-to-key algorithms 389 3.6.3.1 Simple S2K algorithm 391 Simple S2K hashes the passphrase to produce the session key. The 392 manner in which this is done depends on the size of the session key 393 (which will depend on the cipher used) and the size of the hash 394 algorithm's output. If the hash size is greater than or equal to the 395 session key size, the leftmost octets of the hash are used as the key. 397 If the hash size is less than the key size, multiple instances of the 398 hash context are created -- enough to produce the required key data. 399 These instances are preloaded with 0, 1, 2, ... octets of zeros (that 400 is to say, the first instance has no preloading, the second gets 401 preloaded with 1 octet of zero, the third is preloaded with two octets 402 of zeros, and so forth). 404 As the data is hashed, it is given independently to each hash context. 405 Since the contexts have been initialized differently, they will each 406 produce different hash output. Once the passphrase is hashed, the 407 output data from the multiple hashes is concatenated, first hash 408 leftmost, to produce the key data, with any excess octets on the right 409 discarded. 411 3.6.3.2 Salted S2K algorithm 413 Salted S2K is exactly like Simple S2K, except that the input to the 414 hash function(s) consists of the 8 octets of salt from the S2K 415 specifier, followed by the passphrase. 417 3.6.3.3 Iterated-Salted S2K algorithm 419 Iterated-Salted S2K hashes the passphrase and salt data multiple times. 420 The total number of octets to be hashed is specified in the four-octet 421 count in the S2K specifier. Note that the resulting count value is an 422 octet count of how many octets will be hashed, not an iteration count. 424 Initially, one or more hash contexts are set up as with the other S2K 425 algorithms, depending on how many octets of key data are needed. Then 426 the salt, followed by the passphrase data is repeatedly hashed until 427 the number of octets specified by the octet count has been hashed. The 428 one exception is that if the octet count is less than the size of the 429 salt plus passphrase, the full salt plus passphrase will be hashed even 430 though that is greater than the octet count. After the hashing is done 431 the data is unloaded from the hash context(s) as with the other S2K 432 algorithms. 434 4. Packet Syntax 436 This section describes the packets used by OP. 438 4.1 Overview 440 An OP message is constructed from a number of records that are 441 traditionally called packets. A packet is a chunk of data that has a 442 tag specifying its meaning. An OP message, keyring, certificate, and 443 so forth consists of a number of packets. Some of those packets may 444 contain other OP packets (for example, a compressed data packet, when 445 uncompressed, contains OP packets). 447 Each packet consists of a packet header, followed by the packet body. 448 The packet header is of variable length. 450 4.2 Packet Headers 452 The first octet of the packet header is called the "Packet Tag." It 453 determines the format of the header and denotes the packet contents. 454 The remainder of the packet header is the length of the packet. 456 Note that the most significant bit is the left-most bit, called bit 7. 457 A mask for this bit is 0x80 in hexadecimal. 459 +---------------+ 460 PTag |7 6 5 4 3 2 1 0| 461 +---------------+ 462 Bit 7 -- Always one 463 Bit 6 -- New packet format if set 465 PGP 2.6.X only uses old format packets. Thus, software that 466 interoperates with those versions of PGP must only use old format 467 packets. If interoperability is not an issue, either format may be 468 used. Note that old format packets have four bits of content tags, and 469 new format packets have six; some features cannot be used and still be 470 backwards-compatible. 472 Old format packets contain: 473 Bits 5-2 -- content tag 474 Bits 1-0 - length-type 476 New format packets contain: 477 Bits 5-0 -- content tag 479 The meaning of the length-type in old-format packets is: 481 0 - The packet has a one-octet length. The header is 2 octets long. 483 1 - The packet has a two-octet length. The header is 3 octets long. 485 2 - The packet has a four-octet length. The header is 5 octets long. 487 3 - The packet is of indeterminate length. The header is 1 byte long, 488 and the application must determine how long the packet is. If the 489 packet is in a file, this means that the packet extends until the end 490 of the file. In general, an application should not use indeterminate 491 length packets except where the end of the data will be clear from the 492 context. 494 New format packets have three possible ways of encoding length. A 495 one-octet Body Length header encodes packet lengths of up to 191 496 octets, and a two-octet Body Length header encodes packet lengths of 497 192 to 8383 octets. For cases where longer packet body lengths are 498 needed, or where the length of the packet body is not known in advance 499 by the issuer, Partial Body Length headers can be used. These are 500 one-octet length headers that encode the length of only part of the 501 data packet. 503 Each Partial Body Length header is followed by a portion of the packet 504 body data. The Partial Body Length header specifies this portion's 505 length. Another length header (of one of the three types) follows that 506 portion. The last length header in the packet must always be a regular 507 Body Length header. Partial Body Length headers may only be used for 508 the non-final parts of the packet. 510 A one-octet Body Length header encodes a length of from 0 to 191 511 octets. This type of length header is recognized because the one octet 512 value is less than 192. The body length is equal to: 514 bodyLen = length_octet; 516 A two-octet Body Length header encodes a length of from 192 to 8383 517 octets. It is recognized because its first octet is in the range 192 518 to 223. The body length is equal to: 520 bodyLen = (1st_octet - 192) * 256 + (2nd_octet) + 192 522 A Partial Body Length header is one octet long and encodes a length 523 which is a power of 2, from 1 to 2147483648 (2 to the 31st power). It 524 is recognized because its one octet value is greater than or equal to 525 224. The partial body length is equal to: 527 partialBodyLen = 1 << (length_octet & 0x1f); 529 Examples: 531 A packet with length 100 may have its length encoded in one octet: 532 0x64. This is followed by 100 octets of data. 534 A packet with length 1723 may have its length coded in two octets: 535 0xC5, 0xFB. This header is followed by the 1723 octets of data. 537 A packet with length 100000 might be encoded in the following octet 538 stream: 0xE1, first two octets of data, 0xE0, next one octet of data, 539 0xEF, next 32768 octets of data, 0xF0, next 65536 octets of data, 0xC5, 540 0xDD, last 1693 octets of data. This is just one possible encoding, 541 and many variations are possible on the size of the Partial Body Length 542 headers, as long as a regular Body Length header encodes the last 543 portion of the data. Note also that the last Body Length header can be 544 a zero-length header. 546 Please note that in all of these explanations, the total length of the 547 packet is the length of the header(s) plus the length of the body. 549 4.3 Packet Tags 551 The packet tag denotes what type of packet the body holds. Note that 552 old format packets can only have tags less than 16, whereas new format 553 packets can have tags as great as 63. The defined tags (in decimal) 554 are: 556 0 -- Reserved. A packet must not have a tag with this value. 557 1 -- Public-Key Encrypted Session Key Packet 558 2 -- Signature Packet 559 3 -- Symmetric-Key Encrypted Session Key Packet 560 4 -- One-Pass Signature Packet 561 5 -- Secret Key Packet 562 6 -- Public Key Packet 563 7 -- Secret Subkey Packet 564 8 -- Compressed Data Packet 565 9 -- Symmetrically Encrypted Data Packet 566 10 -- Marker Packet 567 11 -- Literal Data Packet 568 12 -- Trust Packet 569 13 -- Name Packet 570 14 -- Subkey Packet 571 15 -- Reserved 572 60 to 63 -- Private or Experimental Values 574 5. Packet Types 576 5.1 Public-Key Encrypted Session Key Packets (Tag 1) 578 A Public-Key Encrypted Session Key packet holds the key used to encrypt 579 a message that is itself encrypted with a public key. Zero or more 580 Encrypted Session Key packets and/or Conventional Encrypted Session Key 581 packets may precede a Symmetrically Encrypted Data Packet, which holds 582 an encrypted message. The message is encrypted with a session key, and 583 the session key is itself encrypted and stored in the Encrypted Session 584 Key packet(s). The Symmetrically Encrypted Data Packet is preceded by 585 one Public-Key Encrypted Session Key packet for each OP key to which 586 the message is encrypted. The recipient of the message finds a session 587 key that is encrypted to their public key, decrypts the session key, 588 and then uses the session key to decrypt the message. 590 The body of this packet consists of: 592 - A one-octet number giving the version number of the packet type. 593 The currently defined value for packet version is 3. An 594 implementation should accept, but not generate a version of 2, 595 which is equivalent to V3 in all other respects. 596 - An eight-octet number that gives the key ID of the public key that 597 the session key is encrypted to. 598 - A one-octet number giving the public key algorithm used. 599 - A string of octets that is the encrypted session key. This 600 string takes up the remainder of the packet, and its contents are 601 dependent on the public key algorithm used. 603 Algorithm Specific Fields for RSA encryption 604 - multiprecision integer (MPI) of RSA encrypted value m**e mod n. 606 Algorithm Specific Fields for Elgamal encryption: 607 - MPI of DSA value g**k mod p. 608 - MPI of DSA value m * y**k mod p. 610 The encrypted value "m" in the above formulas is derived from the 611 session key as follows. First the session key is prepended with a 612 one-octet algorithm identifier that specifies the conventional 613 encryption algorithm used to encrypt the following Symmetrically 614 Encrypted Data Packet. Then a two-octet checksum is appended which is 615 equal to the sum of the preceding octets, including the algorithm 616 identifier and session key, modulo 65536. This value is then padded as 617 described in PKCS-1 block type 02 [PKCS1] to form the "m" value used in 618 the formulas above. 620 An implementation MAY use a Key ID of zero as a "wild card" or 621 "speculative" Key ID. In this case, the implementation would try all 622 available private keys, checking for a valid decrypted session key. 623 This format helps reduce traffic analysis of messages. 625 5.2 Signature Packet (Tag 2) 627 A signature packet describes a binding between some public key and some 628 data. The most common signatures are a signature of a file or a block 629 of text, and a signature that is a certification of a user ID. 631 Two versions of signature packets are defined. Version 3 provides 632 basic signature information, while version 4 provides an expandable 633 format with subpackets that can specify more information about the 634 signature. PGP 2.6.X only accepts version 3 signatures. 636 Implementations MUST accept V3 signatures. Implementations SHOULD 637 generate V4 signatures, unless there is a need to generate a signature 638 that can be verified by old implementations. 640 Note that if an implementation is creating an encrypted and signed 641 message that is encrypted to a V3 key, it is reasonable to create a V3 642 signature. 644 5.2.1 Version 3 Signature Packet Format 646 A version 3 Signature packet contains: 647 - One-octet version number (3). 648 - One-octet length of following hashed material. MUST be 5. 649 - One-octet signature type. 650 - Four-octet creation time. 651 - Eight-octet key ID of signer. 652 - One-octet public key algorithm. 653 - One-octet hash algorithm. 654 - Two-octet field holding left 16 bits of signed hash value. 655 - One or more multi-precision integers comprising the signature. 656 This portion is algorithm specific, as described below. 658 The data being signed is hashed, and then the signature type and 659 creation time from the signature packet are hashed (5 additional 660 octets). The resulting hash value is used in the signature algorithm. 661 The high 16 bits (first two octets) of the hash are included in the 662 signature packet to provide a quick test to reject some invalid 663 signatures. 665 Algorithm Specific Fields for RSA signatures: 666 - multiprecision integer (MPI) of RSA signature value m**d. 668 Algorithm Specific Fields for DSA signatures: 669 - MPI of DSA value r. 670 - MPI of DSA value s. 672 The signature calculation is based on a hash of the signed data, as 673 described above. The details of the calculation are different for DSA 674 signature than for RSA signatures. 676 With RSA signatures, the hash value is encoded as described in PKCS-1 677 section 10.1.2, "Data encoding", producing an ASN.1 value of type 678 DigestInfo, and then padded using PKCS-1 block type 01 [PKCS1]. This 679 requires inserting the hash value as an octet string into an ASN.1 680 structure. The object identifier for the type of hash being used is 681 included in the structure. The hexadecimal representations for the 682 currently defined hash algorithms are: 684 - MD5: 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x02, 0x05 685 - SHA-1: 0x2b, 0x0e, 0x03, 0x02, 0x1a 686 - RIPEMD-160: 0x2b, 0x24, 0x03, 0x02, 0x01 688 The ASN.1 OIDs are: 689 - MD5: 1.2.840.113549.2.5 690 - SHA-1: 1.3.14.3.2.26 691 - RIPEMD160: 1.3.36.3.2.1 693 DSA signatures SHOULD use hashes with a size of 160 bits, to match q, 694 the size of the group generated by the DSA key's generator value. The 695 hash function result is treated as a 160 bit number and used directly 696 in the DSA signature algorithm. 698 5.2.2 Version 4 Signature Packet Format 700 A version 4 Signature packet contains: 701 - One-octet version number (4). 702 - One-octet signature type. 703 - One-octet public key algorithm. 704 - One-octet hash algorithm. 705 - Two-octet octet count for following hashed subpacket data. 706 - Hashed subpacket data. (zero or more subpackets) 707 - Two-octet octet count for following unhashed subpacket data. 708 - Unhashed subpacket data. (zero or more subpackets) 709 - Two-octet field holding left 16 bits of signed hash value. 710 - One or more multi-precision integers comprising the signature. 711 This portion is algorithm specific, as described above. 713 The data being signed is hashed, and then the signature data from the 714 version number through the hashed subpacket data is hashed. The 715 resulting hash value is what is signed. The left 16 bits of the hash 716 are included in the signature packet to provide a quick test to reject 717 some invalid signatures. 719 There are two fields consisting of signature subpackets. The first 720 field is hashed with the rest of the signature data, while the second 721 is unhashed. The second set of subpackets is not cryptographically 722 protected by the signature and should include only advisory 723 information. 725 The algorithms for converting the hash function result to a signature 726 are described above. 728 5.2.2.1 Signature Subpacket Specification 730 The subpacket fields consist of zero or more signature subpackets. 731 Each set of subpackets is preceded by a two-octet count of the length 732 of the set of subpackets. 734 Each subpacket consists of a subpacket header and a body. The header 735 consists of: 737 - subpacket length (1 or 2 octets): 738 Length includes the type octet but not this length, 739 1st octet < 192, then length is octet value 740 1st octet >= 192, then length is 2 octets and equal to 741 (1st octet - 192) * 256 + (2nd octet) + 192 743 - subpacket type (1 octet): 744 If bit 7 is set, subpacket understanding is critical, 745 2 = signature creation time, 746 3 = signature expiration time, 747 4 = exportable, 748 5 = trust signature, 749 6 = regular expression, 750 7 = revocable, 751 9 = key expiration time, 752 10 = placeholder for backwards compatibility 753 11 = preferred symmetric algorithms, 754 12 = revocation key, 755 16 = issuer key ID, 756 20 = notation data, 757 21 = preferred hash algorithms, 758 22 = preferred compression algorithms, 759 23 = key server preferences, 760 24 = preferred key server, 761 25 = primary user id, 762 26 = policy URL, 764 27 = key flags, 28 = Signer's user id 766 - subpacket specific data: 768 An implementation SHOULD ignore any subpacket that it does not 769 recognize. 771 Bit 7 of the subpacket type is the "critical" bit. If set, it denotes 772 that the subpacket is one which is critical that the evaluator of the 773 signature recognize. If a subpacket is encountered which is marked 774 critical but is unknown to the evaluating software, the evaluator 775 SHOULD consider the signature to be in error. 777 An evaluator may "recognize" a subpacket, but not implement it. The 778 purpose of the critical bit is to allow the signer to tell an evaluator 779 that it would prefer a new, unknown feature to generate an error than 780 be ignored. 782 5.2.2.2 Signature Subpacket Types 784 Several types of subpackets are currently defined. Some subpackets 785 apply to the signature itself and some are attributes of the key. 786 Subpackets that are found on a self-signature are placed on a user name 787 certification made by the key itself. Note that a key may have more 788 than one user name, and thus may have more than one self-signature, and 789 differing subpackets. 791 A self-signature is a binding signature made by the key the signature 792 refers to. There are three types of self-signatures, the certification 793 signatures (types 0x10-0x13), the direct-key signature (type 0x1f), and 794 the subkey binding signature (type 0x18). For certification 795 self-signatures, username may have a self-signature, and thus different 796 subpackets in those self-signatures. For subkey binding signatures, 797 each subkey in fact has a self-signature. Subpackets that appear in a 798 certification self-signature apply to the username, and subpackets that 799 appear in the subkey self-signature apply to the subkey. Lastly, 800 subpackets on the direct key signature apply to the entire key. 802 Implementing software should interpret a self-signature's preference 803 subpackets as narrowly as possible. For example, suppose a key has two 804 usernames, Alice and Bob. Suppose that Alice prefers the symmetric 805 algorithm CAST5, and Bob prefers IDEA or Triple-DES. If the software 806 locates this key via Alice's name, then the preferred algorithm is 807 CAST5, if software locates the key via Bob's name, then the preferred 808 algorithm is IDEA. If the key is located by key id, then algorithm of 809 the default user name of the key provides the default symmetric 810 algorithm. 812 A subpacket may be found either in the hashed or unhashed subpacket 813 sections of a signature. If a subpacket is not hashed, then the 814 information in it cannot be considered definitive because it is not 815 part of the signature proper. 817 Subpacket types: 819 Signature creation time (4 octet time field) 821 The time the signature was made. Always included with new 822 signatures. 824 Issuer (8 octet key ID) 826 The OP key ID of the key issuing the signature. 828 Key expiration time (4 octet time field) 830 The validity period of the key. This is the number of seconds 831 after the key creation time that the key expires. If this is 832 not present or has a value of zero, the key never expires. This 833 is found only on a self-signature. 835 Preferred symmetric algorithms (array of one-octet values) 837 Symmetric algorithm numbers that indicate which algorithms the 838 key holder prefers to use. This is an ordered list of octets 839 with the most preferred listed first. It should be assumed 840 that only algorithms listed are supported by the recipient's 841 software. Algorithm numbers in section 6. This is only found 842 on a self-signature. 844 Preferred hash algorithms (array of one-octet values) 846 Message digest algorithm numbers that indicate which algorithms 847 the key holder prefers to receive. Like the preferred 848 symmetric algorithms, the list is ordered. Algorithm numbers 849 are in section 6. This is only found on a self-signature. 851 Preferred compression algorithms (array of one-octet values) 853 Compression algorithm numbers that indicate which algorithms 854 the key holder prefers to use. Like the preferred symmetric 855 algorithms, the list is ordered. Algorithm numbers are in 856 section 6. If this subpacket is not included, ZIP is 857 preferred. A zero denotes that uncompressed data is preferred; 858 the key holder's software may not have compression software. 859 This is only found on a self-signature. 861 Signature expiration time (4 octet time field) 862 The validity period of the signature. This is the number of 863 seconds after the signature creation time that the signature 864 expires. If this is not present or has a value of zero, it 865 never expires. 867 Exportable (1 octet of exportability, 0 for not, 1 for exportable) 869 Signature's exportability status. Packet body contains a 870 boolean flag indicating whether the signature is exportable. 871 Signatures which are not exportable are ignored during export 872 and import operations. If this packet is not present the 873 signature is assumed to be exportable. 875 Revocable (1 octet of revocability, 0 for not, 1 for revocable) 877 Signature's revocability status. Packet body contains a 878 boolean flag indicating whether the signature is revocable. 879 Signatures which are not revocable have any later revocation 880 signatures ignored. They represent a commitment by the signer 881 that he cannot revoke his signature for the life of his key. 882 If this packet is not present, the signature is revocable. 884 Trust signature (1 octet "level" (depth), 1 octet of trust amount) 886 Signer asserts that the key is not only valid, but also 887 trustworthy, at the specified level. Level 0 has the same 888 meaning as an ordinary validity signature. Level 1 means that 889 the signed key is asserted to be a valid trusted introducer, 890 with the 2nd octet of the body specifying the degree of trust. 891 Level 2 means that the signed key is asserted to be trusted to 892 issue level 1 trust signatures, i.e. that it is a "meta 893 introducer". Generally, a level n trust signature asserts that 894 a key is trusted to issue level n-1 trust signatures. The 895 trust amount is in a range from 0-255, interpreted such that 896 values less than 120 indicate partial trust and values of 120 897 or greater indicate complete trust. Implementations SHOULD 898 emit values of 60 for partial trust and 120 for complete trust. 900 Regular expression (null-terminated regular expression) 902 Used in conjunction with trust signature packets (of level > 0) 903 to limit the scope of trust which is extended. Only signatures 904 by the target key on user IDs which match the regular 905 expression in the body of this packet have trust extended by 906 the trust packet. The regular expression uses the same syntax 907 as the Henry Spencer's "almost public domain" regular 908 expression package. A description of the syntax in in a 909 section below. 911 Revocation key (1 octet of class, 1 octet of algid, 20 octets of 912 fingerprint) 914 Authorizes the specified key to issue revocation 915 self-signatures for this key. Class octet must have bit 0x80 916 set, other bits are for future expansion to other kinds of 917 signature authorizations. This is found on a self-signature. 919 Authorizes the specified key to issue revocation signatures for 920 this key. Class octet must have bit 0x80 set. If the bit 0x40 921 is set, then this means that the revocation information is 922 sensitive. Other bits are for future expansion to other kinds 923 of authorizations. This is found on a self-signature. 925 If the "sensitive" flag is set, the keyholder feels this 926 subpacket contains private trust information that describes a 927 real-world sensitive relationship. If this flag is set, 928 implementations SHOULD NOT export this signature to other users 929 except in cases where the data needs to be available: when the 930 signature is being sent to the designated revoker, or when it 931 is accompanied by a revocation signature from that revoker. 932 Note that it may be appropriate to isolate this subpacket 933 within a separate signature so that it is not combined with 934 other subpackets which need to be exported. 936 Notation Data (4 octets of flags, 2 octets of name length, 937 2 octets of value length, M octets of name data, 938 N octets of value data) 940 This subpacket describes a "notation" on the signature that the 941 issuer wishes to make. The notation has a name and a value, 942 each of which are strings of octets. There may be more than 943 one notation in a signature. Notations can be used for any 944 extension the issuer of the signature cares to make. The 945 "flags" field holds four octets of flags. 947 All undefined flags MUST be zero. Defined flags are: 948 First octet: 0x80 = human-readable. This note is text, a note 949 from one person to another, and has no 950 meaning to software. 951 Other octets: none. 953 Key server preferences (N octets of flags) 955 This is a list of flags that indicate preferences that the key 956 holder has about how the key is handled on a key server. All 957 undefined flags MUST be zero. 959 First octet: 0x80 = No-modify -- the key holder requests that 960 this key only be modified or updated by the 961 key holder or an authorized administrator of 962 the key server. 963 This is found only on a self-signature. 965 Preferred key server (String) 967 This is a URL of a key server that the key holder prefers be 968 used for updates. Note that keys with multiple user names can 969 have a preferred key server for each user name. Note also that 970 since this is a URL, the key server can actually be a copy of 971 the key retrieved by ftp, http, finger, etc. 973 Primary user id (1 octet, boolean) 975 This is a flag in a user id's self signature that states 976 whether this user id is the main user id for this key. It is 977 reasonable for an implementation to resolve ambiguities in 978 preferences, etc. by referring to the primary user id. If this 979 flag is absent, its value is zero. If more than one user id in 980 a key is marked as primary, the implementation may resolve the 981 ambiguity in any way it sees fit. 983 Policy URL (String) 985 This subpacket contains a URL of a document that describes the 986 policy under which the signature was issued. 988 Key Flags (Octet string) 990 This subpacket contains a list of binary flags that hold 991 information about a key. It is a string of octets, and an 992 implementation MUST NOT assume a fixed size. This is so it can 993 grow over time. If a list is shorter than an implementation 994 expects, the unstated flags are considered to be zero. The 995 defined flags are: 997 First octet: 998 0x01 - This key may be used to certify other keys. 999 0x02 - This key may be used to sign data. 1000 0x04 - This key may be used to encrypt communications. 1001 0x08 - This key may be used to encrypt storage. 1002 0x10 - The private component of this key may have been split by 1003 a secret-sharing mechanism. 1004 0x80 - The private component of this key may be in the posession 1005 of more than one person. 1007 Usage notes: 1009 The flags in this packet may appear in self-signatures or in 1010 certification signatures. They mean different things depending 1011 on who is making the statement -- for example, a certification 1012 signature that has the "sign data" flag is stating that the 1013 certification is for that use. On the other hand, the 1014 "communications encryption" flag in a self-signature is stating 1015 a preference that a given key be used for communications. Note 1016 however, that it is a thorny issue to determine what is 1017 "communications" and what is "storage." This decision is left 1018 wholly up to the implementation; the authors of this document 1019 do not claim any special wisdom on the issue, and realize that 1020 accepted opinion may change. 1022 The "split key" (0x10) and "group key" (0x80) flags are placed 1023 on a self-signature only; they are meaningless on a 1024 certification signature. They SHOULD be placed only on a 1025 direct-key signature (type 0x1f) or a subkey signature (type 1026 0x18), one that refers to the key the flag applies to. 1028 Signer's User ID 1030 This subpacket allows a keyholder to state which user id is 1031 responsible for the signing. Many keyholders use a single key 1032 for different purposes, such as business communications as well 1033 as personal communications. This subpacket allows such a 1034 keyholder to state which of their roles is making a signature. 1036 Implementations SHOULD implement "preferences". 1038 5.2.3 Signature Types 1040 There are a number of possible meanings for a signature, which are 1041 specified in a signature type octet in any given signature. These 1042 meanings are: 1044 - 0x00: Signature of a binary document. 1046 Typically, this means the signer owns it, created it, or certifies that 1047 it has not been modified. 1049 - 0x01: Signature of a canonical text document. 1051 Typically, this means the signer owns it, created it, or certifies that 1052 it has not been modified. The signature will be calculated over the 1053 text data with its line endings converted to . 1055 - 0x02: Standalone signature. 1057 This signature is a signature of only its own subpacket contents. It 1058 is calculated identically to a signature over a zero-length binary 1059 document. Note that it doesn't make sense to have a V3 standalone 1060 signature. 1062 - 0x10: The certification of a User ID and Public Key packet. 1064 The issuer of this certification does not make any particular assertion 1065 as to how well the certifier has checked that the owner of the key is 1066 in fact the person described by the user ID. Note that all PGP "key 1067 signatures" are this type of certification. 1069 - 0x11: This is a persona certification of a User ID and 1070 Public Key packet. 1072 The issuer of this certification has not done any verification of the 1073 claim that the owner of this key is the user ID specified. 1075 - 0x12: This is the casual certification of a User ID and 1076 Public Key packet. 1078 The issuer of this certification has done some casual verification of 1079 the claim of identity. 1081 - 0x13: This is the positive certification of a User ID and 1082 Public Key packet. 1084 The issuer of this certification has done substantial verification of 1085 the claim of identity. 1087 Please note that the vagueness of these certification claims is not a 1088 flaw, but a feature of the system. Because PGP places final authority 1089 for validity upon the receiver of a certification, it may be that one 1090 authority's casual certification might be more rigorous than some other 1091 authority's positive certification. These classifications allow a 1092 certification authority to issue fine-grained claims. 1094 - 0x18: This is used for a signature by a signature key to bind a 1095 subkey which will be used for encryption. 1097 The signature is calculated directly on the subkey itself, not on any 1098 User ID or other packets. 1100 - 0x1f: Signature directly on a key 1102 This signature is calculated directly on a key. It binds the 1103 information in the signature subpackets to the key, and is appropriate 1104 to be used for subpackets which provide information about the key, such 1105 as the revocation key subpacket. It is also appropriate for statements 1106 that non-self certifiers want to make about the key itself, rather than 1107 the binding between a key and a name. 1109 - 0x20: This signature is used to revoke a key. 1111 The signature is calculated directly on the key being revoked. A 1112 revoked key is not to be used. Only revocation signatures by the key 1113 being revoked, or by an authorized revocation key, should be 1114 considered. 1116 - 0x28: This is used to revoke a subkey. 1118 The signature is calculated directly on the subkey being revoked. A 1119 revoked subkey is not to be used. Only revocation signatures by the 1120 top-level signature key which is bound to this subkey, or by an 1121 authorized revocation key, should be considered. 1123 - 0x30: This signature revokes an earlier user ID certification 1124 signature (signature class 0x10 through 0x13). 1126 It should be issued by the same key which issued the revoked signature, 1127 and should have a later creation date than the signature it revokes. 1129 - 0x40: Timestamp signature. 1131 This signature is only meaningful for the timestamp contained in it. 1133 5.2.4 Computing Signatures 1135 All signatures are formed by producing a hash over the signature data, 1136 and then using the resulting hash in the signature algorithm. 1138 The signature data is simple to compute for document signatures (types 1139 0x00 and 0x01), for which the document itself is the data. For 1140 standalone signatures, this is a null string. 1142 When a signature is made over a key, the hash data starts with the 1143 octet 0x99, followed by a two-octet length of the key, and then body of 1144 the key packet. (Note that this is an old-style packet header for a key 1145 packet with two-octet length.) A subkey signature (type 0x18) then 1146 hashes the subkey, using the same format as the main key. Key 1147 revocation signatures (types 0x20 and 0x28) hash only the key being 1148 revoked. 1150 A certification signature (type 0x10 through 0x13) then hashes the user 1151 name being bound to the key. A V3 certification hashes the contents of 1152 the name packet, without any header. A V4 certification hashes the 1153 constant 0xd4 (which is an old-style CTB with the length-of-length set 1154 to zero), a four-octet number giving the length of the username, and 1155 then the username data. 1157 Once the data body is hashed, then a trailer is hashed. A V3 signature 1158 hashes five octets of the packet body, starting from the signature type 1159 field. This data is the signature type, followed by the four-octet 1160 signature time. A V4 signature hashes the packet body starting from 1161 its first field, the version number, through the end of the hashed 1162 subpacket data. Thus, the fields hashed are the signature version, the 1163 signature type, the public key algorithm, the hash algorithm, the 1164 hashed subpacket length, and the hashed subpacket body. 1166 After all this has been hashed, the resulting hash field is used in the 1167 signature algorithm, and placed at the end of the signature packet. 1169 5.3 Symmetric-Key Encrypted Session-Key Packets (Tag 3) 1171 The Symmetric-Key Encrypted Session Key packet holds the 1172 conventional-cipher encryption of a session key used to encrypt a 1173 message. Zero or more Encrypted Session Key packets and/or 1174 Conventional Encrypted Session Key packets may precede a Symmetrically 1175 Encrypted Data Packet that holds an encrypted message. The message is 1176 encrypted with a session key, and the session key is itself encrypted 1177 and stored in the Encrypted Session Key packet or the Conventional 1178 Encrypted Session Key packet. 1180 If the Symmetrically Encrypted Data Packet is preceded by one or more 1181 Symmetric-Key Encrypted Session Key packets, each specifies a 1182 passphrase which may be used to decrypt the message. This allows a 1183 message to be encrypted to a number of public keys, and also to one or 1184 more pass phrases. This packet type is new, and is not generated by 1185 PGP 2.x or PGP 5.0. 1187 The body of this packet consists of: 1188 - A one-octet version number. The only currently defined version is 1189 4. 1190 - A one-octet number describing the symmetric algorithm used. 1191 - A string-to-key (S2K) specifier, length as defined above. 1192 - Optionally, the encrypted session key itself, which is decrypted 1193 with the string-to-key object. 1195 If the encrypted session key is not present (which can be detected on 1196 the basis of packet length and S2K specifier size), then the S2K 1197 algorithm applied to the passphrase produces the session key for 1198 decrypting the file, using the symmetric cipher algorithm from the 1199 Symmetric-Key Encrypted Session Key packet. 1201 If the encrypted session key is present, the result of applying the S2K 1202 algorithm to the passphrase is used to decrypt just that encrypted 1203 session key field, using CFB mode with an IV of all zeros. The 1204 decryption result consists of a one-octet algorithm identifier that 1205 specifies the conventional encryption algorithm used to encrypt the 1206 following Symmetrically Encrypted Data Packet, followed by the session 1207 key octets themselves. 1209 Note: because an all-zero IV is used for this decryption, the S2K 1210 specifier MUST use a salt value, either a a Salted S2K or an 1211 Iterated-Salted S2K. The salt value will insure that the decryption 1212 key is not repeated even if the passphrase is reused. 1214 5.4 One-Pass Signature Packets (Tag 4) 1216 The One-Pass Signature packet precedes the signed data and contains 1217 enough information to allow the receiver to begin calculating any 1218 hashes needed to verify the signature. It allows the Signature Packet 1219 to be placed at the end of the message, so that the signer can compute 1220 the entire signed message in one pass. 1222 A One-Pass Signature does not interoperate with PGP 2.6.x or earlier. 1224 The body of this packet consists of: 1225 - A one-octet version number. The current version is 3. 1226 - A one-octet signature type. Signature types are described 1227 in section 5.2.3. 1228 - A one-octet number describing the hash algorithm used. 1229 - A one-octet number describing the public key algorithm used. 1230 - An eight-octet number holding the key ID of the signing key. 1231 - A one-octet number holding a flag showing whether the signature 1232 is nested. A zero value indicates that the next packet is 1233 another One-Pass Signature packet which describes another 1234 signature to be applied to the same message data. 1236 5.5 Key Material Packet 1238 A key material packet contains all the information about a public or 1239 private key. There are four variants of this packet type, and two 1240 major versions. Consequently, this section is complex. 1242 5.5.1 Key Packet Variants 1244 5.5.1.1 Public Key Packet (Tag 6) 1246 A Public Key packet starts a series of packets that forms an OP key 1247 (sometimes called an OP certificate). 1249 5.5.1.2 Public Subkey Packet (Tag 14) 1251 A Public Subkey packet (tag 14) has exactly the same format as a Public 1252 Key packet, but denotes a subkey. One or more subkeys may be 1253 associated with a top-level key. By convention, the top-level key 1254 provides signature services, and the subkeys provide encryption 1255 services. 1257 Note: in PGP 2.6.X, tag 14 was intended to indicate a comment packet. 1258 This tag was selected for reuse because no previous version of PGP ever 1259 emitted comment packets but they did properly ignore them. Public 1260 Subkey packets are ignored by PGP 2.6.X and do not cause it to fail, 1261 providing a limited degree of backwards compatibility. 1263 5.5.1.3 Secret Key Packet (Tag 5) 1265 A Secret Key packet contains all the information that is found in a 1266 Public Key packet, including the public key material, but also includes 1267 the secret key material after all the public key fields. 1269 5.5.1.4 Secret Subkey Packet (Tag 7) 1271 A Secret Subkey packet (tag 7) is the subkey analog of the Secret Key 1272 packet, and has exactly the same format. 1274 5.5.2 Public Key Packet Formats 1276 There are two versions of key-material packets. Version 3 packets were 1277 first generated PGP 2.6. Version 2 packets are identical in format to 1278 Version 3 packets, but are generated by PGP 2.5 or before. PGP 5.0 1279 introduces version 4 packets, with new fields and semantics. PGP 2.6.X 1280 will not accept key-material packets with versions greater than 3. 1282 OP implementations SHOULD create keys with version 4 format. An 1283 implementation MAY generate a V3 key to ensure interoperability with 1284 old software; note, however, that V4 keys correct some security 1285 deficiencies in V3 keys. These deficiencies are described below. An 1286 implementation MUST NOT create a V3 key with a public key algorithm 1287 other than RSA. 1289 A version 3 public key or public subkey packet contains: 1290 - A one-octet version number (3). 1291 - A four-octet number denoting the time that the key was created. 1292 - A two-octet number denoting the time in days that this key is 1293 valid. If this number is zero, then it does not expire. 1294 - A one-octet number denoting the public key algorithm of this key 1295 - A series of multi-precision integers comprising the key 1296 material: 1297 - a multiprecision integer (MPI) of RSA public modulus n; 1298 - an MPI of RSA public encryption exponent e. 1300 The fingerprint of the key is formed by hashing the body (but not the 1301 two-octet length) of the MPIs that form the key material (public 1302 modulus n, followed by exponent e) with MD5. 1304 The eight-octet key ID of the key consists of the low 64 bits of the 1305 public modulus of an RSA key. 1307 Since the release of V3 keys, there have been a number of improvements 1308 desired in the key format. For example, if the key ID is a function of 1309 the public modulus, it is easy for a person to create a key that has 1310 the same key ID as some existing key. Similarly, MD5 is no longer the 1311 preferred hash algorithm, and not hashing the length of an MPI with its 1312 body increases the chances of a fingerprint collision. 1314 The version 4 format is similar to the version 3 format except for the 1315 absence of a validity period. This has been moved to the signature 1316 packet. In addition, fingerprints of version 4 keys are calculated 1317 differently from version 3 keys, as described in section "Enhanced Key 1318 Formats." 1320 A version 4 packet contains: 1321 - A one-octet version number (4). 1322 - A four-octet number denoting the time that the key was created. 1323 - A one-octet number denoting the public key algorithm of this key 1324 - A series of multi-precision integers comprising the key 1325 material. This algorithm-specific portion is: 1327 Algorithm Specific Fields for RSA public keys: 1328 - multiprecision integer (MPI) of RSA public modulus n; 1329 - MPI of RSA public encryption exponent e. 1331 Algorithm Specific Fields for DSA public keys: 1332 - MPI of DSA prime p; 1333 - MPI of DSA group order q (q is a prime divisor of p-1); 1334 - MPI of DSA group generator g; 1335 - MPI of DSA public key value y (= g**x where x is secret). 1337 Algorithm Specific Fields for Elgamal public keys: 1338 - MPI of Elgamal prime p; 1339 - MPI of Elgamal group generator g; 1340 - MPI of Elgamal public key value y (= g**x where x 1341 is secret). 1343 5.5.3 Secret Key Packet Formats 1345 The Secret Key and Secret Subkey packets contain all the data of the 1346 Public Key and Public Subkey packets, with additional 1347 algorithm-specific secret key data appended, in encrypted form. 1349 The packet contains: 1350 - A Public Key or Public Subkey packet, as described above 1351 - One octet indicating string-to-key usage conventions. 0 indicates 1352 that the secret key data is not encrypted. 255 indicates that a 1353 string-to-key specifier is being given. Any other value 1354 is a conventional encryption algorithm specifier. 1355 - [Optional] If string-to-key usage octet was 255, a one-octet 1356 conventional encryption algorithm. 1357 - [Optional] If string-to-key usage octet was 255, a string-to-key 1358 specifier. The length of the string-to-key specifier is implied 1359 by its type, as described above. 1360 - [Optional] If secret data is encrypted, eight-octet Initial Vector 1361 (IV). 1362 - Encrypted multi-precision integers comprising the secret key data. 1363 These algorithm-specific fields are as described below. 1365 - Two-octet checksum of the plaintext of the algorithm-specific 1366 portion (sum of all octets, mod 65536). 1368 Algorithm Specific Fields for RSA secret keys: 1369 - multiprecision integer (MPI) of RSA secret exponent d. 1370 - MPI of RSA secret prime value p. 1371 - MPI of RSA secret prime value q (p < q). 1372 - MPI of u, the multiplicative inverse of p, mod q. 1374 Algorithm Specific Fields for DSA secret keys: 1375 - MPI of DSA secret exponent x. 1377 Algorithm Specific Fields for Elgamal secret keys: 1378 - MPI of Elgamal secret exponent x. 1380 Secret MPI values can be encrypted using a passphrase. If a 1381 string-to-key specifier is given, that describes the algorithm for 1382 converting the passphrase to a key, else a simple MD5 hash of the 1383 passphrase is used. Implementations SHOULD use a string-to-key 1384 specifier; the simple hash is for backwards compatibility. The cipher 1385 for encrypting the MPIs is specified in the secret key packet. 1387 Encryption/decryption of the secret data is done in CFB mode using the 1388 key created from the passphrase and the Initial Vector from the packet. 1389 A different mode is used with RSA keys than with other key formats. 1390 With RSA keys, the MPI bit count prefix (i.e., the first two octets) is 1391 not encrypted. Only the MPI non-prefix data is encrypted. 1392 Furthermore, the CFB state is resynchronized at the beginning of each 1393 new MPI value, so that the CFB block boundary is aligned with the start 1394 of the MPI data. 1396 With non-RSA keys, a simpler method is used. All secret MPI values are 1397 encrypted in CFB mode, including the MPI bitcount prefix. 1399 The 16-bit checksum that follows the algorithm-specific portion is the 1400 algebraic sum, mod 65536, of the plaintext of all the 1401 algorithm-specific octets (including MPI prefix and data). With RSA 1402 keys, the checksum is stored in the clear. With non-RSA keys, the 1403 checksum is encrypted like the algorithm-specific data. This value is 1404 used to check that the passphrase was correct. 1406 5.6 Compressed Data Packet (Tag 8) 1408 The Compressed Data packet contains compressed data. Typically, this 1409 packet is found as the contents of an encrypted packet, or following a 1410 Signature or One-Pass Signature packet, and contains literal data 1411 packets. 1413 The body of this packet consists of: 1414 - One octet that gives the algorithm used to compress the packet. 1415 - The remainder of the packet is compressed data. 1417 A Compressed Data Packet's body contains an RFC1951 DEFLATE block that 1418 compresses some set of packets. See section "Packet Composition" for 1419 details on how messages are formed. 1421 5.7 Symmetrically Encrypted Data Packet (Tag 9) 1423 The Symmetrically Encrypted Data packet contains data encrypted with a 1424 conventional (symmetric-key) algorithm. When it has been decrypted, it 1425 will typically contain other packets (often literal data packets or 1426 compressed data packets). 1428 The body of this packet consists of: 1430 - Encrypted data, the output of the selected conventional cipher 1431 operating in PGP's variant of Cipher Feedback (CFB) mode. 1433 The conventional cipher used may be specified in an Encrypted Session 1434 Key or Conventional Encrypted Session Key packet which precedes the 1435 Symmetrically Encrypted Data Packet. In that case, the cipher 1436 algorithm octet is prepended to the session key before it is encrypted. 1437 If no packets of these types precede the encrypted data, the IDEA 1438 algorithm is used with the session key calculated as the MD5 hash of 1439 the passphrase. 1441 The data is encrypted in CFB mode, with a CFB shift size equal to the 1442 cipher's block size. The Initial Vector (IV) is specified as all 1443 zeros. Instead of using an IV, OP prefixes a 10 octet string to the 1444 data before it is encrypted. The first eight octets are random, and 1445 the 9th and 10th octets are copies of the 7th and 8th octets, 1446 respectivelly. After encrypting the first 10 octets, the CFB state is 1447 resynchronized if the cipher block size is 8 octets or less. The last 1448 8 octets of ciphertext are passed through the cipher and the block 1449 boundary is reset. 1451 The repetition of 16 bits in the 80 bits of random data prepended to 1452 the message allows the receiver to immediately check whether the 1453 session key is correct. 1455 5.8 Marker Packet (Obsolete Literal Packet) (Tag 10) 1457 An experimental version of PGP used this packet as the Literal packet, 1458 but no released version of PGP generated Literal packets with this tag. 1459 With PGP 5.x, this packet has been re-assigned and is reserved for use 1460 as the Marker packet. 1462 The body of this packet consists of: 1463 - The three octets 0x60, 0x47, 0x60 (which spell "PGP" in UTF-8). 1465 Such a packet MUST be ignored when received. It may be placed at the 1466 beginning of a message that uses features not available in PGP 2.6.X in 1467 order to cause that version to report that newer software necessary to 1468 process the message. 1470 5.9 Literal Data Packet (Tag 11) 1472 A Literal Data packet contains the body of a message; data that is not 1473 to be further interpreted. 1475 The body of this packet consists of: 1476 - A one-octet field that describes how the data is formatted. 1478 If it is a 'b' (0x62), then the literal packet contains binary data. If 1479 it is a 't' (0x74), then it contains text data, and thus may need line 1480 ends converted to local form, or other text-mode changes. RFC 1991 1481 also defined a value of 'l' as a 'local' mode for machine-local 1482 conversions. This use is now deprecated. 1484 - File name as a string (one-octet length, followed by file name), 1485 if the encrypted data should be saved as a file. 1487 If the special name "_CONSOLE" is used, the message is considered to be 1488 "for your eyes only". This advises that the message data is unusually 1489 sensitive, and the receiving program should process it more carefully, 1490 perhaps avoiding storing the received data to disk, for example. 1492 - A four-octet number that indicates the modification date of the 1493 file, or the creation time of the packet, or a zero that indicates the 1494 present time. 1496 - The remainder of the packet is literal data. 1498 Text data is stored with text endings (i.e. network-normal 1499 line endings). These should be converted to native line endings by the 1500 receiving software. 1502 5.10 Trust Packet (Tag 12) 1504 The Trust packet is used only within keyrings and is not normally 1505 exported. Trust packets contain data that record the user's 1506 specifications of which key holders are trustworthy introducers, along 1507 with other information that implementing software uses for trust 1508 information. 1510 Trust packets SHOULD NOT be emitted to output streams that are 1511 transferred to other users, and they SHOULD be ignored on any input 1512 other than local keyring files. 1514 5.11 User ID Packet (Tag 13) 1516 A User ID packet consists of data which is intended to represent the 1517 name and email address of the key holder. By convention, it includes 1518 an RFC822 mail name, but there are no restrictions on its content. The 1519 packet length in the header specifies the length of the user name. If 1520 it is text, it is encoded in UTF-8. 1522 6. Radix-64 Conversions 1524 As stated in the introduction, OP's underlying native representation 1525 for objects is a stream of arbitrary octets, and some systems desire 1526 these objects to be immune to damage caused by character set 1527 translation, data conversions, etc. 1529 In principle, any printable encoding scheme that met the requirements 1530 of the unsafe channel would suffice, since it would not change the 1531 underlying binary bit streams of the native OP data structures. The OP 1532 standard specifies one such printable encoding scheme to ensure 1533 interoperability. 1535 OP's Radix-64 encoding is composed of two parts: a base64 encoding of 1536 the binary data, and a checksum. The base64 encoding is identical to 1537 the MIME base64 content-transfer-encoding [RFC 2045, Section 6.8]. An 1538 OP implementation MAY use ASCII Armor to protect the raw binary data. 1540 The checksum is a 24-bit CRC converted to four characters of radix-64 1541 encoding by the same MIME base64 transformation, preceded by an equals 1542 sign (=). The CRC is computed by using the generator 0x864CFB and an 1543 initialization of 0xB704CE. The accumulation is done on the data 1544 before it is converted to radix-64, rather than on the converted data. 1545 A sample implementation of this algorithm is in the next section. 1547 The checksum with its leading equal sign MAY appear on the first line 1548 after the Base64 encoded data. 1550 Rationale for CRC-24: The size of 24 bits fits evenly into printable 1551 base64. The nonzero initialization can detect more errors than a zero 1552 initialization. 1554 6.1 An Implementation of the CRC-24 in "C" 1556 #define CRC24_INIT 0xb704ce 1557 #define CRC24_POLY 0x1864cfb 1559 crc24 crc_bytes(unsigned char *bytes, size_t len) 1560 { 1561 crc24 crc = CRC_INIT; 1562 int i; 1564 while (len--) { 1565 crc ^= *bytes++; 1566 for (i = 0; i < 8; i++) { 1567 crc <<= 1; 1568 if (crc & 0x1000000) 1569 crc ^= CRC24_POLY; 1570 } 1571 } 1572 return crc; 1573 } 1575 6.2 Forming ASCII Armor 1577 When OP encodes data into ASCII Armor, it puts specific headers around 1578 the data, so OP can reconstruct the data later. OP informs the user 1579 what kind of data is encoded in the ASCII armor through the use of the 1580 headers. 1582 Concatenating the following data creates ASCII Armor: 1584 - An Armor Header Line, appropriate for the type of data 1585 - Armor Headers 1586 - A blank (zero-length, or containing only whitespace) line 1587 - The ASCII-Armored data 1588 - An Armor Checksum 1589 - The Armor Tail, which depends on the Armor Header Line. 1591 An Armor Header Line consists of the appropriate header line text 1592 surrounded by five (5) dashes ('-', 0x2D) on either side of the header 1593 line text. The header line text is chosen based upon the type of data 1594 that is being encoded in Armor, and how it is being encoded. Header 1595 line texts include the following strings: 1597 BEGIN PGP MESSAGE used for signed, encrypted, or 1598 compressed files 1600 BEGIN PGP PUBLIC KEY BLOCK used for armoring public keys 1602 BEGIN PGP PRIVATE KEY BLOCK used for armoring private keys 1604 BEGIN PGP MESSAGE, PART X/Y used for multi-part messages, where 1605 the armor is split amongst Y parts, 1606 and this is the Xth part out of Y. 1608 BEGIN PGP MESSAGE, PART X used for multi-part messages, where 1609 this is the Xth part of an 1610 unspecified number of parts. 1611 Requires the MESSAGE-ID Armor 1612 Header to be used. 1614 BEGIN PGP SIGNATURE used for detached signatures, 1615 OP/MIME signatures, and signatures 1616 following clearsigned messages 1618 The Armor Headers are pairs of strings that can give the user or the 1619 receiving OP message block some information about how to decode or use 1620 the message. The Armor Headers are a part of the armor, not a part of 1621 the message, and hence are not protected by any signatures applied to 1622 the message. 1624 The format of an Armor Header is that of a key-value pair. A colon 1625 (':' 0x38) and a single space (0x20) separate the key and value. OP 1626 should consider improperly formatted Armor Headers to be corruption of 1627 the ASCII Armor. Unknown keys should be reported to the user, but OP 1628 should continue to process the message. 1630 Currently defined Armor Header Keys are: 1632 - "Version", which states the OP Version used to encode the 1633 message. 1635 - "Comment", a user-defined comment. 1637 - "MessageID", a 32-character string of printable characters. The 1638 string must be the same for all parts of a multi-part message that 1639 uses the "PART X" Armor Header. MessageID strings should be unique 1640 enough that the recipient of the mail can associate all the parts 1641 of a message with each other. A good checksum or cryptographic 1642 hash function is sufficent. 1644 The MessageID should not appear unless it is in a multi-part 1645 message. If it appears at all, it MUST be computed from the message 1646 in a deterministic fashion, rather than contain a purely random 1647 value. This is to allow anyone to determine that the MessageID 1648 cannot serve as a covert means of leaking cryptographic key 1649 information. 1651 The Armor Tail Line is composed in the same manner as the Armor Header 1652 Line, except the string "BEGIN" is replaced by the string "END." 1654 6.3 Encoding Binary in Radix-64 1656 The encoding process represents 24-bit groups of input bits as output 1657 strings of 4 encoded characters. Proceeding from left to right, a 1658 24-bit input group is formed by concatenating three 8-bit input groups. 1659 These 24 bits are then treated as four concatenated 6-bit groups, each 1660 of which is translated into a single digit in the Radix-64 alphabet. 1661 When encoding a bit stream with the Radix-64 encoding, the bit stream 1662 must be presumed to be ordered with the most-significant-bit first. 1663 That is, the first bit in the stream will be the high-order bit in the 1664 first 8-bit byte, and the eighth bit will be the low-order bit in the 1665 first 8-bit byte, and so on. 1667 +--first octet--+-second octet--+--third octet--+ 1668 |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0| 1669 +-----------+---+-------+-------+---+-----------+ 1670 |5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0| 1671 +--1.index--+--2.index--+--3.index--+--4.index--+ 1673 Each 6-bit group is used as an index into an array of 64 printable 1674 characters from the table below. The character referenced by the index 1675 is placed in the output string. 1677 Value Encoding Value Encoding Value Encoding Value Encoding 1678 0 A 17 R 34 i 51 z 1679 1 B 18 S 35 j 52 0 1680 2 C 19 T 36 k 53 1 1681 3 D 20 U 37 l 54 2 1682 4 E 21 V 38 m 55 3 1683 5 F 22 W 39 n 56 4 1684 6 G 23 X 40 o 57 5 1685 7 H 24 Y 41 p 58 6 1686 8 I 25 Z 42 q 59 7 1687 9 J 26 a 43 r 60 8 1688 10 K 27 b 44 s 61 9 1689 11 L 28 c 45 t 62 + 1690 12 M 29 d 46 u 63 / 1691 13 N 30 e 47 v 1692 14 O 31 f 48 w (pad) = 1693 15 P 32 g 49 x 1694 16 Q 33 h 50 y 1696 The encoded output stream must be represented in lines of no more than 1697 76 characters each. 1699 Special processing is performed if fewer than 24 bits are available at 1700 the end of the data being encoded. There are three possibilities: 1702 - The last data group has 24 bits (3 octets). No special processing is 1703 needed. 1705 - The last data group has 16 bits (2 octets). The first two 6-bit 1706 groups are processed as above. The third (incomplete) data group has 1707 two zero-value bits added to it, and is processed as above. A pad 1708 character (=) is added to the output. 1710 - The last data group has 8 bits (1 octet). The first 6-bit group is 1711 processed as above. The second (incomplete) data group has four 1712 zero-value bits added to it, and is processed as above. Two pad 1713 characters (=) are added to the output. 1715 6.4 Decoding Radix-64 1717 Any characters outside of the base64 alphabet are ignored in Radix-64 1718 data. Decoding software must ignore all line breaks or other 1719 characters not found in the table above. 1721 In Radix-64 data, characters other than those in the table, line 1722 breaks, and other white space probably indicate a transmission error, 1723 about which a warning message or even a message rejection might be 1724 appropriate under some circumstances. 1726 Because it is used only for padding at the end of the data, the 1727 occurrence of any "=" characters may be taken as evidence that the end 1728 of the data has been reached (without truncation in transit). No such 1729 assurance is possible, however, when the number of octets transmitted 1730 was a multiple of three and no "=" characters are present. 1732 6.5 Examples of Radix-64 1734 Input data: 0x14fb9c03d97e 1735 Hex: 1 4 f b 9 c | 0 3 d 9 7 e 1736 8-bit: 00010100 11111011 10011100 | 00000011 11011001 11111110 1737 6-bit: 000101 001111 101110 011100 | 000000 111101 100111 111110 1738 Decimal: 5 15 46 28 0 61 37 63 1739 Output: F P u c A 9 l / 1741 Input data: 0x14fb9c03d9 1742 Hex: 1 4 f b 9 c | 0 3 d 9 1743 8-bit: 00010100 11111011 10011100 | 00000011 11011001 1744 pad with 00 1745 6-bit: 000101 001111 101110 011100 | 000000 111101 100100 1746 Decimal: 5 15 46 28 0 61 36 1747 pad with = 1748 Output: F P u c A 9 k = 1750 Input data: 0x14fb9c03 1751 Hex: 1 4 f b 9 c | 0 3 1752 8-bit: 00010100 11111011 10011100 | 00000011 1753 pad with 0000 1754 6-bit: 000101 001111 101110 011100 | 000000 110000 1755 Decimal: 5 15 46 28 0 48 1756 pad with = = 1757 Output: F P u c A w = = 1759 6.6 Example of an ASCII Armored Message 1761 -----BEGIN PGP MESSAGE----- 1762 Version: OP V0.0 1764 owFbx8DAYFTCWlySkpkHZDKEFCXmFedmFhdn5ucpZKdWFiv4hgaHKPj5hygUpSbn 1765 l6UWpabo8XIBAA== 1766 =3m1o 1767 -----END PGP MESSAGE----- 1769 Note that this example is indented by two spaces. 1771 7. Cleartext signature framework 1773 It is desirable to sign a textual octet stream without ASCII armoring 1774 the stream itself, so the signed text is still readable without special 1775 software. In order to bind a signature to such a cleartext, this 1776 framework is used. (Note that RFC 2015 defines another way to clear 1777 sign messages for environments that support MIME.) 1779 The cleartext signed message consists of: 1780 - The cleartext header '-----BEGIN PGP SIGNED MESSAGE-----' on a 1781 single line, 1782 - Zero or more "Hash" Armor Headers, 1783 - Exactly one empty line not included into the message digest, 1784 - The dash-escaped cleartext that is included into the message digest, 1785 - The ASCII armored signature(s) including the Armor Header and Armor 1786 Tail Lines. 1788 If the "Hash" armor header is given, the specified message digest 1789 algorithm is used for the signature. If there are no such headers, 1790 SHA-1 is used. If more than one message digest is used in the 1791 signature, the "Hash" armor header contains a comma-delimited list of 1792 used message digests. 1794 Current message digest names are: 1796 - "SHA1" 1797 - "MD5" 1798 - "RIPEMD160" 1800 The cleartext content of the message must also be dash-escaped. 1802 Dash escaped cleartext is the ordinary cleartext where every line 1803 starting with a dash '-' (0x2D) is prefixed by the sequence dash '-' 1804 (0x2D) and space ' ' (0x20). This prevents the parser from recognizing 1805 armor headers of the cleartext itself. The message digest is computed 1806 using the cleartext itself, not the dash escaped form. 1808 As with binary signatures on text documents, a cleartext signature is 1809 calculated on the text using canonical line endings. The line 1810 ending (i.e. the ) before the '-----BEGIN PGP SIGNATURE-----' 1811 line that terminates the signed text is not considered part of the 1812 signed text. 1814 Also, any trailing whitespace (spaces, and tabs, 0x09) at the end of 1815 any line is ignored when the cleartext signature is calculated. 1817 8. Regular Expressions 1819 A regular expression is zero or more branches, separated by `|'. It 1820 matches anything that matches one of the branches. 1822 A branch is zero or more pieces, concatenated. It matches a match for 1823 the first, followed by a match for the second, etc. 1825 A piece is an atom possibly followed by `*', `+', or `?'. An atom 1826 followed by `*' matches a sequence of 0 or more matches of the atom. 1827 An atom followed by `+' matches a sequence of 1 or more matches of the 1828 atom. An atom fol- lowed by `?' matches a match of the atom, or the 1829 null string. 1831 An atom is a regular expression in parentheses (matching a match for 1832 the regular expression), a range (see below), `.' (matching any single 1833 character), `^' (matching the null string at the beginning of the input 1834 string), `$' (matching the null string at the end of the input string), 1835 a `\' followed by a single character (matching that char- acter), or a 1836 single character with no other significance (matching that character). 1838 A range is a sequence of characters enclosed in `[]'. It normally 1839 matches any single character from the sequence. If the sequence begins 1840 with `^', it matches any single character not from the rest of the 1841 sequence. If two char- acters in the sequence are separated by `-', 1842 this is shorthand for the full list of ASCII characters between them 1843 (e.g. `[0-9]' matches any decimal digit). To include a literal `]' in 1844 the sequence, make it the first character (following a possible `^'). 1845 To include a literal `-', make it the first or last character. 1847 9. Constants 1849 This section describes the constants used in OP. 1851 Note that these tables are not exhaustive lists; an implementation MAY 1852 implement an algorithm not on these lists. 1854 9.1 Public Key Algorithms 1856 1 - RSA (Encrypt or Sign) 1857 2 - RSA Encrypt-Only 1858 3 - RSA Sign-Only 1859 16 - Elgamal, see [ELGAMAL] 1860 17 - DSA (Digital Signature Standard) 1861 18 - Elliptic Curve 1862 19 - ECDSA 1863 21 - Diffie-Hellman (X9.42) 1864 100 to 110 - Private/Experimental algorithm. 1866 Implementations MUST implement DSA for signatures, and Elgamal for 1867 encryption. Implementations SHOULD implement RSA encryption. 1868 Implementations MAY implement any other algorithm. 1870 9.2 Symmetric Key Algorithms 1872 0 - Plaintext 1873 1 - IDEA 1874 2 - Triple-DES (DES-EDE, as per spec - 1875 168 bit key derived from 192) 1876 3 - CAST5 (128 bit key) 1877 4 - Blowfish (128 bit key, 16 rounds) 1878 5 - ROT-N (128 bit N) 1879 6 - SAFER-SK128 1880 7 - DES/SK 1881 100 to 110 - Private/Experimental algorithm. 1883 Implementations MUST implement Triple-DES. Implementations SHOULD 1884 implement IDEA and CAST5.Implementations MAY implement any other 1885 algorithm. 1887 9.3 Compression Algorithms 1889 0 - Uncompressed 1890 1 - ZIP 1891 100 to 110 - Private/Experimental algorithm. 1893 Implementations MUST implement uncompressed data. Implementations 1894 SHOULD implement ZIP. 1896 9.4 Hash Algorithms 1898 1 - MD5 1899 2 - SHA-1 1900 3 - RIPE-MD/160 1901 4 - HAVAL 1902 100 to 110 - Private/Experimental algorithm. 1904 Implementations MUST implement SHA-1. Implementations SHOULD implement 1905 MD5. 1907 10. Packet Composition 1909 OP packets are assembled into sequences in order to create messages and 1910 to transfer keys. Not all possible packet sequences are meaningful and 1911 correct. This describes the rules for how packets should be placed 1912 into sequences. 1914 10.1 Transferable Public Keys 1916 OP users may transfer public keys. The essential elements of a 1917 transferable public key are: 1919 - One Public Key packet 1920 - Zero or more revocation signatures 1921 - One or more User ID packets 1922 - After each User ID packet, zero or more Signature packets 1923 - Zero or more Subkey packets 1924 - After each Subkey packet, one or more Signature packets 1926 The Public Key packet occurs first. Each of the following User ID 1927 packets provides the identity of the owner of this public key. If 1928 there are multiple User ID packets, this corresponds to multiple means 1929 of identifying the same unique individual user; for example, a user may 1930 enjoy the use of more than one e-mail address, and construct a User ID 1931 packet for each one. 1933 Immediately following each User ID packet, there are zero or more 1934 signature packets. Each signature packet is calculated on the 1935 immediately preceding User ID packet and the initial Public Key packet. 1936 The signature serves to certify the corresponding public key and user 1937 ID. In effect, the signer is testifying to his or her belief that this 1938 public key belongs to the user identified by this user ID. 1940 After the User ID packets there may be one or more Subkey packets. In 1941 general, subkeys are provided in cases where the top-level public key 1942 is a signature-only key. However, any V4 key may have subkeys, and the 1943 subkeys may be encryption-only keys, signature-only keys, or 1944 general-purpose keys. 1946 Each Subkey packet must be followed by at least one Signature packet, 1947 which should be of the subkey binding signature type, issued by the top 1948 level key. 1950 Subkey and Key packets may each be followed by a revocation Signature 1951 packet to indicate that the key is revoked. Revocation signatures are 1952 only accepted if they are issued by the key itself, or by a key which 1953 is authorized to issue revocations via a revocation key subpacket in a 1954 self-signature by the top level key. 1956 Transferable public key packet sequences may be concatenated to allow 1957 transferring multiple public keys in one operation. 1959 10.2 OP Messages 1961 An OP message is a packet or sequence of packets that corresponds to 1962 the following grammatical rules (comma represents sequential 1963 composition, and vertical bar separates alternatives): 1965 OP Message :- Encrypted Message | Signed Message | Compressed Message 1966 | Literal Message. 1968 Compressed Message :- Compressed Data Packet. 1970 Literal Message :- Literal Data Packet. 1972 ESK :- Pubic Key Encrypted Session Key Packet | 1973 Conventionally Encrypted Session Key Packet. 1975 ESK Sequence :- ESK | ESK Sequence, ESK. 1977 Encrypted Message :- Symmetrically Encrypted Data Packet | 1978 ESK Sequence, Symmetrically Encrypted Data Packet. 1980 One-Pass Signed Message :- One-Pass Signature Packet, OP Message, 1981 Signature Packet. 1983 Signed Message :- Signature Packet, OP Message | 1984 One-Pass Signed Message. 1986 In addition, decrypting a Symmetrically Encrypted Data packet and 1987 decompressing a Compressed Data packet must yield a valid OP Message. 1989 11. Enhanced Key Formats 1991 11.1 Key Structures 1993 The format of V3 OP key using RSA is as follows. Entries in square 1994 brackets are optional and ellipses indicate repetition. 1996 RSA Public Key 1997 [Revocation Self Signature] 1998 User ID [Signature ...] 1999 [User ID [Signature ...] ...] 2001 Each signature certifies the RSA public key and the preceding user ID. 2002 The RSA public key can have many user IDs and each user ID can have 2003 many signatures. 2005 The format of an OP V4 key that uses two public keys is very similar 2006 except that the second key is added to the end as a 'subkey' of the 2007 primary key. 2009 Primary-Key 2010 [Revocation Self Signature] 2011 [Direct Key Self Signature...] 2012 User ID [Signature ...] 2013 [User ID [Signature ...] ...] 2015 [Subkey Primary-Key-Signature] 2017 The subkey always has a single signature after it that is issued using 2018 the primary key to tie the two keys together. The new format can use 2019 either the new signature packets or the old signature packets. 2021 In an key that has a main key and subkeys, the primary key MUST be a 2022 key capable of signing. The subkeys may be keys of any other type, and 2023 either version 3 or 4 of the signature packet can be used. There may 2024 be other types of V4 keys, too. For example, there may be a single-key 2025 RSA key in V4 format, a DSA primary key with an RSA encryption key, 2026 etc, or RSA primary key with an Elgamal subkey. 2028 It is also possible to have a signature-only subkey. This permits a 2029 primary key that collects certifications (key signatures) but is used 2030 only used for certifying subkeys that are used for encryption and 2031 signatures. 2033 11.2 V4 Key IDs and Fingerprints 2035 A V4 fingerprint is the 160-bit SHA-1 hash of the one-octet Packet Tag, 2036 followed by the two-octet packet length, followed by the entire Public 2037 Key packet starting with the version field. The key ID is either the 2038 low order 32 bits or 64 bits of the fingerprint. Here are the fields 2039 of the hash material, with the example of a DSA key: 2041 a.1) 0x99 (1 byte) 2042 a.2) high order length byte of (b)-(f) (1 byte) 2043 a.3) low order length byte of (b)-(f) (1 byte) 2044 b) version number = 4 (1 byte); 2045 c) time stamp of key creation (4 bytes); 2046 e) algorithm (1 byte): 2047 17 = DSA; 2048 f) Algorithm specific fields. 2050 Algorithm Specific Fields for DSA keys (example): 2051 f.1) MPI of DSA prime p; 2052 f.2) MPI of DSA group order q (q is a prime divisor of p-1); 2053 f.3) MPI of DSA group generator g; 2054 f.4) MPI of DSA public key value y (= g**x where x is secret). 2056 12. Security Considerations 2058 As with any technology involving cryptography, you should check the 2059 current literature to determine if any algorithms used here have been 2060 found to be vulnerable to attack. 2062 This specification uses Public Key Cryptography technologies. 2063 Possession of the private key portion of a public-private key pair is 2064 assumed to be controlled by the proper party or parties. 2066 Certain operations in this specification involve the use of random 2067 numbers. An appropriate entropy source should be used to generate 2068 these numbers. See RFC 1750. 2070 The MD5 hash algorithm has been found to have weaknesses 2071 (pseudo-collisions in the compress function) that make some people 2072 deprecate its use. They consider the SHA-1 algorithm better. 2074 If you are building an authentication system, the recipient may specify 2075 a preferred signing algorithm. However, the signer would be foolish to 2076 use a weak algorithm simply because the recipient requests it. 2078 Some of the encryption algorithms mentioned in this document have been 2079 analyzed less than others. For example, although CAST5 is presently 2080 considered strong, it has been analyzed less than Triple-DES. Other 2081 algorithms may have other controversies surrounding them. 2083 Some technologies mentioned here may be subject to government control 2084 in some countries. 2086 13. Authors and Working Group Chair 2088 The working group can be contacted via the current chair: 2090 John W. Noerenberg, II 2091 Qualcomm, Inc 2092 6455 Lusk Blvd 2093 San Diego, CA 92131 USA 2094 Email: jwn2@qualcomm.com 2095 Tel: +1 619-658-3510 2097 The principal authors of this draft are (in alphabetical order): 2099 Jon Callas 2100 Network Associates, Inc. 2101 4200 Bohannon Drive 2102 Menlo Park, CA 94025, USA 2103 Email: jon@pgp.com 2104 Tel: +1-650-473-2860 2106 Lutz Donnerhacke 2107 IKS GmbH 2108 Wildenbruchstr. 15 2109 07745 Jena, Germany 2110 EMail: lutz@iks-jena.de 2111 Tel: +49-3641-675642 2113 Hal Finney 2114 Network Associates, Inc. 2115 4200 Bohannon Drive 2116 Menlo Park, CA 94025, USA 2117 Email: hal@pgp.com 2119 Rodney Thayer 2120 Sable Technology Corporation 2121 246 Walnut Street 2122 Newton, MA 02160 USA 2123 Email: rodney@sabletech.com 2124 Tel: +1-617-332-7292 2126 This draft also draws on much previous work from a number of other 2127 authors who include: Derek Atkins, Charles Breed, Dave Del Torto, Marc 2128 Dyksterhouse, Gail Haspert, Gene Hoffman, Paul Hoffman, Raph Levine, 2129 Colin Plumb, Will Price, William Stallings, Mark Weaver, and Philip R. 2130 Zimmermann. 2132 14. References 2134 [DONNERHACKE] Donnerhacke, L., et. al, "PGP263in - an improved 2135 international version of PGP", 2136 ftp://ftp.iks-jena.de/mitarb/lutz/crypt/software/pgp/ 2138 [ELGAMAL] T. ElGamal, "A Public-Key Cryptosystem and a Signature 2139 Scheme Based on Discrete Logarithms," IEEE Transactions on Information 2140 Theory, v. IT-31, n. 4, 1985, pp. 469-472. 2142 [ISO-10646] ISO/IEC 10646-1:1993. International Standard -- 2143 Information technology -- Universal Multiple-Octet Coded Character Set 2144 (UCS) -- Part 1: Architecture and Basic Multilingual Plane. UTF-8 is 2145 described in Annex R, adopted but not yet published. UTF-16 is 2146 described in Annex Q, adopted but not yet published. 2148 [PKCS1] RSA Laboratories, "PKCS #1: RSA Encryption Standard," version 2149 1.5, November 1993 2151 [RFC822] D. Crocker, "Standard for the format of ARPA Internet text 2152 messages", RFC 822, August 1982 2154 [RFC1423] D. Balenson, "Privacy Enhancement for Internet Electronic 2155 Mail: Part III: Algorithms, Modes, and Identifiers", RFC 1423, 2156 October 1993 2158 [RFC1641] Goldsmith, D., and M. Davis, "Using Unicode with MIME", RFC 2159 1641, Taligent inc., July 1994. 2161 [RFC1750] Eastlake, Crocker, & Schiller., Randomness Recommendations 2162 for Security. December 1994. 2164 [RFC1951] Deutsch, P., DEFLATE Compressed Data Format Specification 2165 version 1.3. May 1996. 2167 [RFC1983] G. Malkin., Internet Users' Glossary. August 1996. 2169 [RFC1991] Atkins, D., Stallings, W., and P. Zimmermann, "PGP Message 2170 Exchange Formats", RFC 1991, August 1996. 2172 [RFC2015] Elkins, M., "MIME Security with Pretty Good Privacy (PGP)", 2173 RFC 2015, October 1996. 2175 [RFC2044] F. Yergeau., UTF-8, a transformation format of Unicode and 2176 ISO 10646. October 1996. 2178 [RFC2045] Borenstein, N., and Freed, N., "Multipurpose Internet Mail 2179 Extensions (MIME) Part One: Format of Internet Message Bodies.", 2180 November 1996 2182 [RFC2119] Bradner, S., Key words for use in RFCs to Indicate 2183 Requirement Level. March 1997. 2185 15. Full Copyright Statement 2187 Copyright 1998 by The Internet Society. All Rights Reserved. 2189 This document and translations of it may be copied and furnished to 2190 others, and derivative works that comment on or otherwise explain it or 2191 assist in its implementation may be prepared, copied, published and 2192 distributed, in whole or in part, without restriction of any kind, 2193 provided that the above copyright notice and this paragraph are 2194 included on all such copies and derivative works. However, this 2195 document itself may not be modified in any way, such as by removing the 2196 copyright notice or references to the Internet Society or other 2197 Internet organizations, except as needed for the purpose of developing 2198 Internet standards in which case the procedures for copyrights defined 2199 in the Internet Standards process must be followed, or as required to 2200 translate it into languages other than English. 2202 The limited permissions granted above are perpetual and will not be 2203 revoked by the Internet Society or its successors or assigns.