1Network Working Group Jon Callas 2Category: INTERNET-DRAFT PGP Corporation 3draft-ietf-openpgp-rfc2440bis-14.txt 4Expires January 2006 Lutz Donnerhacke 5July 2005 6 7Obsoletes: 1991, 2440 Hal Finney 8 PGP Corporation 9 10 Rodney Thayer 11 12 OpenPGP Message Format 13 draft-ietf-openpgp-rfc2440bis-14.txt 14 15 16 Copyright (C) The Internet Society (2005). 17 18Status of this Memo 19 20 This document is an Internet-Draft and is in full conformance with 21 all provisions of Section 10 of RFC 2026. 22 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF), its areas, and its working groups. Note that 25 other groups may also distribute working documents as 26 Internet-Drafts. 27 28 Internet-Drafts are draft documents valid for a maximum of six 29 months and may be updated, replaced, or obsoleted by other documents 30 at any time. It is inappropriate to use Internet-Drafts as 31 reference material or to cite them other than as "work in progress." 32 33 The list of current Internet-Drafts can be accessed at 34 http://www.ietf.org/ietf/1id-abstracts.txt 35 36 The list of Internet-Draft Shadow Directories can be accessed at 37 http://www.ietf.org/shadow.html. 38 39IPR Claim Notice 40 41 By submitting this Internet-Draft, each author represents that any 42 applicable patent or other IPR claims of which he or she is aware 43 have been or will be disclosed, and any of which he or she becomes 44 aware will be disclosed, in accordance with Section 6 of BCP 79. 45 46IESG Note 47 48 This document defines many tag values, yet it doesn't describe a 49 mechanism for adding new tags (for new features). Traditionally the 50 Internet Assigned Numbers Authority (IANA) handles the allocation of 51 new values for future expansion and RFCs usually define the 52 procedure to be used by the IANA. However there are subtle (and not 53 so subtle) interactions that may occur in this protocol between new 54 features and existing features which result in a significant 55 56Callas, et al. Expires Jan 08, 2006 [Page 1] 57 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 58 59 reduction in over all security. Therefore this document does not 60 define an extension procedure. Instead requests to define new tag 61 values (say for new encryption algorithms for example) should be 62 forwarded to the IESG Security Area Directors for consideration or 63 forwarding to the appropriate IETF Working Group for consideration. 64 65Abstract 66 67 This document is maintained in order to publish all necessary 68 information needed to develop interoperable applications based on 69 the OpenPGP format. It is not a step-by-step cookbook for writing an 70 application. It describes only the format and methods needed to 71 read, check, generate, and write conforming packets crossing any 72 network. It does not deal with storage and implementation questions. 73 It does, however, discuss implementation issues necessary to avoid 74 security flaws. 75 76 OpenPGP software uses a combination of strong public-key and 77 symmetric cryptography to provide security services for electronic 78 communications and data storage. These services include 79 confidentiality, key management, authentication, and digital 80 signatures. This document specifies the message formats used in 81 OpenPGP. 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112Callas, et al. Expires Jan 08, 2006 [Page 2] 113 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 114 115Table of Contents 116 117 Status of this Memo 1 118 IPR Claim Notice 1 119 IESG Note 1 120 Abstract 2 121 Table of Contents 3 122 1. Introduction 6 123 1.1. Terms 6 124 2. General functions 6 125 2.1. Confidentiality via Encryption 7 126 2.2. Authentication via Digital signature 7 127 2.3. Compression 8 128 2.4. Conversion to Radix-64 8 129 2.5. Signature-Only Applications 8 130 3. Data Element Formats 9 131 3.1. Scalar numbers 9 132 3.2. Multiprecision Integers 9 133 3.3. Key IDs 9 134 3.4. Text 10 135 3.5. Time fields 10 136 3.6. Keyrings 10 137 3.7. String-to-key (S2K) specifiers 10 138 3.7.1. String-to-key (S2K) specifier types 10 139 3.7.1.1. Simple S2K 10 140 3.7.1.2. Salted S2K 11 141 3.7.1.3. Iterated and Salted S2K 11 142 3.7.2. String-to-key usage 12 143 3.7.2.1. Secret key encryption 12 144 3.7.2.2. Symmetric-key message encryption 13 145 4. Packet Syntax 13 146 4.1. Overview 13 147 4.2. Packet Headers 13 148 4.2.1. Old-Format Packet Lengths 14 149 4.2.2. New-Format Packet Lengths 14 150 4.2.2.1. One-Octet Lengths 15 151 4.2.2.2. Two-Octet Lengths 15 152 4.2.2.3. Five-Octet Lengths 15 153 4.2.2.4. Partial Body Lengths 15 154 4.2.3. Packet Length Examples 16 155 4.3. Packet Tags 16 156 5. Packet Types 17 157 5.1. Public-Key Encrypted Session Key Packets (Tag 1) 17 158 5.2. Signature Packet (Tag 2) 18 159 5.2.1. Signature Types 18 160 5.2.2. Version 3 Signature Packet Format 20 161 5.2.3. Version 4 Signature Packet Format 23 162 5.2.3.1. Signature Subpacket Specification 23 163 5.2.3.2. Signature Subpacket Types 25 164 5.2.3.3. Notes on Self-Signatures 25 165 5.2.3.4. Signature creation time 26 166 5.2.3.5. Issuer 26 167 168Callas, et al. Expires Jan 08, 2006 [Page 3] 169 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 170 171 5.2.3.6. Key expiration time 27 172 5.2.3.7. Preferred symmetric algorithms 27 173 5.2.3.8. Preferred hash algorithms 27 174 5.2.3.9. Preferred compression algorithms 27 175 5.2.3.10.Signature expiration time 27 176 5.2.3.11.Exportable Certification 28 177 5.2.3.12.Revocable 28 178 5.2.3.13.Trust signature 28 179 5.2.3.14.Regular expression 29 180 5.2.3.15.Revocation key 29 181 5.2.3.16.Notation Data 29 182 5.2.3.17.Key server preferences 30 183 5.2.3.18.Preferred key server 30 184 5.2.3.19.Primary User ID 31 185 5.2.3.20.Policy URI 31 186 5.2.3.21.Key Flags 31 187 5.2.3.22.Signer's User ID 32 188 5.2.3.23.Reason for Revocation 32 189 5.2.3.24.Features 33 190 5.2.3.25.Signature Target 34 191 5.2.3.26.Embedded Signature 34 192 5.2.4. Computing Signatures 34 193 5.2.4.1. Subpacket Hints 35 194 5.3. Symmetric-Key Encrypted Session Key Packets (Tag 3) 36 195 5.4. One-Pass Signature Packets (Tag 4) 37 196 5.5. Key Material Packet 37 197 5.5.1. Key Packet Variants 37 198 5.5.1.1. Public Key Packet (Tag 6) 37 199 5.5.1.2. Public Subkey Packet (Tag 14) 38 200 5.5.1.3. Secret Key Packet (Tag 5) 38 201 5.5.1.4. Secret Subkey Packet (Tag 7) 38 202 5.5.2. Public Key Packet Formats 38 203 5.5.3. Secret Key Packet Formats 40 204 5.6. Compressed Data Packet (Tag 8) 41 205 5.7. Symmetrically Encrypted Data Packet (Tag 9) 42 206 5.8. Marker Packet (Obsolete Literal Packet) (Tag 10) 43 207 5.9. Literal Data Packet (Tag 11) 43 208 5.10. Trust Packet (Tag 12) 44 209 5.11. User ID Packet (Tag 13) 44 210 5.12. User Attribute Packet (Tag 17) 44 211 5.12.1. The Image Attribute Subpacket 45 212 5.13. Sym. Encrypted Integrity Protected Data Packet (Tag 18) 46 213 5.14. Modification Detection Code Packet (Tag 19) 47 214 6. Radix-64 Conversions 48 215 6.1. An Implementation of the CRC-24 in "C" 49 216 6.2. Forming ASCII Armor 49 217 6.3. Encoding Binary in Radix-64 51 218 6.4. Decoding Radix-64 52 219 6.5. Examples of Radix-64 53 220 6.6. Example of an ASCII Armored Message 53 221 7. Cleartext signature framework 54 222 7.1. Dash-Escaped Text 54 223 224Callas, et al. Expires Jan 08, 2006 [Page 4] 225 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 226 227 8. Regular Expressions 55 228 9. Constants 55 229 9.1. Public Key Algorithms 56 230 9.2. Symmetric Key Algorithms 56 231 9.3. Compression Algorithms 57 232 9.4. Hash Algorithms 57 233 10. Packet Composition 57 234 10.1. Transferable Public Keys 57 235 10.2. OpenPGP Messages 59 236 10.3. Detached Signatures 59 237 11. Enhanced Key Formats 60 238 11.1. Key Structures 60 239 11.2. Key IDs and Fingerprints 60 240 12. Notes on Algorithms 61 241 12.1. Symmetric Algorithm Preferences 61 242 12.2. Other Algorithm Preferences 62 243 12.2.1. Compression Preferences 62 244 12.2.2. Hash Algorithm Preferences 63 245 12.3. Plaintext 63 246 12.4. RSA 63 247 12.5. DSA 63 248 12.6. Elgamal 64 249 12.7. Reserved Algorithm Numbers 64 250 12.8. OpenPGP CFB mode 64 251 13. Security Considerations 65 252 14. Implementation Nits 68 253 15. Authors and Working Group Chair 69 254 16. References (Normative) 70 255 17. References (Non-Normative) 71 256 18. Full Copyright Statement 72 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280Callas, et al. Expires Jan 08, 2006 [Page 5] 281 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 282 2831. Introduction 284 285 This document provides information on the message-exchange packet 286 formats used by OpenPGP to provide encryption, decryption, signing, 287 and key management functions. It is a revision of RFC 2440, "OpenPGP 288 Message Format", which itself replaces RFC 1991, "PGP Message 289 Exchange Formats." 290 2911.1. Terms 292 293 * OpenPGP - This is a definition for security software that uses 294 PGP 5.x as a basis, formalized in RFC 2440 and this document. 295 296 * PGP - Pretty Good Privacy. PGP is a family of software systems 297 developed by Philip R. Zimmermann from which OpenPGP is based. 298 299 * PGP 2.6.x - This version of PGP has many variants, hence the 300 term PGP 2.6.x. It used only RSA, MD5, and IDEA for its 301 cryptographic transforms. An informational RFC, RFC 1991, was 302 written describing this version of PGP. 303 304 * PGP 5.x - This version of PGP is formerly known as "PGP 3" in 305 the community and also in the predecessor of this document, RFC 306 1991. It has new formats and corrects a number of problems in 307 the PGP 2.6.x design. It is referred to here as PGP 5.x because 308 that software was the first release of the "PGP 3" code base. 309 310 * GPG - GNU Privacy Guard, also called GnuPG. GPG is an OpenPGP 311 implementation that avoids all encumbered algorithms. 312 Consequently, early versions of GPG did not include RSA public 313 keys. GPG may or may not have (depending on version) support for 314 IDEA or other encumbered algorithms. 315 316 "PGP", "Pretty Good", and "Pretty Good Privacy" are trademarks of 317 PGP Corporation and are used with permission. 318 319 This document uses the terms "MUST", "SHOULD", and "MAY" as defined 320 in RFC 2119, along with the negated forms of those terms. 321 3222. General functions 323 324 OpenPGP provides data integrity services for messages and data files 325 by using these core technologies: 326 327 - digital signatures 328 329 - encryption 330 331 - compression 332 333 334 335 336Callas, et al. Expires Jan 08, 2006 [Page 6] 337 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 338 339 - radix-64 conversion 340 341 In addition, OpenPGP provides key management and certificate 342 services, but many of these are beyond the scope of this document. 343 3442.1. Confidentiality via Encryption 345 346 OpenPGP combines symmetric-key encryption and public key encryption 347 to provide confidentiality. When made confidential, first the object 348 is encrypted using a symmetric encryption algorithm. Each symmetric 349 key is used only once, for a single object. A new "session key" is 350 generated as a random number for each object (sometimes referred to 351 as a session). Since it is used only once, the session key is bound 352 to the message and transmitted with it. To protect the key, it is 353 encrypted with the receiver's public key. The sequence is as 354 follows: 355 356 1. The sender creates a message. 357 358 2. The sending OpenPGP generates a random number to be used as a 359 session key for this message only. 360 361 3. The session key is encrypted using each recipient's public key. 362 These "encrypted session keys" start the message. 363 364 4. The sending OpenPGP encrypts the message using the session key, 365 which forms the remainder of the message. Note that the message 366 is also usually compressed. 367 368 5. The receiving OpenPGP decrypts the session key using the 369 recipient's private key. 370 371 6. The receiving OpenPGP decrypts the message using the session 372 key. If the message was compressed, it will be decompressed. 373 374 With symmetric-key encryption, an object may be encrypted with a 375 symmetric key derived from a passphrase (or other shared secret), or 376 a two-stage mechanism similar to the public-key method described 377 above in which a session key is itself encrypted with a symmetric 378 algorithm keyed from a shared secret. 379 380 Both digital signature and confidentiality services may be applied 381 to the same message. First, a signature is generated for the message 382 and attached to the message. Then, the message plus signature is 383 encrypted using a symmetric session key. Finally, the session key is 384 encrypted using public-key encryption and prefixed to the encrypted 385 block. 386 3872.2. Authentication via Digital signature 388 389 The digital signature uses a hash code or message digest algorithm, 390 and a public-key signature algorithm. The sequence is as follows: 391 392Callas, et al. Expires Jan 08, 2006 [Page 7] 393 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 394 395 1. The sender creates a message. 396 397 2. The sending software generates a hash code of the message. 398 399 3. The sending software generates a signature from the hash code 400 using the sender's private key. 401 402 4. The binary signature is attached to the message. 403 404 5. The receiving software keeps a copy of the message signature. 405 406 6. The receiving software generates a new hash code for the 407 received message and verifies it using the message's signature. 408 If the verification is successful, the message is accepted as 409 authentic. 410 4112.3. Compression 412 413 OpenPGP implementations SHOULD compress the message after applying 414 the signature but before encryption. 415 416 If an implementation does not implement compression, its authors 417 should be aware that most OpenPGP messages in the world are 418 compressed. Thus, it may even be wise for a space-constrained 419 implementation to implement decompression, but not compression. 420 421 Furthermore, compression has the added side-effect that some types 422 of attacks can be thwarted by the fact that slightly altered, 423 compressed data rarely uncompresses without severe errors. This is 424 hardly rigorous, but it is operationally useful. These attacks can 425 be rigorously prevented by implementing and using Modification 426 Detection Codes as described in sections following. 427 4282.4. Conversion to Radix-64 429 430 OpenPGP's underlying native representation for encrypted messages, 431 signature certificates, and keys is a stream of arbitrary octets. 432 Some systems only permit the use of blocks consisting of seven-bit, 433 printable text. For transporting OpenPGP's native raw binary octets 434 through channels that are not safe to raw binary data, a printable 435 encoding of these binary octets is needed. OpenPGP provides the 436 service of converting the raw 8-bit binary octet stream to a stream 437 of printable ASCII characters, called Radix-64 encoding or ASCII 438 Armor. 439 440 Implementations SHOULD provide Radix-64 conversions. 441 4422.5. Signature-Only Applications 443 444 OpenPGP is designed for applications that use both encryption and 445 signatures, but there are a number of problems that are solved by a 446 signature-only implementation. Although this specification requires 447 448Callas, et al. Expires Jan 08, 2006 [Page 8] 449 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 450 451 both encryption and signatures, it is reasonable for there to be 452 subset implementations that are non-conformant only in that they 453 omit encryption. 454 4553. Data Element Formats 456 457 This section describes the data elements used by OpenPGP. 458 4593.1. Scalar numbers 460 461 Scalar numbers are unsigned, and are always stored in big-endian 462 format. Using n[k] to refer to the kth octet being interpreted, the 463 value of a two-octet scalar is ((n[0] << 8) + n[1]). The value of a 464 four-octet scalar is ((n[0] << 24) + (n[1] << 16) + (n[2] << 8) + 465 n[3]). 466 4673.2. Multiprecision Integers 468 469 Multiprecision Integers (also called MPIs) are unsigned integers 470 used to hold large integers such as the ones used in cryptographic 471 calculations. 472 473 An MPI consists of two pieces: a two-octet scalar that is the length 474 of the MPI in bits followed by a string of octets that contain the 475 actual integer. 476 477 These octets form a big-endian number; a big-endian number can be 478 made into an MPI by prefixing it with the appropriate length. 479 480 Examples: 481 482 (all numbers are in hexadecimal) 483 484 The string of octets [00 01 01] forms an MPI with the value 1. The 485 string [00 09 01 FF] forms an MPI with the value of 511. 486 487 Additional rules: 488 489 The size of an MPI is ((MPI.length + 7) / 8) + 2 octets. 490 491 The length field of an MPI describes the length starting from its 492 most significant non-zero bit. Thus, the MPI [00 02 01] is not 493 formed correctly. It should be [00 01 01]. 494 495 Unused bits of an MPI MUST be zero. 496 497 Also note that when an MPI is encrypted, the length refers to the 498 plaintext MPI. It may be ill-formed in its ciphertext. 499 5003.3. Key IDs 501 502 A Key ID is an eight-octet scalar that identifies a key. 503 504Callas, et al. Expires Jan 08, 2006 [Page 9] 505 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 506 507 Implementations SHOULD NOT assume that Key IDs are unique. The 508 section, "Enhanced Key Formats" below describes how Key IDs are 509 formed. 510 5113.4. Text 512 513 Unless otherwise specified, the character set for text is the UTF-8 514 [RFC2279] encoding of Unicode [ISO10646]. 515 5163.5. Time fields 517 518 A time field is an unsigned four-octet number containing the number 519 of seconds elapsed since midnight, 1 January 1970 UTC. 520 5213.6. Keyrings 522 523 A keyring is a collection of one or more keys in a file or database. 524 Traditionally, a keyring is simply a sequential list of keys, but 525 may be any suitable database. It is beyond the scope of this 526 standard to discuss the details of keyrings or other databases. 527 5283.7. String-to-key (S2K) specifiers 529 530 String-to-key (S2K) specifiers are used to convert passphrase 531 strings into symmetric-key encryption/decryption keys. They are 532 used in two places, currently: to encrypt the secret part of private 533 keys in the private keyring, and to convert passphrases to 534 encryption keys for symmetrically encrypted messages. 535 5363.7.1. String-to-key (S2K) specifier types 537 538 There are three types of S2K specifiers currently supported, and 539 some reserved values: 540 541 ID S2K Type 542 -- --- ---- 543 0 Simple S2K 544 1 Salted S2K 545 2 Illegal value 546 3 Iterated and Salted S2K 547 100 to 110 Private/Experimental S2K 548 549 These are described as follows: 550 5513.7.1.1. Simple S2K 552 553 This directly hashes the string to produce the key data. See below 554 for how this hashing is done. 555 556 Octet 0: 0x00 557 Octet 1: hash algorithm 558 559 560Callas, et al. Expires Jan 08, 2006 [Page 10] 561 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 562 563 Simple S2K hashes the passphrase to produce the session key. The 564 manner in which this is done depends on the size of the session key 565 (which will depend on the cipher used) and the size of the hash 566 algorithm's output. If the hash size is greater than the session key 567 size, the high-order (leftmost) octets of the hash are used as the 568 key. 569 570 If the hash size is less than the key size, multiple instances of 571 the hash context are created -- enough to produce the required key 572 data. These instances are preloaded with 0, 1, 2, ... octets of 573 zeros (that is to say, the first instance has no preloading, the 574 second gets preloaded with 1 octet of zero, the third is preloaded 575 with two octets of zeros, and so forth). 576 577 As the data is hashed, it is given independently to each hash 578 context. Since the contexts have been initialized differently, they 579 will each produce different hash output. Once the passphrase is 580 hashed, the output data from the multiple hashes is concatenated, 581 first hash leftmost, to produce the key data, with any excess octets 582 on the right discarded. 583 5843.7.1.2. Salted S2K 585 586 This includes a "salt" value in the S2K specifier -- some arbitrary 587 data -- that gets hashed along with the passphrase string, to help 588 prevent dictionary attacks. 589 590 Octet 0: 0x01 591 Octet 1: hash algorithm 592 Octets 2-9: 8-octet salt value 593 594 Salted S2K is exactly like Simple S2K, except that the input to the 595 hash function(s) consists of the 8 octets of salt from the S2K 596 specifier, followed by the passphrase. 597 5983.7.1.3. Iterated and Salted S2K 599 600 This includes both a salt and an octet count. The salt is combined 601 with the passphrase and the resulting value is hashed repeatedly. 602 This further increases the amount of work an attacker must do to try 603 dictionary attacks. 604 605 Octet 0: 0x03 606 Octet 1: hash algorithm 607 Octets 2-9: 8-octet salt value 608 Octet 10: count, a one-octet, coded value 609 610 The count is coded into a one-octet number using the following 611 formula: 612 613 614 615 616Callas, et al. Expires Jan 08, 2006 [Page 11] 617 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 618 619 #define EXPBIAS 6 620 count = ((Int32)16 + (c & 15)) << ((c >> 4) + EXPBIAS); 621 622 The above formula is in C, where "Int32" is a type for a 32-bit 623 integer, and the variable "c" is the coded count, Octet 10. 624 625 Iterated-Salted S2K hashes the passphrase and salt data multiple 626 times. The total number of octets to be hashed is specified in the 627 encoded count in the S2K specifier. Note that the resulting count 628 value is an octet count of how many octets will be hashed, not an 629 iteration count. 630 631 Initially, one or more hash contexts are set up as with the other 632 S2K algorithms, depending on how many octets of key data are needed. 633 Then the salt, followed by the passphrase data is repeatedly hashed 634 until the number of octets specified by the octet count has been 635 hashed. The one exception is that if the octet count is less than 636 the size of the salt plus passphrase, the full salt plus passphrase 637 will be hashed even though that is greater than the octet count. 638 After the hashing is done the data is unloaded from the hash 639 context(s) as with the other S2K algorithms. 640 6413.7.2. String-to-key usage 642 643 Implementations SHOULD use salted or iterated-and-salted S2K 644 specifiers, as simple S2K specifiers are more vulnerable to 645 dictionary attacks. 646 6473.7.2.1. Secret key encryption 648 649 An S2K specifier can be stored in the secret keyring to specify how 650 to convert the passphrase to a key that unlocks the secret data. 651 Older versions of PGP just stored a cipher algorithm octet preceding 652 the secret data or a zero to indicate that the secret data was 653 unencrypted. The MD5 hash function was always used to convert the 654 passphrase to a key for the specified cipher algorithm. 655 656 For compatibility, when an S2K specifier is used, the special value 657 255 is stored in the position where the hash algorithm octet would 658 have been in the old data structure. This is then followed 659 immediately by a one-octet algorithm identifier, and then by the S2K 660 specifier as encoded above. 661 662 Therefore, preceding the secret data there will be one of these 663 possibilities: 664 665 0: secret data is unencrypted (no pass phrase) 666 255 or 254: followed by algorithm octet and S2K specifier 667 Cipher alg: use Simple S2K algorithm using MD5 hash 668 669 670 671 672Callas, et al. Expires Jan 08, 2006 [Page 12] 673 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 674 675 This last possibility, the cipher algorithm number with an implicit 676 use of MD5 and IDEA, is provided for backward compatibility; it MAY 677 be understood, but SHOULD NOT be generated, and is deprecated. 678 679 These are followed by an Initial Vector of the same length as the 680 block size of the cipher for the decryption of the secret values, if 681 they are encrypted, and then the secret key values themselves. 682 6833.7.2.2. Symmetric-key message encryption 684 685 OpenPGP can create a Symmetric-key Encrypted Session Key (ESK) 686 packet at the front of a message. This is used to allow S2K 687 specifiers to be used for the passphrase conversion or to create 688 messages with a mix of symmetric-key ESKs and public-key ESKs. This 689 allows a message to be decrypted either with a passphrase or a 690 public key pair. 691 692 PGP 2.X always used IDEA with Simple string-to-key conversion when 693 encrypting a message with a symmetric algorithm. This is deprecated, 694 but MAY be used for backward-compatibility. 695 6964. Packet Syntax 697 698 This section describes the packets used by OpenPGP. 699 7004.1. Overview 701 702 An OpenPGP message is constructed from a number of records that are 703 traditionally called packets. A packet is a chunk of data that has a 704 tag specifying its meaning. An OpenPGP message, keyring, 705 certificate, and so forth consists of a number of packets. Some of 706 those packets may contain other OpenPGP packets (for example, a 707 compressed data packet, when uncompressed, contains OpenPGP 708 packets). 709 710 Each packet consists of a packet header, followed by the packet 711 body. The packet header is of variable length. 712 7134.2. Packet Headers 714 715 The first octet of the packet header is called the "Packet Tag." It 716 determines the format of the header and denotes the packet contents. 717 The remainder of the packet header is the length of the packet. 718 719 Note that the most significant bit is the left-most bit, called bit 720 7. A mask for this bit is 0x80 in hexadecimal. 721 722 +---------------+ 723 PTag |7 6 5 4 3 2 1 0| 724 +---------------+ 725 Bit 7 -- Always one 726 Bit 6 -- New packet format if set 727 728Callas, et al. Expires Jan 08, 2006 [Page 13] 729 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 730 731 PGP 2.6.x only uses old format packets. Thus, software that 732 interoperates with those versions of PGP must only use old format 733 packets. If interoperability is not an issue, the new packet format 734 is preferred. Note that old format packets have four bits of packet 735 tags, and new format packets have six; some features cannot be used 736 and still be backward-compatible. 737 738 Also note that packets with a tag greater than or equal to 16 MUST 739 use new format packets. The old format packets can only express tags 740 less than or equal to 15. 741 742 Old format packets contain: 743 744 Bits 5-2 -- packet tag 745 Bits 1-0 - length-type 746 747 New format packets contain: 748 749 Bits 5-0 -- packet tag 750 7514.2.1. Old-Format Packet Lengths 752 753 The meaning of the length-type in old-format packets is: 754 755 0 - The packet has a one-octet length. The header is 2 octets long. 756 757 1 - The packet has a two-octet length. The header is 3 octets long. 758 759 2 - The packet has a four-octet length. The header is 5 octets long. 760 761 3 - The packet is of indeterminate length. The header is 1 octet 762 long, and the implementation must determine how long the packet 763 is. If the packet is in a file, this means that the packet 764 extends until the end of the file. In general, an implementation 765 SHOULD NOT use indeterminate length packets except where the end 766 of the data will be clear from the context, and even then it is 767 better to use a definite length, or a new-format header. The 768 new-format headers described below have a mechanism for 769 precisely encoding data of indeterminate length. 770 7714.2.2. New-Format Packet Lengths 772 773 New format packets have four possible ways of encoding length: 774 775 1. A one-octet Body Length header encodes packet lengths of up to 776 191 octets. 777 778 2. A two-octet Body Length header encodes packet lengths of 192 to 779 8383 octets. 780 781 782 783 784Callas, et al. Expires Jan 08, 2006 [Page 14] 785 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 786 787 3. A five-octet Body Length header encodes packet lengths of up to 788 4,294,967,295 (0xFFFFFFFF) octets in length. (This actually 789 encodes a four-octet scalar number.) 790 791 4. When the length of the packet body is not known in advance by 792 the issuer, Partial Body Length headers encode a packet of 793 indeterminate length, effectively making it a stream. 794 7954.2.2.1. One-Octet Lengths 796 797 A one-octet Body Length header encodes a length of from 0 to 191 798 octets. This type of length header is recognized because the one 799 octet value is less than 192. The body length is equal to: 800 801 bodyLen = 1st_octet; 802 8034.2.2.2. Two-Octet Lengths 804 805 A two-octet Body Length header encodes a length of from 192 to 8383 806 octets. It is recognized because its first octet is in the range 807 192 to 223. The body length is equal to: 808 809 bodyLen = ((1st_octet - 192) << 8) + (2nd_octet) + 192 810 8114.2.2.3. Five-Octet Lengths 812 813 A five-octet Body Length header consists of a single octet holding 814 the value 255, followed by a four-octet scalar. The body length is 815 equal to: 816 817 bodyLen = (2nd_octet << 24) | (3rd_octet << 16) | 818 (4th_octet << 8) | 5th_octet 819 820 This basic set of one, two, and five-octet lengths is also used 821 internally to some packets. 822 8234.2.2.4. Partial Body Lengths 824 825 A Partial Body Length header is one octet long and encodes the 826 length of only part of the data packet. This length is a power of 2, 827 from 1 to 1,073,741,824 (2 to the 30th power). It is recognized by 828 its one octet value that is greater than or equal to 224, and less 829 than 255. The partial body length is equal to: 830 831 partialBodyLen = 1 << (1st_octet & 0x1f); 832 833 Each Partial Body Length header is followed by a portion of the 834 packet body data. The Partial Body Length header specifies this 835 portion's length. Another length header (one octet, two-octet, 836 five-octet, or partial) follows that portion. The last length header 837 in the packet MUST NOT be a partial Body Length header. Partial 838 Body Length headers may only be used for the non-final parts of the 839 840Callas, et al. Expires Jan 08, 2006 [Page 15] 841 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 842 843 packet. 844 845 It might also be encoded in the following octet stream: 0xEF, first 846 32768 octets of data; 0xE1, next two octets of data; 0xE0, next one 847 octet of data; 0xF0, next 65536 octets of data; 0xC5, 0xDD, last 848 1693 octets of data. This is just one possible encoding, and many 849 variations are possible on the size of the Partial Body Length 850 headers, as long as a regular Body Length header encodes the last 851 portion of the data. 852 853 Note also that the last Body Length header can be a zero-length 854 header. 855 856 An implementation MAY use Partial Body Lengths for data packets, be 857 they literal, compressed, or encrypted. The first partial length 858 MUST be at least 512 octets long. Partial Body Lengths MUST NOT be 859 used for any other packet types. 860 8614.2.3. Packet Length Examples 862 863 These examples show ways that new-format packets might encode the 864 packet lengths. 865 866 A packet with length 100 may have its length encoded in one octet: 867 0x64. This is followed by 100 octets of data. 868 869 A packet with length 1723 may have its length coded in two octets: 870 0xC5, 0xFB. This header is followed by the 1723 octets of data. 871 872 A packet with length 100000 may have its length encoded in five 873 octets: 0xFF, 0x00, 0x01, 0x86, 0xA0. 874 875 Please note that in all of these explanations, the total length of 876 the packet is the length of the header(s) plus the length of the 877 body. 878 8794.3. Packet Tags 880 881 The packet tag denotes what type of packet the body holds. Note that 882 old format headers can only have tags less than 16, whereas new 883 format headers can have tags as great as 63. The defined tags (in 884 decimal) are: 885 886 0 -- Reserved - a packet tag must not have this value 887 1 -- Public-Key Encrypted Session Key Packet 888 2 -- Signature Packet 889 3 -- Symmetric-Key Encrypted Session Key Packet 890 4 -- One-Pass Signature Packet 891 5 -- Secret Key Packet 892 6 -- Public Key Packet 893 7 -- Secret Subkey Packet 894 8 -- Compressed Data Packet 895 896Callas, et al. Expires Jan 08, 2006 [Page 16] 897 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 898 899 9 -- Symmetrically Encrypted Data Packet 900 10 -- Marker Packet 901 11 -- Literal Data Packet 902 12 -- Trust Packet 903 13 -- User ID Packet 904 14 -- Public Subkey Packet 905 17 -- User Attribute Packet 906 18 -- Sym. Encrypted and Integrity Protected Data Packet 907 19 -- Modification Detection Code Packet 908 60 to 63 -- Private or Experimental Values 909 9105. Packet Types 911 9125.1. Public-Key Encrypted Session Key Packets (Tag 1) 913 914 A Public-Key Encrypted Session Key packet holds the session key used 915 to encrypt a message. Zero or more Encrypted Session Key packets 916 (either Public-Key or Symmetric-Key) may precede a Symmetrically 917 Encrypted Data Packet, which holds an encrypted message. The 918 message is encrypted with the session key, and the session key is 919 itself encrypted and stored in the Encrypted Session Key packet(s). 920 The Symmetrically Encrypted Data Packet is preceded by one 921 Public-Key Encrypted Session Key packet for each OpenPGP key to 922 which the message is encrypted. The recipient of the message finds 923 a session key that is encrypted to their public key, decrypts the 924 session key, and then uses the session key to decrypt the message. 925 926 The body of this packet consists of: 927 928 - A one-octet number giving the version number of the packet type. 929 The currently defined value for packet version is 3. 930 931 - An eight-octet number that gives the key ID of the public key 932 that the session key is encrypted to. If the session key is 933 encrypted to a subkey then the key ID of this subkey is used 934 here instead of the key ID of the primary key. 935 936 - A one-octet number giving the public key algorithm used. 937 938 - A string of octets that is the encrypted session key. This 939 string takes up the remainder of the packet, and its contents 940 are dependent on the public key algorithm used. 941 942 Algorithm Specific Fields for RSA encryption 943 944 - multiprecision integer (MPI) of RSA encrypted value m**e mod n. 945 946 Algorithm Specific Fields for Elgamal encryption: 947 948 - MPI of Elgamal (Diffie-Hellman) value g**k mod p. 949 950 951 952Callas, et al. Expires Jan 08, 2006 [Page 17] 953 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 954 955 - MPI of Elgamal (Diffie-Hellman) value m * y**k mod p. 956 957 The value "m" in the above formulas is derived from the session key 958 as follows. First the session key is prefixed with a one-octet 959 algorithm identifier that specifies the symmetric encryption 960 algorithm used to encrypt the following Symmetrically Encrypted Data 961 Packet. Then a two-octet checksum is appended which is equal to the 962 sum of the preceding session key octets, not including the algorithm 963 identifier, modulo 65536. This value is then encoded as described 964 in PKCS-1 block encoding EME-PKCS1-v1_5 [RFC2437] to form the "m" 965 value used in the formulas above. 966 967 Note that when an implementation forms several PKESKs with one 968 session key, forming a message that can be decrypted by several 969 keys, the implementation MUST make new PKCS-1 encoding for each key. 970 971 An implementation MAY accept or use a Key ID of zero as a "wild 972 card" or "speculative" Key ID. In this case, the receiving 973 implementation would try all available private keys, checking for a 974 valid decrypted session key. This format helps reduce traffic 975 analysis of messages. 976 9775.2. Signature Packet (Tag 2) 978 979 A signature packet describes a binding between some public key and 980 some data. The most common signatures are a signature of a file or a 981 block of text, and a signature that is a certification of a User ID. 982 983 Two versions of signature packets are defined. Version 3 provides 984 basic signature information, while version 4 provides an expandable 985 format with subpackets that can specify more information about the 986 signature. PGP 2.6.x only accepts version 3 signatures. 987 988 Implementations SHOULD accept V3 signatures. Implementations SHOULD 989 generate V4 signatures. 990 991 Note that if an implementation is creating an encrypted and signed 992 message that is encrypted to a V3 key, it is reasonable to create a 993 V3 signature. 994 9955.2.1. Signature Types 996 997 There are a number of possible meanings for a signature, which are 998 specified in a signature type octet in any given signature. These 999 meanings are: 1000 1001 0x00: Signature of a binary document. 1002 This means the signer owns it, created it, or certifies that it 1003 has not been modified. 1004 1005 1006 1007 1008Callas, et al. Expires Jan 08, 2006 [Page 18] 1009 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1010 1011 0x01: Signature of a canonical text document. 1012 This means the signer owns it, created it, or certifies that it 1013 has not been modified. The signature is calculated over the 1014 text data with its line endings converted to <CR><LF>. 1015 1016 0x02: Standalone signature. 1017 This signature is a signature of only its own subpacket 1018 contents. It is calculated identically to a signature over a 1019 zero-length binary document. Note that it doesn't make sense to 1020 have a V3 standalone signature. 1021 1022 0x10: Generic certification of a User ID and Public Key packet. 1023 The issuer of this certification does not make any particular 1024 assertion as to how well the certifier has checked that the 1025 owner of the key is in fact the person described by the User ID. 1026 1027 0x11: Persona certification of a User ID and Public Key packet. 1028 The issuer of this certification has not done any verification 1029 of the claim that the owner of this key is the User ID 1030 specified. 1031 1032 0x12: Casual certification of a User ID and Public Key packet. 1033 The issuer of this certification has done some casual 1034 verification of the claim of identity. 1035 1036 0x13: Positive certification of a User ID and Public Key packet. 1037 The issuer of this certification has done substantial 1038 verification of the claim of identity. 1039 1040 Please note that the vagueness of these certification claims is 1041 not a flaw, but a feature of the system. Because OpenPGP places 1042 final authority for validity upon the receiver of a 1043 certification, it may be that one authority's casual 1044 certification might be more rigorous than some other authority's 1045 positive certification. These classifications allow a 1046 certification authority to issue fine-grained claims. 1047 1048 Most OpenPGP implementations make their "key signatures" as 0x10 1049 certifications. Some implementations can issue 0x11-0x13 1050 certifications, but few differentiate between the types. 1051 1052 0x18: Subkey Binding Signature 1053 This signature is a statement by the top-level signing key that 1054 indicates that it owns the subkey. This signature is calculated 1055 directly on the subkey itself, not on any User ID or other 1056 packets. A signature that binds a signing subkey also has an 1057 embedded signature subpacket in this binding signature which 1058 contains a 0x19 signature made by the signing subkey on the 1059 primary key. 1060 1061 1062 1063 1064Callas, et al. Expires Jan 08, 2006 [Page 19] 1065 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1066 1067 0x19 Primary Key Binding Signature 1068 This signature is a statement by a signing subkey, indicating 1069 that it is owned by the primary key. This signature is 1070 calculated directly on the primary key itself, and not on any 1071 User ID or other packets. 1072 1073 0x1F: Signature directly on a key 1074 This signature is calculated directly on a key. It binds the 1075 information in the signature subpackets to the key, and is 1076 appropriate to be used for subpackets that provide information 1077 about the key, such as the revocation key subpacket. It is also 1078 appropriate for statements that non-self certifiers want to make 1079 about the key itself, rather than the binding between a key and 1080 a name. 1081 1082 0x20: Key revocation signature 1083 The signature is calculated directly on the key being revoked. 1084 A revoked key is not to be used. Only revocation signatures by 1085 the key being revoked, or by an authorized revocation key, 1086 should be considered valid revocation signatures. 1087 1088 0x28: Subkey revocation signature 1089 The signature is calculated directly on the subkey being 1090 revoked. A revoked subkey is not to be used. Only revocation 1091 signatures by the top-level signature key that is bound to this 1092 subkey, or by an authorized revocation key, should be considered 1093 valid revocation signatures. 1094 1095 0x30: Certification revocation signature 1096 This signature revokes an earlier User ID certification 1097 signature (signature class 0x10 through 0x13) or direct-key 1098 signature (0x1F). It should be issued by the same key that 1099 issued the revoked signature or an authorized revocation key. 1100 The signature should have a later creation date than the 1101 signature it revokes. 1102 1103 0x40: Timestamp signature. 1104 This signature is only meaningful for the timestamp contained in 1105 it. 1106 1107 0x50: Third-Party Confirmation signature. 1108 This signature is a signature over some other OpenPGP signature 1109 packet(s). It is analogous to a notary seal on the signed data. 1110 A third-party signature SHOULD include Signature Target 1111 subpacket(s) to give easy identification. Note that we really do 1112 mean SHOULD. There are plausible uses for this (such as a blind 1113 party that only sees the signature, not the key nor source 1114 document) that cannot include a target subpacket. 1115 11165.2.2. Version 3 Signature Packet Format 1117 1118 The body of a version 3 Signature Packet contains: 1119 1120Callas, et al. Expires Jan 08, 2006 [Page 20] 1121 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1122 1123 - One-octet version number (3). 1124 1125 - One-octet length of following hashed material. MUST be 5. 1126 1127 - One-octet signature type. 1128 1129 - Four-octet creation time. 1130 1131 - Eight-octet key ID of signer. 1132 1133 - One-octet public key algorithm. 1134 1135 - One-octet hash algorithm. 1136 1137 - Two-octet field holding left 16 bits of signed hash value. 1138 1139 - One or more multiprecision integers comprising the signature. 1140 This portion is algorithm specific, as described below. 1141 1142 The concatenation of the data to be signed, the signature type and 1143 creation time from the signature packet (5 additional octets) is 1144 hashed. The resulting hash value is used in the signature algorithm. 1145 The high 16 bits (first two octets) of the hash are included in the 1146 signature packet to provide a quick test to reject some invalid 1147 signatures. 1148 1149 Algorithm Specific Fields for RSA signatures: 1150 1151 - multiprecision integer (MPI) of RSA signature value m**d mod n. 1152 1153 Algorithm Specific Fields for DSA signatures: 1154 1155 - MPI of DSA value r. 1156 1157 - MPI of DSA value s. 1158 1159 The signature calculation is based on a hash of the signed data, as 1160 described above. The details of the calculation are different for 1161 DSA signature than for RSA signatures. 1162 1163 The hash h is PKCS-1 padded exactly the same way as for the above 1164 described RSA signatures. 1165 1166 With RSA signatures, the hash value is encoded as described in 1167 PKCS-1 section 9.2.1 encoded using PKCS-1 encoding type 1168 EMSA-PKCS1-v1_5 [RFC2437]. This requires inserting the hash value 1169 as an octet string into an ASN.1 structure. The object identifier 1170 for the type of hash being used is included in the structure. The 1171 hexadecimal representations for the currently defined hash 1172 algorithms are: 1173 1174 1175 1176Callas, et al. Expires Jan 08, 2006 [Page 21] 1177 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1178 1179 - MD5: 0x2A, 0x86, 0x48, 0x86, 0xF7, 0x0D, 0x02, 0x05 1180 1181 - RIPEMD-160: 0x2B, 0x24, 0x03, 0x02, 0x01 1182 1183 - SHA-1: 0x2B, 0x0E, 0x03, 0x02, 0x1A 1184 1185 - SHA256: 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01 1186 1187 - SHA384: 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x02 1188 1189 - SHA512: 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x03 1190 1191 The ASN.1 OIDs are: 1192 1193 - MD5: 1.2.840.113549.2.5 1194 1195 - RIPEMD-160: 1.3.36.3.2.1 1196 1197 - SHA-1: 1.3.14.3.2.26 1198 1199 - SHA256: 2.16.840.1.101.3.4.2.1 1200 1201 - SHA384: 2.16.840.1.101.3.4.2.2 1202 1203 - SHA512: 2.16.840.1.101.3.4.2.3 1204 1205 The full hash prefixes for these are: 1206 1207 MD5: 0x30, 0x20, 0x30, 0x0C, 0x06, 0x08, 0x2A, 0x86, 1208 0x48, 0x86, 0xF7, 0x0D, 0x02, 0x05, 0x05, 0x00, 1209 0x04, 0x10 1210 1211 RIPEMD-160: 0x30, 0x21, 0x30, 0x09, 0x06, 0x05, 0x2B, 0x24, 1212 0x03, 0x02, 0x01, 0x05, 0x00, 0x04, 0x14 1213 1214 SHA-1: 0x30, 0x21, 0x30, 0x09, 0x06, 0x05, 0x2b, 0x0E, 1215 0x03, 0x02, 0x1A, 0x05, 0x00, 0x04, 0x14 1216 1217 SHA256: 0x30, 0x31, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 1218 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01, 0x05, 1219 0x00, 0x04, 0x20 1220 1221 SHA384: 0x30, 0x41, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 1222 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x02, 0x05, 1223 0x00, 0x04, 0x30 1224 1225 SHA512: 0x30, 0x51, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 1226 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x03, 0x05, 1227 0x00, 0x04, 0x40 1228 1229 1230 1231 1232Callas, et al. Expires Jan 08, 2006 [Page 22] 1233 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1234 1235 DSA signatures MUST use hashes with a size of 160 bits, to match q, 1236 the size of the group generated by the DSA key's generator value. 1237 The hash function result is treated as a 160 bit number and used 1238 directly in the DSA signature algorithm. 1239 12405.2.3. Version 4 Signature Packet Format 1241 1242 The body of a version 4 Signature Packet contains: 1243 1244 - One-octet version number (4). 1245 1246 - One-octet signature type. 1247 1248 - One-octet public key algorithm. 1249 1250 - One-octet hash algorithm. 1251 1252 - Hashed subpacket data set. (zero or more subpackets) 1253 1254 - Two-octet scalar octet count for the following unhashed 1255 subpacket data. Note that this is the length in octets of all of 1256 the unhashed subpackets; a pointer incremented by this number 1257 will skip over the unhashed subpackets. 1258 1259 - Unhashed subpacket data set. (zero or more subpackets) 1260 1261 - Two-octet field holding the left 16 bits of the signed hash 1262 value. 1263 1264 - One or more multiprecision integers comprising the signature. 1265 This portion is algorithm specific, as described above. 1266 1267 The data being signed is hashed, and then the signature data from 1268 the version number through the hashed subpacket data (inclusive) is 1269 hashed. The resulting hash value is what is signed. The left 16 1270 bits of the hash are included in the signature packet to provide a 1271 quick test to reject some invalid signatures. 1272 1273 There are two fields consisting of signature subpackets. The first 1274 field is hashed with the rest of the signature data, while the 1275 second is unhashed. The second set of subpackets is not 1276 cryptographically protected by the signature and should include only 1277 advisory information. 1278 1279 The algorithms for converting the hash function result to a 1280 signature are described in a section below. 1281 12825.2.3.1. Signature Subpacket Specification 1283 1284 A subpacket data set consists of zero or more signature subpackets, 1285 preceded by a two-octet scalar count of the length in octets of all 1286 the subpackets; a pointer incremented by this number will skip over 1287 1288Callas, et al. Expires Jan 08, 2006 [Page 23] 1289 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1290 1291 the subpacket data set. 1292 1293 Each subpacket consists of a subpacket header and a body. The 1294 header consists of: 1295 1296 - the subpacket length (1, 2, or 5 octets) 1297 1298 - the subpacket type (1 octet) 1299 1300 and is followed by the subpacket specific data. 1301 1302 The length includes the type octet but not this length. Its format 1303 is similar to the "new" format packet header lengths, but cannot 1304 have partial body lengths. That is: 1305 1306 if the 1st octet < 192, then 1307 lengthOfLength = 1 1308 subpacketLen = 1st_octet 1309 1310 if the 1st octet >= 192 and < 255, then 1311 lengthOfLength = 2 1312 subpacketLen = ((1st_octet - 192) << 8) + (2nd_octet) + 192 1313 1314 if the 1st octet = 255, then 1315 lengthOfLength = 5 1316 subpacket length = [four-octet scalar starting at 2nd_octet] 1317 1318 The value of the subpacket type octet may be: 1319 1320 2 = signature creation time 1321 3 = signature expiration time 1322 4 = exportable certification 1323 5 = trust signature 1324 6 = regular expression 1325 7 = revocable 1326 9 = key expiration time 1327 10 = placeholder for backward compatibility 1328 11 = preferred symmetric algorithms 1329 12 = revocation key 1330 16 = issuer key ID 1331 20 = notation data 1332 21 = preferred hash algorithms 1333 22 = preferred compression algorithms 1334 23 = key server preferences 1335 24 = preferred key server 1336 25 = primary User ID 1337 26 = policy URI 1338 27 = key flags 1339 28 = signer's User ID 1340 29 = reason for revocation 1341 30 = features 1342 31 = signature target 1343 1344Callas, et al. Expires Jan 08, 2006 [Page 24] 1345 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1346 1347 32 = embedded signature 1348 1349 100 to 110 = internal or user-defined 1350 1351 An implementation SHOULD ignore any subpacket of a type that it does 1352 not recognize. 1353 1354 Bit 7 of the subpacket type is the "critical" bit. If set, it 1355 denotes that the subpacket is one that is critical for the evaluator 1356 of the signature to recognize. If a subpacket is encountered that 1357 is marked critical but is unknown to the evaluating software, the 1358 evaluator SHOULD consider the signature to be in error. 1359 1360 An evaluator may "recognize" a subpacket, but not implement it. The 1361 purpose of the critical bit is to allow the signer to tell an 1362 evaluator that it would prefer a new, unknown feature to generate an 1363 error than be ignored. 1364 1365 Implementations SHOULD implement "preferences" and the "reason for 1366 revocation" subpackets. Note, however, that if an implementation 1367 chooses not to implement some of the preferences, it is required to 1368 behave in a polite manner to respect the wishes of those users who 1369 do implement these preferences. 1370 13715.2.3.2. Signature Subpacket Types 1372 1373 A number of subpackets are currently defined. Some subpackets apply 1374 to the signature itself and some are attributes of the key. 1375 Subpackets that are found on a self-signature are placed on a 1376 certification made by the key itself. Note that a key may have more 1377 than one User ID, and thus may have more than one self-signature, 1378 and differing subpackets. 1379 1380 A subpacket may be found either in the hashed or unhashed subpacket 1381 sections of a signature. If a subpacket is not hashed, then the 1382 information in it cannot be considered definitive because it is not 1383 part of the signature proper. 1384 13855.2.3.3. Notes on Self-Signatures 1386 1387 A self-signature is a binding signature made by the key the 1388 signature refers to. There are three types of self-signatures, the 1389 certification signatures (types 0x10-0x13), the direct-key signature 1390 (type 0x1f), and the subkey binding signature (type 0x18). For 1391 certification self-signatures, each User ID may have a 1392 self-signature, and thus different subpackets in those 1393 self-signatures. For subkey binding signatures, each subkey in fact 1394 has a self-signature. Subpackets that appear in a certification 1395 self-signature apply to the username, and subpackets that appear in 1396 the subkey self-signature apply to the subkey. Lastly, subpackets on 1397 the direct-key signature apply to the entire key. 1398 1399 1400Callas, et al. Expires Jan 08, 2006 [Page 25] 1401 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1402 1403 Implementing software should interpret a self-signature's preference 1404 subpackets as narrowly as possible. For example, suppose a key has 1405 two usernames, Alice and Bob. Suppose that Alice prefers the 1406 symmetric algorithm CAST5, and Bob prefers IDEA or TripleDES. If the 1407 software locates this key via Alice's name, then the preferred 1408 algorithm is CAST5, if software locates the key via Bob's name, then 1409 the preferred algorithm is IDEA. If the key is located by key ID, 1410 the algorithm of the primary User ID of the key provides the default 1411 symmetric algorithm. 1412 1413 Revoking a self-signature or allowing it to expire has a semantic 1414 meaning that varies with the signature type. Revoking the 1415 self-signature on a User ID effectively retires that user name. The 1416 self-signature is a statement, "My name X is tied to my signing key 1417 K" and is corroborated by other users' certifications. If another 1418 user revokes their certification, they are effectively saying that 1419 they no longer believe that name and that key are tied together. 1420 Similarly, if the user themselves revokes their self-signature, it 1421 means the user no longer goes by that name, no longer has that email 1422 address, etc. Revoking a binding signature effectively retires that 1423 subkey. Revoking a direct-key signature cancels that signature. 1424 Please see the "Reason for Revocation" subpacket below for more 1425 relevant detail. 1426 1427 Since a self-signature contains important information about the 1428 key's use, an implementation SHOULD allow the user to rewrite the 1429 self-signature, and important information in it, such as preferences 1430 and key expiration. 1431 1432 It is good practice to verify that a self-signature imported into an 1433 implementation doesn't advertise features that the implementation 1434 doesn't support, rewriting the signature as appropriate. 1435 1436 An implementation that encounters multiple self-signatures on the 1437 same object may resolve the ambiguity in any way it sees fit, but it 1438 is RECOMMENDED that priority be given to the most recent 1439 self-signature. 1440 14415.2.3.4. Signature creation time 1442 1443 (4 octet time field) 1444 1445 The time the signature was made. 1446 1447 MUST be present in the hashed area. 1448 14495.2.3.5. Issuer 1450 1451 (8 octet key ID) 1452 1453 1454 1455 1456Callas, et al. Expires Jan 08, 2006 [Page 26] 1457 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1458 1459 The OpenPGP key ID of the key issuing the signature. 1460 14615.2.3.6. Key expiration time 1462 1463 (4 octet time field) 1464 1465 The validity period of the key. This is the number of seconds after 1466 the key creation time that the key expires. If this is not present 1467 or has a value of zero, the key never expires. This is found only on 1468 a self-signature. 1469 14705.2.3.7. Preferred symmetric algorithms 1471 1472 (array of one-octet values) 1473 1474 Symmetric algorithm numbers that indicate which algorithms the key 1475 holder prefers to use. The subpacket body is an ordered list of 1476 octets with the most preferred listed first. It is assumed that only 1477 algorithms listed are supported by the recipient's software. 1478 Algorithm numbers in section 9. This is only found on a 1479 self-signature. 1480 14815.2.3.8. Preferred hash algorithms 1482 1483 (array of one-octet values) 1484 1485 Message digest algorithm numbers that indicate which algorithms the 1486 key holder prefers to receive. Like the preferred symmetric 1487 algorithms, the list is ordered. Algorithm numbers are in section 9. 1488 This is only found on a self-signature. 1489 14905.2.3.9. Preferred compression algorithms 1491 1492 (array of one-octet values) 1493 1494 Compression algorithm numbers that indicate which algorithms the key 1495 holder prefers to use. Like the preferred symmetric algorithms, the 1496 list is ordered. Algorithm numbers are in section 9. If this 1497 subpacket is not included, ZIP is preferred. A zero denotes that 1498 uncompressed data is preferred; the key holder's software might have 1499 no compression software in that implementation. This is only found 1500 on a self-signature. 1501 15025.2.3.10. Signature expiration time 1503 1504 (4 octet time field) 1505 1506 The validity period of the signature. This is the number of seconds 1507 after the signature creation time that the signature expires. If 1508 this is not present or has a value of zero, it never expires. 1509 1510 1511 1512Callas, et al. Expires Jan 08, 2006 [Page 27] 1513 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1514 15155.2.3.11. Exportable Certification 1516 1517 (1 octet of exportability, 0 for not, 1 for exportable) 1518 1519 This subpacket denotes whether a certification signature is 1520 "exportable," to be used by other users than the signature's issuer. 1521 The packet body contains a Boolean flag indicating whether the 1522 signature is exportable. If this packet is not present, the 1523 certification is exportable; it is equivalent to a flag containing a 1524 1. 1525 1526 Non-exportable, or "local," certifications are signatures made by a 1527 user to mark a key as valid within that user's implementation only. 1528 Thus, when an implementation prepares a user's copy of a key for 1529 transport to another user (this is the process of "exporting" the 1530 key), any local certification signatures are deleted from the key. 1531 1532 The receiver of a transported key "imports" it, and likewise trims 1533 any local certifications. In normal operation, there won't be any, 1534 assuming the import is performed on an exported key. However, there 1535 are instances where this can reasonably happen. For example, if an 1536 implementation allows keys to be imported from a key database in 1537 addition to an exported key, then this situation can arise. 1538 1539 Some implementations do not represent the interest of a single user 1540 (for example, a key server). Such implementations always trim local 1541 certifications from any key they handle. 1542 15435.2.3.12. Revocable 1544 1545 (1 octet of revocability, 0 for not, 1 for revocable) 1546 1547 Signature's revocability status. Packet body contains a Boolean 1548 flag indicating whether the signature is revocable. Signatures that 1549 are not revocable have any later revocation signatures ignored. 1550 They represent a commitment by the signer that he cannot revoke his 1551 signature for the life of his key. If this packet is not present, 1552 the signature is revocable. 1553 15545.2.3.13. Trust signature 1555 1556 (1 octet "level" (depth), 1 octet of trust amount) 1557 1558 Signer asserts that the key is not only valid, but also trustworthy, 1559 at the specified level. Level 0 has the same meaning as an ordinary 1560 validity signature. Level 1 means that the signed key is asserted 1561 to be a valid trusted introducer, with the 2nd octet of the body 1562 specifying the degree of trust. Level 2 means that the signed key is 1563 asserted to be trusted to issue level 1 trust signatures, i.e. that 1564 it is a "meta introducer". Generally, a level n trust signature 1565 asserts that a key is trusted to issue level n-1 trust signatures. 1566 The trust amount is in a range from 0-255, interpreted such that 1567 1568Callas, et al. Expires Jan 08, 2006 [Page 28] 1569 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1570 1571 values less than 120 indicate partial trust and values of 120 or 1572 greater indicate complete trust. Implementations SHOULD emit values 1573 of 60 for partial trust and 120 for complete trust. 1574 15755.2.3.14. Regular expression 1576 1577 (null-terminated regular expression) 1578 1579 Used in conjunction with trust signature packets (of level > 0) to 1580 limit the scope of trust that is extended. Only signatures by the 1581 target key on User IDs that match the regular expression in the body 1582 of this packet have trust extended by the trust signature subpacket. 1583 The regular expression uses the same syntax as the Henry Spencer's 1584 "almost public domain" regular expression package. A description of 1585 the syntax is found in a section below. 1586 15875.2.3.15. Revocation key 1588 1589 (1 octet of class, 1 octet of algid, 20 octets of fingerprint) 1590 1591 Authorizes the specified key to issue revocation signatures for this 1592 key. Class octet must have bit 0x80 set. If the bit 0x40 is set, 1593 then this means that the revocation information is sensitive. Other 1594 bits are for future expansion to other kinds of authorizations. This 1595 is found on a self-signature. 1596 1597 If the "sensitive" flag is set, the keyholder feels this subpacket 1598 contains private trust information that describes a real-world 1599 sensitive relationship. If this flag is set, implementations SHOULD 1600 NOT export this signature to other users except in cases where the 1601 data needs to be available: when the signature is being sent to the 1602 designated revoker, or when it is accompanied by a revocation 1603 signature from that revoker. Note that it may be appropriate to 1604 isolate this subpacket within a separate signature so that it is not 1605 combined with other subpackets that need to be exported. 1606 16075.2.3.16. Notation Data 1608 1609 (4 octets of flags, 2 octets of name length (M), 1610 2 octets of value length (N), 1611 M octets of name data, 1612 N octets of value data) 1613 1614 This subpacket describes a "notation" on the signature that the 1615 issuer wishes to make. The notation has a name and a value, each of 1616 which are strings of octets. There may be more than one notation in 1617 a signature. Notations can be used for any extension the issuer of 1618 the signature cares to make. The "flags" field holds four octets of 1619 flags. 1620 1621 1622 1623 1624Callas, et al. Expires Jan 08, 2006 [Page 29] 1625 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1626 1627 All undefined flags MUST be zero. Defined flags are: 1628 1629 First octet: 0x80 = human-readable. This note value is text, a 1630 note from one person to another, and need 1631 not have meaning to software. 1632 Other octets: none. 1633 1634 Notation names are arbitrary strings encoded in UTF-8. They reside 1635 two name spaces: The IETF name space and the user name space. 1636 1637 The IETF name space is registered with IANA. These names MUST NOT 1638 contain the "@" character (0x40). This this is a tag for the user 1639 name space. 1640 1641 Names in the user name space consist of a UTF-8 string tag followed 1642 by "@" followed by a DNS domain name. Note that the tag MUST NOT 1643 contain an "@" character. For example, the "sample" tag used by 1644 Example Corporation could be "sample@example.com". 1645 1646 Names in a user space are owned and controlled by the owners of that 1647 domain. Obviously, it's of bad form to create a new name in a DNS 1648 space that you don't own. 1649 1650 Since the user name space is in the form of an email address, 1651 implementers MAY wish to arrange for that address to reach a person 1652 who can be consulted about the use of the named tag. Note that due 1653 to UTF-8 encoding, not all valid user space name tags are valid 1654 email addresses. 1655 1656 If there is a critical notation, the criticality applies to that 1657 specific notation and not to notations in general. 1658 16595.2.3.17. Key server preferences 1660 1661 (N octets of flags) 1662 1663 This is a list of one-bit flags that indicate preferences that the 1664 key holder has about how the key is handled on a key server. All 1665 undefined flags MUST be zero. 1666 1667 First octet: 0x80 = No-modify 1668 the key holder requests that this key only be modified or 1669 updated by the key holder or an administrator of the key server. 1670 1671 This is found only on a self-signature. 1672 16735.2.3.18. Preferred key server 1674 1675 (String) 1676 1677 1678 1679 1680Callas, et al. Expires Jan 08, 2006 [Page 30] 1681 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1682 1683 This is a URI of a key server that the key holder prefers be used 1684 for updates. Note that keys with multiple User IDs can have a 1685 preferred key server for each User ID. Note also that since this is 1686 a URI, the key server can actually be a copy of the key retrieved by 1687 ftp, http, finger, etc. 1688 16895.2.3.19. Primary User ID 1690 1691 (1 octet, Boolean) 1692 1693 This is a flag in a User ID's self signature that states whether 1694 this User ID is the main User ID for this key. It is reasonable for 1695 an implementation to resolve ambiguities in preferences, etc. by 1696 referring to the primary User ID. If this flag is absent, its value 1697 is zero. If more than one User ID in a key is marked as primary, the 1698 implementation may resolve the ambiguity in any way it sees fit, but 1699 it is RECOMMENDED that priority be given to the User ID with the 1700 most recent self-signature. 1701 1702 When appearing on a self-signature on a User ID packet, this 1703 subpacket applies only to User ID packets. When appearing on a 1704 self-signature on a User Attribute packet, this subpacket applies 1705 only to User Attribute packets. That is to say, there are two 1706 different and independent "primaries" - one for User IDs, and one 1707 for User Attributes. 1708 17095.2.3.20. Policy URI 1710 1711 (String) 1712 1713 This subpacket contains a URI of a document that describes the 1714 policy that the signature was issued under. 1715 17165.2.3.21. Key Flags 1717 1718 (N octets of flags) 1719 1720 This subpacket contains a list of binary flags that hold information 1721 about a key. It is a string of octets, and an implementation MUST 1722 NOT assume a fixed size. This is so it can grow over time. If a list 1723 is shorter than an implementation expects, the unstated flags are 1724 considered to be zero. The defined flags are: 1725 1726 First octet: 1727 1728 0x01 - This key may be used to certify other keys. 1729 1730 0x02 - This key may be used to sign data. 1731 1732 0x04 - This key may be used to encrypt communications. 1733 1734 1735 1736Callas, et al. Expires Jan 08, 2006 [Page 31] 1737 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1738 1739 0x08 - This key may be used to encrypt storage. 1740 1741 0x10 - The private component of this key may have been split by 1742 a secret-sharing mechanism. 1743 1744 0x20 - This key may be used for authentication. 1745 1746 0x80 - The private component of this key may be in the 1747 possession of more than one person. 1748 1749 Usage notes: 1750 1751 The flags in this packet may appear in self-signatures or in 1752 certification signatures. They mean different things depending on 1753 who is making the statement -- for example, a certification 1754 signature that has the "sign data" flag is stating that the 1755 certification is for that use. On the other hand, the 1756 "communications encryption" flag in a self-signature is stating a 1757 preference that a given key be used for communications. Note 1758 however, that it is a thorny issue to determine what is 1759 "communications" and what is "storage." This decision is left wholly 1760 up to the implementation; the authors of this document do not claim 1761 any special wisdom on the issue, and realize that accepted opinion 1762 may change. 1763 1764 The "split key" (0x10) and "group key" (0x80) flags are placed on a 1765 self-signature only; they are meaningless on a certification 1766 signature. They SHOULD be placed only on a direct-key signature 1767 (type 0x1f) or a subkey signature (type 0x18), one that refers to 1768 the key the flag applies to. 1769 17705.2.3.22. Signer's User ID 1771 1772 (String) 1773 1774 This subpacket allows a keyholder to state which User ID is 1775 responsible for the signing. Many keyholders use a single key for 1776 different purposes, such as business communications as well as 1777 personal communications. This subpacket allows such a keyholder to 1778 state which of their roles is making a signature. 1779 1780 This subpacket is not appropriate to use to refer to a User 1781 Attribute packet. 1782 17835.2.3.23. Reason for Revocation 1784 1785 (1 octet of revocation code, N octets of reason string) 1786 1787 This subpacket is used only in key revocation and certification 1788 revocation signatures. It describes the reason why the key or 1789 certificate was revoked. 1790 1791 1792Callas, et al. Expires Jan 08, 2006 [Page 32] 1793 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1794 1795 The first octet contains a machine-readable code that denotes the 1796 reason for the revocation: 1797 1798 0x00 - No reason specified (key revocations or cert revocations) 1799 0x01 - Key is superseded (key revocations) 1800 0x02 - Key material has been compromised (key revocations) 1801 0x03 - Key is retired and no longer used (key revocations) 1802 0x20 - User ID information is no longer valid (cert revocations) 1803 1804 Following the revocation code is a string of octets which gives 1805 information about the reason for revocation in human-readable form 1806 (UTF-8). The string may be null, that is, of zero length. The length 1807 of the subpacket is the length of the reason string plus one. 1808 1809 An implementation SHOULD implement this subpacket, include it in all 1810 revocation signatures, and interpret revocations appropriately. 1811 There are important semantic differences between the reasons, and 1812 there are thus important reasons for revoking signatures. 1813 1814 If a key has been revoked because of a compromise, all signatures 1815 created by that key are suspect. However, if it was merely 1816 superseded or retired, old signatures are still valid. If the 1817 revoked signature is the self-signature for certifying a User ID, a 1818 revocation denotes that that user name is no longer in use. Such a 1819 revocation SHOULD include an 0x20 subpacket. 1820 1821 Note that any signature may be revoked, including a certification on 1822 some other person's key. There are many good reasons for revoking a 1823 certification signature, such as the case where the keyholder leaves 1824 the employ of a business with an email address. A revoked 1825 certification is no longer a part of validity calculations. 1826 18275.2.3.24. Features 1828 1829 (N octets of flags) 1830 1831 The features subpacket denotes which advanced OpenPGP features a 1832 user's implementation supports. This is so that as features are 1833 added to OpenPGP that cannot be backwards-compatible, a user can 1834 state that they can use that feature. The flags are single bits that 1835 indicate that a given feature is supported. 1836 1837 This subpacket is similar to a preferences subpacket, and only 1838 appears in a self-signature. 1839 1840 An implementation SHOULD NOT use a feature listed when sending to a 1841 user who does not state that they can use it. 1842 1843 Defined features are: 1844 1845 1846 1847 1848Callas, et al. Expires Jan 08, 2006 [Page 33] 1849 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1850 1851 First octet: 1852 1853 0x01 - Modification Detection (packets 18 and 19) 1854 1855 If an implementation implements any of the defined features, it 1856 SHOULD implement the features subpacket, too. 1857 1858 An implementation may freely infer features from other suitable 1859 implementation-dependent mechanisms. 1860 18615.2.3.25. Signature Target 1862 1863 (1 octet PK algorithm, 1 octet hash algorithm, N octets hash) 1864 1865 This subpacket identifies a specific target signature that a 1866 signature refers to. For revocation signatures, this subpacket 1867 provides explicit designation of which signature is being revoked. 1868 For a third-party or timestamp signature, this designates what 1869 signature is signed. All arguments are an identifier of that target 1870 signature. 1871 1872 The N octets of hash data MUST be the size of the hash of the 1873 signature. For example, a target signature with a SHA-1 hash MUST 1874 have 20 octets of hash data. 1875 18765.2.3.26. Embedded Signature 1877 1878 (1 signature packet body) 1879 1880 This subpacket contains a complete signature packet body as 1881 specified in section 5.2 above. It is useful when one signature 1882 needs to refer to, or be incorporated in, another signature. 1883 18845.2.4. Computing Signatures 1885 1886 All signatures are formed by producing a hash over the signature 1887 data, and then using the resulting hash in the signature algorithm. 1888 1889 The signature data is simple to compute for document signatures 1890 (types 0x00 and 0x01), for which the document itself is the data. 1891 For standalone signatures, this is a null string. 1892 1893 When a signature is made over a key, the hash data starts with the 1894 octet 0x99, followed by a two-octet length of the key, and then body 1895 of the key packet. (Note that this is an old-style packet header for 1896 a key packet with two-octet length.) A subkey binding signature 1897 (type 0x18) or primary key binding signature (type 0x19) then hashes 1898 the subkey using the same format as the main key (also using 0x99 as 1899 the first octet). Key revocation signatures (types 0x20 and 0x28) 1900 hash only the key being revoked. 1901 1902 1903 1904Callas, et al. Expires Jan 08, 2006 [Page 34] 1905 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1906 1907 When a signature is made over a signature packet, the hash data 1908 starts with the octet 0x88, followed by the four-octet length of the 1909 signature, and then the body of the signature packet. The unhashed 1910 subpacket data of the signature packet being hashed is not included 1911 in the hash and the unhashed subpacket data length value is set to 1912 zero. (Note that this is an old-style packet header for a signature 1913 packet with the length-of-length set to zero). 1914 1915 A certification signature (type 0x10 through 0x13) hashes the User 1916 ID being bound to the key into the hash context after the above 1917 data. A V3 certification hashes the contents of the User ID or 1918 attribute packet packet, without any header. A V4 certification 1919 hashes the constant 0xb4 for User ID certifications or the constant 1920 0xd1 for User Attribute certifications, followed by a four-octet 1921 number giving the length of the User ID or User Attribute data, and 1922 then the User ID or User Attribute data. 1923 1924 Once the data body is hashed, then a trailer is hashed. A V3 1925 signature hashes five octets of the packet body, starting from the 1926 signature type field. This data is the signature type, followed by 1927 the four-octet signature time. A V4 signature hashes the packet body 1928 starting from its first field, the version number, through the end 1929 of the hashed subpacket data. Thus, the fields hashed are the 1930 signature version, the signature type, the public key algorithm, the 1931 hash algorithm, the hashed subpacket length, and the hashed 1932 subpacket body. 1933 1934 V4 signatures also hash in a final trailer of six octets: the 1935 version of the signature packet, i.e. 0x04; 0xFF; a four-octet, 1936 big-endian number that is the length of the hashed data from the 1937 signature packet (note that this number does not include these final 1938 six octets. 1939 1940 After all this has been hashed in a single hash context the 1941 resulting hash field is used in the signature algorithm, and placed 1942 at the end of the signature packet. 1943 19445.2.4.1. Subpacket Hints 1945 1946 It is certainly possible for a signature to contain conflicting 1947 information in subpackets. For example, a signature may contain 1948 multiple copies of a preference or multiple expiration times. In 1949 most cases, an implementation SHOULD use the last subpacket in the 1950 signature, but MAY use any conflict resolution scheme that makes 1951 more sense. Please note that we are intentionally leaving conflict 1952 resolution to the implementer; most conflicts are simply syntax 1953 errors, and the wishy-washy language here allows a receiver to be 1954 generous in what they accept, while putting pressure on a creator to 1955 be stingy in what they generate. 1956 1957 1958 1959 1960Callas, et al. Expires Jan 08, 2006 [Page 35] 1961 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 1962 1963 Some apparent conflicts may actually make sense -- for example, 1964 suppose a keyholder has an V3 key and a V4 key that share the same 1965 RSA key material. Either of these keys can verify a signature 1966 created by the other, and it may be reasonable for a signature to 1967 contain an issuer subpacket for each key, as a way of explicitly 1968 tying those keys to the signature. 1969 19705.3. Symmetric-Key Encrypted Session Key Packets (Tag 3) 1971 1972 The Symmetric-Key Encrypted Session Key packet holds the 1973 symmetric-key encryption of a session key used to encrypt a message. 1974 Zero or more Encrypted Session Key packets and/or Symmetric-Key 1975 Encrypted Session Key packets may precede a Symmetrically Encrypted 1976 Data Packet that holds an encrypted message. The message is 1977 encrypted with a session key, and the session key is itself 1978 encrypted and stored in the Encrypted Session Key packet or the 1979 Symmetric-Key Encrypted Session Key packet. 1980 1981 If the Symmetrically Encrypted Data Packet is preceded by one or 1982 more Symmetric-Key Encrypted Session Key packets, each specifies a 1983 passphrase that may be used to decrypt the message. This allows a 1984 message to be encrypted to a number of public keys, and also to one 1985 or more pass phrases. This packet type is new, and is not generated 1986 by PGP 2.x or PGP 5.0. 1987 1988 The body of this packet consists of: 1989 1990 - A one-octet version number. The only currently defined version 1991 is 4. 1992 1993 - A one-octet number describing the symmetric algorithm used. 1994 1995 - A string-to-key (S2K) specifier, length as defined above. 1996 1997 - Optionally, the encrypted session key itself, which is decrypted 1998 with the string-to-key object. 1999 2000 If the encrypted session key is not present (which can be detected 2001 on the basis of packet length and S2K specifier size), then the S2K 2002 algorithm applied to the passphrase produces the session key for 2003 decrypting the file, using the symmetric cipher algorithm from the 2004 Symmetric-Key Encrypted Session Key packet. 2005 2006 If the encrypted session key is present, the result of applying the 2007 S2K algorithm to the passphrase is used to decrypt just that 2008 encrypted session key field, using CFB mode with an IV of all zeros. 2009 The decryption result consists of a one-octet algorithm identifier 2010 that specifies the symmetric-key encryption algorithm used to 2011 encrypt the following Symmetrically Encrypted Data Packet, followed 2012 by the session key octets themselves. 2013 2014 2015 2016Callas, et al. Expires Jan 08, 2006 [Page 36] 2017 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2018 2019 Note: because an all-zero IV is used for this decryption, the S2K 2020 specifier MUST use a salt value, either a Salted S2K or an 2021 Iterated-Salted S2K. The salt value will insure that the decryption 2022 key is not repeated even if the passphrase is reused. 2023 20245.4. One-Pass Signature Packets (Tag 4) 2025 2026 The One-Pass Signature packet precedes the signed data and contains 2027 enough information to allow the receiver to begin calculating any 2028 hashes needed to verify the signature. It allows the Signature 2029 Packet to be placed at the end of the message, so that the signer 2030 can compute the entire signed message in one pass. 2031 2032 A One-Pass Signature does not interoperate with PGP 2.6.x or 2033 earlier. 2034 2035 The body of this packet consists of: 2036 2037 - A one-octet version number. The current version is 3. 2038 2039 - A one-octet signature type. Signature types are described in 2040 section 5.2.1. 2041 2042 - A one-octet number describing the hash algorithm used. 2043 2044 - A one-octet number describing the public key algorithm used. 2045 2046 - An eight-octet number holding the key ID of the signing key. 2047 2048 - A one-octet number holding a flag showing whether the signature 2049 is nested. A zero value indicates that the next packet is 2050 another One-Pass Signature packet that describes another 2051 signature to be applied to the same message data. 2052 2053 Note that if a message contains more than one one-pass signature, 2054 then the signature packets bracket the message; that is, the first 2055 signature packet after the message corresponds to the last one-pass 2056 packet and the final signature packet corresponds to the first 2057 one-pass packet. 2058 20595.5. Key Material Packet 2060 2061 A key material packet contains all the information about a public or 2062 private key. There are four variants of this packet type, and two 2063 major versions. Consequently, this section is complex. 2064 20655.5.1. Key Packet Variants 2066 20675.5.1.1. Public Key Packet (Tag 6) 2068 2069 A Public Key packet starts a series of packets that forms an OpenPGP 2070 key (sometimes called an OpenPGP certificate). 2071 2072Callas, et al. Expires Jan 08, 2006 [Page 37] 2073 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2074 20755.5.1.2. Public Subkey Packet (Tag 14) 2076 2077 A Public Subkey packet (tag 14) has exactly the same format as a 2078 Public Key packet, but denotes a subkey. One or more subkeys may be 2079 associated with a top-level key. By convention, the top-level key 2080 provides signature services, and the subkeys provide encryption 2081 services. 2082 2083 Note: in PGP 2.6.x, tag 14 was intended to indicate a comment 2084 packet. This tag was selected for reuse because no previous version 2085 of PGP ever emitted comment packets but they did properly ignore 2086 them. Public Subkey packets are ignored by PGP 2.6.x and do not 2087 cause it to fail, providing a limited degree of backward 2088 compatibility. 2089 20905.5.1.3. Secret Key Packet (Tag 5) 2091 2092 A Secret Key packet contains all the information that is found in a 2093 Public Key packet, including the public key material, but also 2094 includes the secret key material after all the public key fields. 2095 20965.5.1.4. Secret Subkey Packet (Tag 7) 2097 2098 A Secret Subkey packet (tag 7) is the subkey analog of the Secret 2099 Key packet, and has exactly the same format. 2100 21015.5.2. Public Key Packet Formats 2102 2103 There are two versions of key-material packets. Version 3 packets 2104 were first generated by PGP 2.6. Version 4 keys first appeared in 2105 PGP 5.0, and are the preferred key version for OpenPGP. 2106 2107 OpenPGP implementations SHOULD create keys with version 4 format. V3 2108 keys are deprecated; an implementation SHOULD NOT generate a V3 key, 2109 but MAY accept it. An implementation MUST NOT create a V3 key with a 2110 public key algorithm other than RSA. 2111 2112 A version 3 public key or public subkey packet contains: 2113 2114 - A one-octet version number (3). 2115 2116 - A four-octet number denoting the time that the key was created. 2117 2118 - A two-octet number denoting the time in days that this key is 2119 valid. If this number is zero, then it does not expire. 2120 2121 - A one-octet number denoting the public key algorithm of this key 2122 2123 - A series of multiprecision integers comprising the key material: 2124 2125 2126 2127 2128Callas, et al. Expires Jan 08, 2006 [Page 38] 2129 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2130 2131 - a multiprecision integer (MPI) of RSA public modulus n; 2132 2133 - an MPI of RSA public encryption exponent e. 2134 2135 V3 keys are deprecated. They contain three weaknesses in them. 2136 First, it is relatively easy to construct a V3 key that has the same 2137 key ID as any other key because the key ID is simply the low 64 bits 2138 of the public modulus. Secondly, because the fingerprint of a V3 key 2139 hashes the key material, but not its length, there is an increased 2140 opportunity for fingerprint collisions. Third, there are minor 2141 weaknesses in the MD5 hash algorithm that make developers prefer 2142 other algorithms. See below for a fuller discussion of key IDs and 2143 fingerprints. 2144 2145 V2 keys are identical to V3 keys except for the deprecated V3 keys 2146 except for the version number. An implementation MUST NOT generate 2147 them and may accept or reject them as it sees fit. 2148 2149 The version 4 format is similar to the version 3 format except for 2150 the absence of a validity period. This has been moved to the 2151 signature packet. In addition, fingerprints of version 4 keys are 2152 calculated differently from version 3 keys, as described in section 2153 "Enhanced Key Formats." 2154 2155 A version 4 packet contains: 2156 2157 - A one-octet version number (4). 2158 2159 - A four-octet number denoting the time that the key was created. 2160 2161 - A one-octet number denoting the public key algorithm of this key 2162 2163 - A series of multiprecision integers comprising the key material. 2164 This algorithm-specific portion is: 2165 2166 Algorithm Specific Fields for RSA public keys: 2167 2168 - multiprecision integer (MPI) of RSA public modulus n; 2169 2170 - MPI of RSA public encryption exponent e. 2171 2172 Algorithm Specific Fields for DSA public keys: 2173 2174 - MPI of DSA prime p; 2175 2176 - MPI of DSA group order q (q is a prime divisor of p-1); 2177 2178 - MPI of DSA group generator g; 2179 2180 - MPI of DSA public key value y (= g**x mod p where x is 2181 secret). 2182 2183 2184Callas, et al. Expires Jan 08, 2006 [Page 39] 2185 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2186 2187 Algorithm Specific Fields for Elgamal public keys: 2188 2189 - MPI of Elgamal prime p; 2190 2191 - MPI of Elgamal group generator g; 2192 2193 - MPI of Elgamal public key value y (= g**x mod p where x is 2194 secret). 2195 21965.5.3. Secret Key Packet Formats 2197 2198 The Secret Key and Secret Subkey packets contain all the data of the 2199 Public Key and Public Subkey packets, with additional 2200 algorithm-specific secret key data appended, usually in encrypted 2201 form. 2202 2203 The packet contains: 2204 2205 - A Public Key or Public Subkey packet, as described above 2206 2207 - One octet indicating string-to-key usage conventions. Zero 2208 indicates that the secret key data is not encrypted. 255 or 254 2209 indicates that a string-to-key specifier is being given. Any 2210 other value is a symmetric-key encryption algorithm identifier. 2211 2212 - [Optional] If string-to-key usage octet was 255 or 254, a 2213 one-octet symmetric encryption algorithm. 2214 2215 - [Optional] If string-to-key usage octet was 255 or 254, a 2216 string-to-key specifier. The length of the string-to-key 2217 specifier is implied by its type, as described above. 2218 2219 - [Optional] If secret data is encrypted (string-to-key usage 2220 octet not zero), an Initial Vector (IV) of the same length as 2221 the cipher's block size. 2222 2223 - Plain or encrypted multiprecision integers comprising the secret 2224 key data. These algorithm-specific fields are as described 2225 below. 2226 2227 - If the string-to-key usage octet is zero or 255, then a 2228 two-octet checksum of the plaintext of the algorithm-specific 2229 portion (sum of all octets, mod 65536). If the string-to-key 2230 usage octet was 254, then a 20-octet SHA-1 hash of the plaintext 2231 of the algorithm-specific portion. This checksum or hash is 2232 encrypted together with the algorithm-specific fields (if 2233 string-to-key usage octet is not zero). Note that for all other 2234 values, a two-octet checksum is required. 2235 2236 Algorithm Specific Fields for RSA secret keys: 2237 2238 2239 2240Callas, et al. Expires Jan 08, 2006 [Page 40] 2241 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2242 2243 - multiprecision integer (MPI) of RSA secret exponent d. 2244 2245 - MPI of RSA secret prime value p. 2246 2247 - MPI of RSA secret prime value q (p < q). 2248 2249 - MPI of u, the multiplicative inverse of p, mod q. 2250 2251 Algorithm Specific Fields for DSA secret keys: 2252 2253 - MPI of DSA secret exponent x. 2254 2255 Algorithm Specific Fields for Elgamal secret keys: 2256 2257 - MPI of Elgamal secret exponent x. 2258 2259 Secret MPI values can be encrypted using a passphrase. If a 2260 string-to-key specifier is given, that describes the algorithm for 2261 converting the passphrase to a key, else a simple MD5 hash of the 2262 passphrase is used. Implementations MUST use a string-to-key 2263 specifier; the simple hash is for backward compatibility and is 2264 deprecated, though implementations MAY continue to use existing 2265 private keys in the old format. The cipher for encrypting the MPIs 2266 is specified in the secret key packet. 2267 2268 Encryption/decryption of the secret data is done in CFB mode using 2269 the key created from the passphrase and the Initial Vector from the 2270 packet. A different mode is used with V3 keys (which are only RSA) 2271 than with other key formats. With V3 keys, the MPI bit count prefix 2272 (i.e., the first two octets) is not encrypted. Only the MPI 2273 non-prefix data is encrypted. Furthermore, the CFB state is 2274 resynchronized at the beginning of each new MPI value, so that the 2275 CFB block boundary is aligned with the start of the MPI data. 2276 2277 With V4 keys, a simpler method is used. All secret MPI values are 2278 encrypted in CFB mode, including the MPI bitcount prefix. 2279 2280 The two-octet checksum that follows the algorithm-specific portion 2281 is the algebraic sum, mod 65536, of the plaintext of all the 2282 algorithm-specific octets (including MPI prefix and data). With V3 2283 keys, the checksum is stored in the clear. With V4 keys, the 2284 checksum is encrypted like the algorithm-specific data. This value 2285 is used to check that the passphrase was correct. However, this 2286 checksum is deprecated; an implementation SHOULD NOT use it, but 2287 should rather use the SHA-1 hash denoted with a usage octet of 254. 2288 The reason for this is that there are some attacks on the private 2289 key that can undetectably modify the secret key. Using a SHA-1 hash 2290 prevents this. 2291 22925.6. Compressed Data Packet (Tag 8) 2293 2294 The Compressed Data packet contains compressed data. Typically, this 2295 2296Callas, et al. Expires Jan 08, 2006 [Page 41] 2297 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2298 2299 packet is found as the contents of an encrypted packet, or following 2300 a Signature or One-Pass Signature packet, and contains literal data 2301 packets. 2302 2303 The body of this packet consists of: 2304 2305 - One octet that gives the algorithm used to compress the packet. 2306 2307 - The remainder of the packet is compressed data. 2308 2309 A Compressed Data Packet's body contains an block that compresses 2310 some set of packets. See section "Packet Composition" for details on 2311 how messages are formed. 2312 2313 ZIP-compressed packets are compressed with raw RFC 1951 DEFLATE 2314 blocks. Note that PGP V2.6 uses 13 bits of compression. If an 2315 implementation uses more bits of compression, PGP V2.6 cannot 2316 decompress it. 2317 2318 ZLIB-compressed packets are compressed with RFC 1950 ZLIB-style 2319 blocks. 2320 23215.7. Symmetrically Encrypted Data Packet (Tag 9) 2322 2323 The Symmetrically Encrypted Data packet contains data encrypted with 2324 a symmetric-key algorithm. When it has been decrypted, it contains 2325 other packets (usually literal data packets or compressed data 2326 packets, but in theory other Symmetrically Encrypted Data Packets or 2327 sequences of packets that form whole OpenPGP messages). 2328 2329 The body of this packet consists of: 2330 2331 - Encrypted data, the output of the selected symmetric-key cipher 2332 operating in OpenPGP's variant of Cipher Feedback (CFB) mode. 2333 2334 The symmetric cipher used may be specified in an Public-Key or 2335 Symmetric-Key Encrypted Session Key packet that precedes the 2336 Symmetrically Encrypted Data Packet. In that case, the cipher 2337 algorithm octet is prefixed to the session key before it is 2338 encrypted. If no packets of these types precede the encrypted data, 2339 the IDEA algorithm is used with the session key calculated as the 2340 MD5 hash of the passphrase, though this use is deprecated. 2341 2342 The data is encrypted in CFB mode, with a CFB shift size equal to 2343 the cipher's block size. The Initial Vector (IV) is specified as 2344 all zeros. Instead of using an IV, OpenPGP prefixes a string of 2345 length equal to the block size of the cipher plus two to the data 2346 before it is encrypted. The first block-size octets (for example, 8 2347 octets for a 64-bit block length) are random, and the following two 2348 octets are copies of the last two octets of the IV. For example, in 2349 an 8 octet block, octet 9 is a repeat of octet 7, and octet 10 is a 2350 repeat of octet 8. In a cipher of length 16, octet 17 is a repeat of 2351 2352Callas, et al. Expires Jan 08, 2006 [Page 42] 2353 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2354 2355 octet 15 and octet 18 is a repeat of octet 16. As a pedantic 2356 clarification, in both these examples, we consider the first octet 2357 to be numbered 1. 2358 2359 After encrypting the first block-size-plus-two octets, the CFB state 2360 is resynchronized. The last block-size octets of ciphertext are 2361 passed through the cipher and the block boundary is reset. 2362 2363 The repetition of 16 bits in the random data prefixed to the message 2364 allows the receiver to immediately check whether the session key is 2365 incorrect. See the Security Considerations section for hints on the 2366 proper use of this "quick check." 2367 23685.8. Marker Packet (Obsolete Literal Packet) (Tag 10) 2369 2370 An experimental version of PGP used this packet as the Literal 2371 packet, but no released version of PGP generated Literal packets 2372 with this tag. With PGP 5.x, this packet has been re-assigned and is 2373 reserved for use as the Marker packet. 2374 2375 The body of this packet consists of: 2376 2377 - The three octets 0x50, 0x47, 0x50 (which spell "PGP" in UTF-8). 2378 2379 Such a packet MUST be ignored when received. It may be placed at 2380 the beginning of a message that uses features not available in PGP 2381 2.6.x in order to cause that version to report that newer software 2382 is necessary to process the message. 2383 23845.9. Literal Data Packet (Tag 11) 2385 2386 A Literal Data packet contains the body of a message; data that is 2387 not to be further interpreted. 2388 2389 The body of this packet consists of: 2390 2391 - A one-octet field that describes how the data is formatted. 2392 2393 If it is a 'b' (0x62), then the literal packet contains binary data. 2394 If it is a 't' (0x74), then it contains text data, and thus may need 2395 line ends converted to local form, or other text-mode changes. The 2396 tag 'u' (0x75) means the same as 't', but also indicates that 2397 implementation believes that the literal data contains UTF-8 text. 2398 2399 Early versions of PGP also defined a value of 'l' as a 'local' mode 2400 for machine-local conversions. RFC 1991 incorrectly stated this 2401 local mode flag as '1' (ASCII numeral one). Both of these local 2402 modes are deprecated. 2403 2404 - File name as a string (one-octet length, followed by a file 2405 name). This may be a zero-length string. Commonly, if the source 2406 of the encrypted data is a file, this will be the name of the 2407 2408Callas, et al. Expires Jan 08, 2006 [Page 43] 2409 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2410 2411 encrypted file. An implementation MAY consider the file name in 2412 the literal packet to be a more authoritative name than the 2413 actual file name. 2414 2415 If the special name "_CONSOLE" is used, the message is considered to 2416 be "for your eyes only". This advises that the message data is 2417 unusually sensitive, and the receiving program should process it 2418 more carefully, perhaps avoiding storing the received data to disk, 2419 for example. 2420 2421 - A four-octet number that indicates a date associated with the 2422 literal data. Commonly, the date might be the modification date 2423 of a file, or the time the packet was created, or a zero that 2424 indicates no specific time. 2425 2426 - The remainder of the packet is literal data. 2427 2428 Text data is stored with <CR><LF> text endings (i.e. network-normal 2429 line endings). These should be converted to native line endings by 2430 the receiving software. 2431 24325.10. Trust Packet (Tag 12) 2433 2434 The Trust packet is used only within keyrings and is not normally 2435 exported. Trust packets contain data that record the user's 2436 specifications of which key holders are trustworthy introducers, 2437 along with other information that implementing software uses for 2438 trust information. The format of trust packets is defined by a given 2439 implementation. 2440 2441 Trust packets SHOULD NOT be emitted to output streams that are 2442 transferred to other users, and they SHOULD be ignored on any input 2443 other than local keyring files. 2444 24455.11. User ID Packet (Tag 13) 2446 2447 A User ID packet consists of UTF-8 text that is intended to 2448 represent the name and email address of the key holder. By 2449 convention, it includes an RFC 822 mail name, but there are no 2450 restrictions on its content. The packet length in the header 2451 specifies the length of the User ID. 2452 24535.12. User Attribute Packet (Tag 17) 2454 2455 The User Attribute packet is a variation of the User ID packet. It 2456 is capable of storing more types of data than the User ID packet 2457 which is limited to text. Like the User ID packet, a User Attribute 2458 packet may be certified by the key owner ("self-signed") or any 2459 other key owner who cares to certify it. Except as noted, a User 2460 Attribute packet may be used anywhere that a User ID packet may be 2461 used. 2462 2463 2464Callas, et al. Expires Jan 08, 2006 [Page 44] 2465 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2466 2467 While User Attribute packets are not a required part of the OpenPGP 2468 standard, implementations SHOULD provide at least enough 2469 compatibility to properly handle a certification signature on the 2470 User Attribute packet. A simple way to do this is by treating the 2471 User Attribute packet as a User ID packet with opaque contents, but 2472 an implementation may use any method desired. 2473 2474 The User Attribute packet is made up of one or more attribute 2475 subpackets. Each subpacket consists of a subpacket header and a 2476 body. The header consists of: 2477 2478 - the subpacket length (1, 2, or 5 octets) 2479 2480 - the subpacket type (1 octet) 2481 2482 and is followed by the subpacket specific data. 2483 2484 The only currently defined subpacket type is 1, signifying an image. 2485 An implementation SHOULD ignore any subpacket of a type that it does 2486 not recognize. Subpacket types 100 through 110 are reserved for 2487 private or experimental use. 2488 24895.12.1. The Image Attribute Subpacket 2490 2491 The image attribute subpacket is used to encode an image, presumably 2492 (but not required to be) that of the key owner. 2493 2494 The image attribute subpacket begins with an image header. The 2495 first two octets of the image header contain the length of the image 2496 header. Note that unlike other multi-octet numerical values in this 2497 document, due to an historical accident this value is encoded as a 2498 little-endian number. The image header length is followed by a 2499 single octet for the image header version. The only currently 2500 defined version of the image header is 1, which is a 16 octet image 2501 header. The first three octets of a version 1 image header are thus 2502 0x10 0x00 0x01. 2503 2504 The fourth octet of a version 1 image header designates the encoding 2505 format of the image. The only currently defined encoding format is 2506 the value 1 to indicate JPEG. Image format types 100 through 110 2507 are reserved for private or experimental use. The rest of the 2508 version 1 image header is made up of 12 reserved octets, all of 2509 which MUST be set to 0. 2510 2511 The rest of the image subpacket contains the image itself. As the 2512 only currently defined image type is JPEG, the image is encoded in 2513 the JPEG File Interchange Format (JFIF), a standard file format for 2514 JPEG images. [JFIF] 2515 2516 An implementation MAY try and determine the type of an image by 2517 examination of the image data if it is unable to handle a particular 2518 version of the image header or if a specified encoding format value 2519 2520Callas, et al. Expires Jan 08, 2006 [Page 45] 2521 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2522 2523 is not recognized. 2524 25255.13. Sym. Encrypted Integrity Protected Data Packet (Tag 18) 2526 2527 The Symmetrically Encrypted Integrity Protected Data Packet is a 2528 variant of the Symmetrically Encrypted Data Packet. It is a new 2529 feature created for OpenPGP that addresses the problem of detecting 2530 a modification to encrypted data. It is used in combination with a 2531 Modification Detection Code Packet. 2532 2533 There is a corresponding feature in the features signature subpacket 2534 that denotes that an implementation can properly use this packet 2535 type. An implementation MUST support decrypting these packets and 2536 SHOULD prefer generating them to the older Symmetrically Encrypted 2537 Data Packet when possible. Since this data packet protects against 2538 modification attacks, this standard encourages its proliferation. 2539 While blanket adoption of this data packet would create 2540 interoperability problems, rapid adoption is nevertheless important. 2541 An implementation SHOULD specifically denote support for this 2542 packet, but it MAY infer it from other mechanisms. 2543 2544 For example, an implementation might infer from the use of a cipher 2545 such as AES or Twofish that a user supports this feature. It might 2546 place in the unhashed portion of another user's key signature a 2547 features subpacket. It might also present a user with an opportunity 2548 to regenerate their own self-signature with a features subpacket. 2549 2550 This packet contains data encrypted with a symmetric-key algorithm 2551 and protected against modification by the SHA-1 hash algorithm. When 2552 it has been decrypted, it will typically contain other packets 2553 (often literal data packets or compressed data packets). The last 2554 decrypted packet in this packet's payload MUST be a Modification 2555 Detection Code packet. 2556 2557 The body of this packet consists of: 2558 2559 - A one-octet version number. The only currently defined value is 2560 1. 2561 2562 - Encrypted data, the output of the selected symmetric-key cipher 2563 operating in Cipher Feedback mode with shift amount equal to the 2564 block size of the cipher (CFB-n where n is the block size). 2565 2566 The symmetric cipher used MUST be specified in a Public-Key or 2567 Symmetric-Key Encrypted Session Key packet that precedes the 2568 Symmetrically Encrypted Data Packet. In either case, the cipher 2569 algorithm octet is prefixed to the session key before it is 2570 encrypted. 2571 2572 The data is encrypted in CFB mode, with a CFB shift size equal to 2573 the cipher's block size. The Initial Vector (IV) is specified as 2574 all zeros. Instead of using an IV, OpenPGP prefixes an octet string 2575 2576Callas, et al. Expires Jan 08, 2006 [Page 46] 2577 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2578 2579 to the data before it is encrypted. The length of the octet string 2580 equals the block size of the cipher in octets, plus two. The first 2581 octets in the group, of length equal to the block size of the 2582 cipher, are random; the last two octets are each copies of their 2nd 2583 preceding octet. For example, with a cipher whose block size is 128 2584 bits or 16 octets, the prefix data will contain 16 random octets, 2585 then two more octets, which are copies of the 15th and 16th octets, 2586 respectively. Unlike the Symmetrically Encrypted Data Packet, no 2587 special CFB resynchronization is done after encrypting this prefix 2588 data. See OpenPGP CFB Mode below for more details. 2589 2590 The repetition of 16 bits in the random data prefixed to the message 2591 allows the receiver to immediately check whether the session key is 2592 incorrect. 2593 2594 The plaintext of the data to be encrypted is passed through the 2595 SHA-1 hash function, and the result of the hash is appended to the 2596 plaintext in a Modification Detection Code packet. The input to the 2597 hash function includes the prefix data described above; it includes 2598 all of the plaintext, and then also includes two octets of values 2599 0xD3, 0x14. These represent the encoding of a Modification 2600 Detection Code packet tag and length field of 20 octets. 2601 2602 The resulting hash value is stored in a Modification Detection Code 2603 packet which MUST use the two octet encoding just given to represent 2604 its tag and length field. The body of the MDC packet is the 20 2605 octet output of the SHA-1 hash. 2606 2607 The Modification Detection Code packet is appended to the plaintext 2608 and encrypted along with the plaintext using the same CFB context. 2609 2610 During decryption, the plaintext data should be hashed with SHA-1, 2611 including the prefix data as well as the packet tag and length field 2612 of the Modification Detection Code packet. The body of the MDC 2613 packet, upon decryption, is compared with the result of the SHA-1 2614 hash. 2615 2616 Any failure of the MDC indicates that the message has been modified 2617 and MUST be treated as a security problem. Failures include a 2618 difference in the hash values, but also the absence of an MDC 2619 packet, or an MDC packet in any position other than the end of the 2620 plaintext. Any failure SHOULD be reported to the user. 2621 2622 Note: future designs of new versions of this packet should consider 2623 rollback attacks since it will be possible for an attacker to change 2624 the version back to 1. 2625 26265.14. Modification Detection Code Packet (Tag 19) 2627 2628 The Modification Detection Code packet contains a SHA-1 hash of 2629 plaintext data which is used to detect message modification. It is 2630 only used with a Symmetrically Encrypted Integrity Protected Data 2631 2632Callas, et al. Expires Jan 08, 2006 [Page 47] 2633 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2634 2635 packet. The Modification Detection Code packet MUST be the last 2636 packet in the plaintext data which is encrypted in the Symmetrically 2637 Encrypted Integrity Protected Data packet, and MUST appear in no 2638 other place. 2639 2640 A Modification Detection Code packet MUST have a length of 20 2641 octets. 2642 2643 The body of this packet consists of: 2644 2645 - A 20-octet SHA-1 hash of the preceding plaintext data of the 2646 Symmetrically Encrypted Integrity Protected Data packet, 2647 including prefix data, the tag octet, and length octet of the 2648 Modification Detection Code packet. 2649 2650 Note that the Modification Detection Code packet MUST always use a 2651 new-format encoding of the packet tag, and a one-octet encoding of 2652 the packet length. The reason for this is that the hashing rules for 2653 modification detection include a one-octet tag and one-octet length 2654 in the data hash. While this is a bit restrictive, it reduces 2655 complexity. 2656 26576. Radix-64 Conversions 2658 2659 As stated in the introduction, OpenPGP's underlying native 2660 representation for objects is a stream of arbitrary octets, and some 2661 systems desire these objects to be immune to damage caused by 2662 character set translation, data conversions, etc. 2663 2664 In principle, any printable encoding scheme that met the 2665 requirements of the unsafe channel would suffice, since it would not 2666 change the underlying binary bit streams of the native OpenPGP data 2667 structures. The OpenPGP standard specifies one such printable 2668 encoding scheme to ensure interoperability. 2669 2670 OpenPGP's Radix-64 encoding is composed of two parts: a base64 2671 encoding of the binary data, and a checksum. The base64 encoding is 2672 identical to the MIME base64 content-transfer-encoding [RFC2045]. 2673 2674 The checksum is a 24-bit CRC converted to four characters of 2675 radix-64 encoding by the same MIME base64 transformation, preceded 2676 by an equals sign (=). The CRC is computed by using the generator 2677 0x864CFB and an initialization of 0xB704CE. The accumulation is 2678 done on the data before it is converted to radix-64, rather than on 2679 the converted data. A sample implementation of this algorithm is in 2680 the next section. 2681 2682 The checksum with its leading equal sign MAY appear on the first 2683 line after the Base64 encoded data. 2684 2685 2686 2687 2688Callas, et al. Expires Jan 08, 2006 [Page 48] 2689 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2690 2691 Rationale for CRC-24: The size of 24 bits fits evenly into printable 2692 base64. The nonzero initialization can detect more errors than a 2693 zero initialization. 2694 26956.1. An Implementation of the CRC-24 in "C" 2696 2697 #define CRC24_INIT 0xb704ceL 2698 #define CRC24_POLY 0x1864cfbL 2699 2700 typedef long crc24; 2701 crc24 crc_octets(unsigned char *octets, size_t len) 2702 { 2703 crc24 crc = CRC24_INIT; 2704 int i; 2705 2706 while (len--) { 2707 crc ^= (*octets++) << 16; 2708 for (i = 0; i < 8; i++) { 2709 crc <<= 1; 2710 if (crc & 0x1000000) 2711 crc ^= CRC24_POLY; 2712 } 2713 } 2714 return crc & 0xffffffL; 2715 } 2716 27176.2. Forming ASCII Armor 2718 2719 When OpenPGP encodes data into ASCII Armor, it puts specific headers 2720 around the Radix-64 encoded data, so OpenPGP can reconstruct the 2721 data later. An OpenPGP implementation MAY use ASCII armor to protect 2722 raw binary data. OpenPGP informs the user what kind of data is 2723 encoded in the ASCII armor through the use of the headers. 2724 2725 Concatenating the following data creates ASCII Armor: 2726 2727 - An Armor Header Line, appropriate for the type of data 2728 2729 - Armor Headers 2730 2731 - A blank (zero-length, or containing only whitespace) line 2732 2733 - The ASCII-Armored data 2734 2735 - An Armor Checksum 2736 2737 - The Armor Tail, which depends on the Armor Header Line. 2738 2739 An Armor Header Line consists of the appropriate header line text 2740 surrounded by five (5) dashes ('-', 0x2D) on either side of the 2741 header line text. The header line text is chosen based upon the 2742 type of data that is being encoded in Armor, and how it is being 2743 2744Callas, et al. Expires Jan 08, 2006 [Page 49] 2745 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2746 2747 encoded. Header line texts include the following strings: 2748 2749 BEGIN PGP MESSAGE 2750 Used for signed, encrypted, or compressed files. 2751 2752 BEGIN PGP PUBLIC KEY BLOCK 2753 Used for armoring public keys 2754 2755 BEGIN PGP PRIVATE KEY BLOCK 2756 Used for armoring private keys 2757 2758 BEGIN PGP MESSAGE, PART X/Y 2759 Used for multi-part messages, where the armor is split amongst Y 2760 parts, and this is the Xth part out of Y. 2761 2762 BEGIN PGP MESSAGE, PART X 2763 Used for multi-part messages, where this is the Xth part of an 2764 unspecified number of parts. Requires the MESSAGE-ID Armor 2765 Header to be used. 2766 2767 BEGIN PGP SIGNATURE 2768 Used for detached signatures, OpenPGP/MIME signatures, and 2769 cleartext signatures. Note that PGP 2.x uses BEGIN PGP MESSAGE 2770 for detached signatures. 2771 2772 Note that all these Armor Header Lines are to consist of a complete 2773 line. That is to say, there is always a line ending preceding the 2774 starting five dashes, and following the ending five dashes. The 2775 header lines, therefore, MUST start at the beginning of a line, and 2776 MUST NOT have text following them on the same line. These line 2777 endings are considered a part of the Armor Header Line for the 2778 purposes of determining the content they delimit. This is 2779 particularly important when computing a cleartext signature (see 2780 below). 2781 2782 The Armor Headers are pairs of strings that can give the user or the 2783 receiving OpenPGP implementation some information about how to 2784 decode or use the message. The Armor Headers are a part of the 2785 armor, not a part of the message, and hence are not protected by any 2786 signatures applied to the message. 2787 2788 The format of an Armor Header is that of a key-value pair. A colon 2789 (':' 0x38) and a single space (0x20) separate the key and value. 2790 OpenPGP should consider improperly formatted Armor Headers to be 2791 corruption of the ASCII Armor. Unknown keys should be reported to 2792 the user, but OpenPGP should continue to process the message. 2793 2794 Currently defined Armor Header Keys are: 2795 2796 - "Version", that states the OpenPGP implementation and version 2797 used to encode the message. 2798 2799 2800Callas, et al. Expires Jan 08, 2006 [Page 50] 2801 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2802 2803 - "Comment", a user-defined comment. OpenPGP defines all text to 2804 be in UTF-8. A comment may be any UTF-8 string. However, the 2805 whole point of armoring is to provide seven-bit-clean data. 2806 Consequently, if a comment has characters that are outside the 2807 US-ASCII range of UTF, they may very well not survive transport. 2808 2809 - "MessageID", a 32-character string of printable characters. The 2810 string must be the same for all parts of a multi-part message 2811 that uses the "PART X" Armor Header. MessageID strings should 2812 be unique enough that the recipient of the mail can associate 2813 all the parts of a message with each other. A good checksum or 2814 cryptographic hash function is sufficient. 2815 2816 The MessageID SHOULD NOT appear unless it is in a multi-part 2817 message. If it appears at all, it MUST be computed from the 2818 finished (encrypted, signed, etc.) message in a deterministic 2819 fashion, rather than contain a purely random value. This is to 2820 allow the legitimate recipient to determine that the MessageID 2821 cannot serve as a covert means of leaking cryptographic key 2822 information. 2823 2824 - "Hash", a comma-separated list of hash algorithms used in this 2825 message. This is used only in cleartext signed messages. 2826 2827 - "Charset", a description of the character set that the plaintext 2828 is in. Please note that OpenPGP defines text to be in UTF-8. An 2829 implementation will get best results by translating into and out 2830 of UTF-8. However, there are many instances where this is easier 2831 said than done. Also, there are communities of users who have no 2832 need for UTF-8 because they are all happy with a character set 2833 like ISO Latin-5 or a Japanese character set. In such instances, 2834 an implementation MAY override the UTF-8 default by using this 2835 header key. An implementation MAY implement this key and any 2836 translations it cares to; an implementation MAY ignore it and 2837 assume all text is UTF-8. 2838 2839 The Armor Tail Line is composed in the same manner as the Armor 2840 Header Line, except the string "BEGIN" is replaced by the string 2841 "END". 2842 28436.3. Encoding Binary in Radix-64 2844 2845 The encoding process represents 24-bit groups of input bits as 2846 output strings of 4 encoded characters. Proceeding from left to 2847 right, a 24-bit input group is formed by concatenating three 8-bit 2848 input groups. These 24 bits are then treated as four concatenated 2849 6-bit groups, each of which is translated into a single digit in the 2850 Radix-64 alphabet. When encoding a bit stream with the Radix-64 2851 encoding, the bit stream must be presumed to be ordered with the 2852 most-significant-bit first. That is, the first bit in the stream 2853 will be the high-order bit in the first 8-bit octet, and the eighth 2854 bit will be the low-order bit in the first 8-bit octet, and so on. 2855 2856Callas, et al. Expires Jan 08, 2006 [Page 51] 2857 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2858 2859 +--first octet--+-second octet--+--third octet--+ 2860 |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0| 2861 +-----------+---+-------+-------+---+-----------+ 2862 |5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0| 2863 +--1.index--+--2.index--+--3.index--+--4.index--+ 2864 2865 Each 6-bit group is used as an index into an array of 64 printable 2866 characters from the table below. The character referenced by the 2867 index is placed in the output string. 2868 2869 Value Encoding Value Encoding Value Encoding Value Encoding 2870 0 A 17 R 34 i 51 z 2871 1 B 18 S 35 j 52 0 2872 2 C 19 T 36 k 53 1 2873 3 D 20 U 37 l 54 2 2874 4 E 21 V 38 m 55 3 2875 5 F 22 W 39 n 56 4 2876 6 G 23 X 40 o 57 5 2877 7 H 24 Y 41 p 58 6 2878 8 I 25 Z 42 q 59 7 2879 9 J 26 a 43 r 60 8 2880 10 K 27 b 44 s 61 9 2881 11 L 28 c 45 t 62 + 2882 12 M 29 d 46 u 63 / 2883 13 N 30 e 47 v 2884 14 O 31 f 48 w (pad) = 2885 15 P 32 g 49 x 2886 16 Q 33 h 50 y 2887 2888 The encoded output stream must be represented in lines of no more 2889 than 76 characters each. 2890 2891 Special processing is performed if fewer than 24 bits are available 2892 at the end of the data being encoded. There are three possibilities: 2893 2894 1. The last data group has 24 bits (3 octets). No special 2895 processing is needed. 2896 2897 2. The last data group has 16 bits (2 octets). The first two 6-bit 2898 groups are processed as above. The third (incomplete) data group 2899 has two zero-value bits added to it, and is processed as above. 2900 A pad character (=) is added to the output. 2901 2902 3. The last data group has 8 bits (1 octet). The first 6-bit group 2903 is processed as above. The second (incomplete) data group has 2904 four zero-value bits added to it, and is processed as above. Two 2905 pad characters (=) are added to the output. 2906 29076.4. Decoding Radix-64 2908 2909 Any characters outside of the base64 alphabet are ignored in 2910 Radix-64 data. Decoding software must ignore all line breaks or 2911 2912Callas, et al. Expires Jan 08, 2006 [Page 52] 2913 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2914 2915 other characters not found in the table above. 2916 2917 In Radix-64 data, characters other than those in the table, line 2918 breaks, and other white space probably indicate a transmission 2919 error, about which a warning message or even a message rejection 2920 might be appropriate under some circumstances. 2921 2922 Because it is used only for padding at the end of the data, the 2923 occurrence of any "=" characters may be taken as evidence that the 2924 end of the data has been reached (without truncation in transit). No 2925 such assurance is possible, however, when the number of octets 2926 transmitted was a multiple of three and no "=" characters are 2927 present. 2928 29296.5. Examples of Radix-64 2930 2931 Input data: 0x14fb9c03d97e 2932 Hex: 1 4 f b 9 c | 0 3 d 9 7 e 2933 8-bit: 00010100 11111011 10011100 | 00000011 11011001 2934 11111110 2935 6-bit: 000101 001111 101110 011100 | 000000 111101 100111 2936 111110 2937 Decimal: 5 15 46 28 0 61 37 62 2938 Output: F P u c A 9 l + 2939 2940 Input data: 0x14fb9c03d9 2941 Hex: 1 4 f b 9 c | 0 3 d 9 2942 8-bit: 00010100 11111011 10011100 | 00000011 11011001 2943 pad with 00 2944 6-bit: 000101 001111 101110 011100 | 000000 111101 100100 2945 Decimal: 5 15 46 28 0 61 36 2946 pad with = 2947 Output: F P u c A 9 k = 2948 2949 Input data: 0x14fb9c03 2950 Hex: 1 4 f b 9 c | 0 3 2951 8-bit: 00010100 11111011 10011100 | 00000011 2952 pad with 0000 2953 6-bit: 000101 001111 101110 011100 | 000000 110000 2954 Decimal: 5 15 46 28 0 48 2955 pad with = = 2956 Output: F P u c A w = = 2957 29586.6. Example of an ASCII Armored Message 2959 2960 -----BEGIN PGP MESSAGE----- 2961 Version: OpenPrivacy 0.99 2962 2963 yDgBO22WxBHv7O8X7O/jygAEzol56iUKiXmV+XmpCtmpqQUKiQrFqclFqUDBovzS 2964 vBSFjNSiVHsuAA== 2965 =njUN 2966 -----END PGP MESSAGE----- 2967 2968Callas, et al. Expires Jan 08, 2006 [Page 53] 2969 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 2970 2971 Note that this example is indented by two spaces. 2972 29737. Cleartext signature framework 2974 2975 It is desirable to sign a textual octet stream without ASCII 2976 armoring the stream itself, so the signed text is still readable 2977 without special software. In order to bind a signature to such a 2978 cleartext, this framework is used. (Note that RFC 3156 defines 2979 another way to sign cleartext messages for environments that support 2980 MIME.) 2981 2982 The cleartext signed message consists of: 2983 2984 - The cleartext header '-----BEGIN PGP SIGNED MESSAGE-----' on a 2985 single line, 2986 2987 - One or more "Hash" Armor Headers, 2988 2989 - Exactly one empty line not included into the message digest, 2990 2991 - The dash-escaped cleartext that is included into the message 2992 digest, 2993 2994 - The ASCII armored signature(s) including the '-----BEGIN PGP 2995 SIGNATURE-----' Armor Header and Armor Tail Lines. 2996 2997 If the "Hash" armor header is given, the specified message digest 2998 algorithm(s) are used for the signature. If there are no such 2999 headers, MD5 is used. If MD5 is the only hash used, then an 3000 implementation MAY omit this header for improved V2.x compatibility. 3001 If more than one message digest is used in the signature, the "Hash" 3002 armor header contains a comma-delimited list of used message 3003 digests. 3004 3005 Current message digest names are described below with the algorithm 3006 IDs. 3007 30087.1. Dash-Escaped Text 3009 3010 The cleartext content of the message must also be dash-escaped. 3011 3012 Dash escaped cleartext is the ordinary cleartext where every line 3013 starting with a dash '-' (0x2D) is prefixed by the sequence dash '-' 3014 (0x2D) and space ' ' (0x20). This prevents the parser from 3015 recognizing armor headers of the cleartext itself. An implementation 3016 MAY dash escape any line, SHOULD dash escape lines commencing "From" 3017 followed by a space, and MUST dash escape any line commencing in a 3018 dash. The message digest is computed using the cleartext itself, not 3019 the dash escaped form. 3020 3021 3022 3023 3024Callas, et al. Expires Jan 08, 2006 [Page 54] 3025 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3026 3027 As with binary signatures on text documents, a cleartext signature 3028 is calculated on the text using canonical <CR><LF> line endings. 3029 The line ending (i.e. the <CR><LF>) before the '-----BEGIN PGP 3030 SIGNATURE-----' line that terminates the signed text is not 3031 considered part of the signed text. 3032 3033 When reversing dash-escaping, an implementation MUST strip the 3034 string "- " if it occurs at the beginning of a line, and SHOULD warn 3035 on "-" and any character other than a space at the beginning of a 3036 line. 3037 3038 Also, any trailing whitespace -- spaces (0x20) and tabs (0x09) -- at 3039 the end of any line is removed when the cleartext signature is 3040 generated. 3041 30428. Regular Expressions 3043 3044 A regular expression is zero or more branches, separated by '|'. It 3045 matches anything that matches one of the branches. 3046 3047 A branch is zero or more pieces, concatenated. It matches a match 3048 for the first, followed by a match for the second, etc. 3049 3050 A piece is an atom possibly followed by '*', '+', or '?'. An atom 3051 followed by '*' matches a sequence of 0 or more matches of the atom. 3052 An atom followed by '+' matches a sequence of 1 or more matches of 3053 the atom. An atom followed by '?' matches a match of the atom, or 3054 the null string. 3055 3056 An atom is a regular expression in parentheses (matching a match for 3057 the regular expression), a range (see below), '.' (matching any 3058 single character), '^' (matching the null string at the beginning of 3059 the input string), '$' (matching the null string at the end of the 3060 input string), a '\' followed by a single character (matching that 3061 character), or a single character with no other significance 3062 (matching that character). 3063 3064 A range is a sequence of characters enclosed in '[]'. It normally 3065 matches any single character from the sequence. If the sequence 3066 begins with '^', it matches any single character not from the rest 3067 of the sequence. If two characters in the sequence are separated by 3068 '-', this is shorthand for the full list of ASCII characters between 3069 them (e.g. '[0-9]' matches any decimal digit). To include a literal 3070 ']' in the sequence, make it the first character (following a 3071 possible '^'). To include a literal '-', make it the first or last 3072 character. 3073 30749. Constants 3075 3076 This section describes the constants used in OpenPGP. 3077 3078 3079 3080Callas, et al. Expires Jan 08, 2006 [Page 55] 3081 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3082 3083 Note that these tables are not exhaustive lists; an implementation 3084 MAY implement an algorithm not on these lists, so long as the 3085 algorithm number(s) are chosen from the private or experimental 3086 algorithm range. 3087 3088 See the section "Notes on Algorithms" below for more discussion of 3089 the algorithms. 3090 30919.1. Public Key Algorithms 3092 3093 ID Algorithm 3094 -- --------- 3095 1 - RSA (Encrypt or Sign) [HAC] 3096 2 - RSA Encrypt-Only 3097 3 - RSA Sign-Only 3098 16 - Elgamal (Encrypt-Only), see [ELGAMAL] [HAC] 3099 17 - DSA (Digital Signature Algorithm) [FIPS186] [HAC] 3100 18 - Reserved for Elliptic Curve 3101 19 - Reserved for ECDSA 3102 20 - Reserved (formerly Elgamal Encrypt or Sign) 3103 21 - Reserved for Diffie-Hellman (X9.42, 3104 as defined for IETF-S/MIME) 3105 100 to 110 - Private/Experimental algorithm. 3106 3107 Implementations MUST implement DSA for signatures, and Elgamal for 3108 encryption. Implementations SHOULD implement RSA keys. 3109 Implementations MAY implement any other algorithm. 3110 31119.2. Symmetric Key Algorithms 3112 3113 ID Algorithm 3114 -- --------- 3115 0 - Plaintext or unencrypted data 3116 1 - IDEA [IDEA] 3117 2 - TripleDES (DES-EDE, [SCHNEIER] [HAC] - 3118 168 bit key derived from 192) 3119 3 - CAST5 (128 bit key, as per RFC 2144) 3120 4 - Blowfish (128 bit key, 16 rounds) [BLOWFISH] 3121 5 - Reserved 3122 6 - Reserved 3123 7 - AES with 128-bit key [AES] 3124 8 - AES with 192-bit key 3125 9 - AES with 256-bit key 3126 10 - Twofish with 256-bit key [TWOFISH] 3127 100 to 110 - Private/Experimental algorithm. 3128 3129 Implementations MUST implement TripleDES. Implementations SHOULD 3130 implement AES-128 and CAST5. Implementations that interoperate with 3131 PGP 2.6 or earlier need to support IDEA, as that is the only 3132 symmetric cipher those versions use. Implementations MAY implement 3133 any other algorithm. 3134 3135 3136Callas, et al. Expires Jan 08, 2006 [Page 56] 3137 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3138 31399.3. Compression Algorithms 3140 3141 ID Algorithm 3142 -- --------- 3143 0 - Uncompressed 3144 1 - ZIP (RFC 1951) 3145 2 - ZLIB (RFC 1950) 3146 3 - BZip2 [BZ2] 3147 100 to 110 - Private/Experimental algorithm. 3148 3149 Implementations MUST implement uncompressed data. Implementations 3150 SHOULD implement ZIP. Implementations MAY implement any other 3151 algorithm. 3152 31539.4. Hash Algorithms 3154 3155 ID Algorithm Text Name 3156 -- --------- ---- ---- 3157 1 - MD5 "MD5" 3158 2 - SHA-1 [FIPS180] "SHA1" 3159 3 - RIPE-MD/160 "RIPEMD160" 3160 4 - Reserved 3161 5 - Reserved 3162 6 - Reserved 3163 7 - Reserved 3164 8 - SHA256 [FIPS180] "SHA256" 3165 9 - SHA384 [FIPS180] "SHA384" 3166 10 - SHA512 [FIPS180] "SHA512" 3167 100 to 110 - Private/Experimental algorithm. 3168 3169 Implementations MUST implement SHA-1. Implementations MAY implement 3170 other algorithms. 3171 317210. Packet Composition 3173 3174 OpenPGP packets are assembled into sequences in order to create 3175 messages and to transfer keys. Not all possible packet sequences 3176 are meaningful and correct. This section describes the rules for 3177 how packets should be placed into sequences. 3178 317910.1. Transferable Public Keys 3180 3181 OpenPGP users may transfer public keys. The essential elements of a 3182 transferable public key are: 3183 3184 - One Public Key packet 3185 3186 - Zero or more revocation signatures 3187 3188 - One or more User ID packets 3189 3190 3191 3192Callas, et al. Expires Jan 08, 2006 [Page 57] 3193 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3194 3195 - After each User ID packet, zero or more signature packets 3196 (certifications) 3197 3198 - Zero or more User Attribute packets 3199 3200 - After each User Attribute packet, zero or more signature packets 3201 (certifications) 3202 3203 - Zero or more Subkey packets 3204 3205 - After each Subkey packet, one signature packet, plus optionally 3206 a revocation. 3207 3208 The Public Key packet occurs first. Each of the following User ID 3209 packets provides the identity of the owner of this public key. If 3210 there are multiple User ID packets, this corresponds to multiple 3211 means of identifying the same unique individual user; for example, a 3212 user may have more than one email address, and construct a User ID 3213 for each one. 3214 3215 Immediately following each User ID packet, there are zero or more 3216 signature packets. Each signature packet is calculated on the 3217 immediately preceding User ID packet and the initial Public Key 3218 packet. The signature serves to certify the corresponding public key 3219 and User ID. In effect, the signer is testifying to his or her 3220 belief that this public key belongs to the user identified by this 3221 User ID. 3222 3223 Within the same section as the User ID packets, there are zero or 3224 more User Attribute packets. Like the User ID packets, a User 3225 Attribute packet is followed by zero or more signature packets 3226 calculated on the immediately preceding User Attribute packet and 3227 the initial Public Key packet. 3228 3229 User Attribute packets and User ID packets may be freely intermixed 3230 in this section, so long as the signatures that follow them are 3231 maintained on the proper User Attribute or User ID packet. 3232 3233 After the User ID or Attribute packets there may be one or more 3234 Subkey packets. In general, subkeys are provided in cases where the 3235 top-level public key is a signature-only key. However, any V4 key 3236 may have subkeys, and the subkeys may be encryption-only keys, 3237 signature-only keys, or general-purpose keys. V3 keys MUST NOT have 3238 subkeys. 3239 3240 Each Subkey packet must be followed by one Signature packet, which 3241 should be a subkey binding signature issued by the top level key. 3242 For subkeys that can issue signatures, the subkey binding signature 3243 must contain an embedded signature subpacket with a primary key 3244 binding signature (0x19) issued by the subkey on the top level key. 3245 3246 3247 3248Callas, et al. Expires Jan 08, 2006 [Page 58] 3249 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3250 3251 Subkey and Key packets may each be followed by a revocation 3252 Signature packet to indicate that the key is revoked. Revocation 3253 signatures are only accepted if they are issued by the key itself, 3254 or by a key that is authorized to issue revocations via a revocation 3255 key subpacket in a self-signature by the top level key. 3256 3257 Transferable public key packet sequences may be concatenated to 3258 allow transferring multiple public keys in one operation. 3259 326010.2. OpenPGP Messages 3261 3262 An OpenPGP message is a packet or sequence of packets that 3263 corresponds to the following grammatical rules (comma represents 3264 sequential composition, and vertical bar separates alternatives): 3265 3266 OpenPGP Message :- Encrypted Message | Signed Message | 3267 Compressed Message | Literal Message. 3268 3269 Compressed Message :- Compressed Data Packet. 3270 3271 Literal Message :- Literal Data Packet | 3272 Literal Message, Literal Data Packet. 3273 3274 ESK :- Public Key Encrypted Session Key Packet | 3275 Symmetric-Key Encrypted Session Key Packet. 3276 3277 ESK Sequence :- ESK | ESK Sequence, ESK. 3278 3279 Encrypted Data :- Symmetrically Encrypted Data Packet | 3280 Symmetrically Encrypted Integrity Protected Data Packet 3281 3282 Encrypted Message :- Encrypted Data | ESK Sequence, Encrypted Data. 3283 3284 One-Pass Signed Message :- One-Pass Signature Packet, 3285 OpenPGP Message, Corresponding Signature Packet. 3286 3287 Signed Message :- Signature Packet, OpenPGP Message | 3288 One-Pass Signed Message. 3289 3290 In addition, decrypting a Symmetrically Encrypted Data Packet or a 3291 Symmetrically Encrypted Integrity Protected Data Packet as well as 3292 3293 decompressing a Compressed Data packet must yield a valid OpenPGP 3294 Message. 3295 329610.3. Detached Signatures 3297 3298 Some OpenPGP applications use so-called "detached signatures." For 3299 example, a program bundle may contain a file, and with it a second 3300 file that is a detached signature of the first file. These detached 3301 signatures are simply a signature packet stored separately from the 3302 data that they are a signature of. 3303 3304Callas, et al. Expires Jan 08, 2006 [Page 59] 3305 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3306 330711. Enhanced Key Formats 3308 330911.1. Key Structures 3310 3311 The format of an OpenPGP V3 key is as follows. Entries in square 3312 brackets are optional and ellipses indicate repetition. 3313 3314 RSA Public Key 3315 [Revocation Self Signature] 3316 User ID [Signature ...] 3317 [User ID [Signature ...] ...] 3318 3319 Each signature certifies the RSA public key and the preceding User 3320 ID. The RSA public key can have many User IDs and each User ID can 3321 have many signatures. V3 keys are deprecated. Implementations MUST 3322 NOT generate new V3 keys, but MAY continue to use existing ones. 3323 3324 The format of an OpenPGP V4 key that uses multiple public keys is 3325 similar except that the other keys are added to the end as "subkeys" 3326 of the primary key. 3327 3328 Primary-Key 3329 [Revocation Self Signature] 3330 [Direct Key Signature...] 3331 User ID [Signature ...] 3332 [User ID [Signature ...] ...] 3333 [User Attribute [Signature ...] ...] 3334 [[Subkey [Binding-Signature-Revocation] 3335 Primary-Key-Binding-Signature] ...] 3336 3337 A subkey always has a single signature after it that is issued using 3338 the primary key to tie the two keys together. This binding 3339 signature may be in either V3 or V4 format, but SHOULD be V4. 3340 3341 In the above diagram, if the binding signature of a subkey has been 3342 revoked, the revoked key may be removed, leaving only one key. 3343 3344 In a V4 key, the primary key MUST be a key capable of certification. 3345 The subkeys may be keys of any other type. There may be other 3346 constructions of V4 keys, too. For example, there may be a 3347 single-key RSA key in V4 format, a DSA primary key with an RSA 3348 encryption key, or RSA primary key with an Elgamal subkey, etc. 3349 3350 It is also possible to have a signature-only subkey. This permits a 3351 primary key that collects certifications (key signatures) but is 3352 used only used for certifying subkeys that are used for encryption 3353 and signatures. 3354 335511.2. Key IDs and Fingerprints 3356 3357 For a V3 key, the eight-octet key ID consists of the low 64 bits of 3358 the public modulus of the RSA key. 3359 3360Callas, et al. Expires Jan 08, 2006 [Page 60] 3361 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3362 3363 The fingerprint of a V3 key is formed by hashing the body (but not 3364 the two-octet length) of the MPIs that form the key material (public 3365 modulus n, followed by exponent e) with MD5. Note that both V3 keys 3366 and MD5 are deprecated. 3367 3368 A V4 fingerprint is the 160-bit SHA-1 hash of the octet 0x99, 3369 followed by the two-octet packet length, followed by the entire 3370 Public Key packet starting with the version field. The key ID is 3371 the low order 64 bits of the fingerprint. Here are the fields of 3372 the hash material, with the example of a DSA key: 3373 3374 a.1) 0x99 (1 octet) 3375 3376 a.2) high order length octet of (b)-(f) (1 octet) 3377 3378 a.3) low order length octet of (b)-(f) (1 octet) 3379 3380 b) version number = 4 (1 octet); 3381 3382 c) time stamp of key creation (4 octets); 3383 3384 d) algorithm (1 octet): 17 = DSA (example); 3385 3386 e) Algorithm specific fields. 3387 3388 Algorithm Specific Fields for DSA keys (example): 3389 3390 e.1) MPI of DSA prime p; 3391 3392 e.2) MPI of DSA group order q (q is a prime divisor of p-1); 3393 3394 e.3) MPI of DSA group generator g; 3395 3396 e.4) MPI of DSA public key value y (= g**x mod p where x is secret). 3397 3398 Note that it is possible for there to be collisions of key IDs -- 3399 two different keys with the same key ID. Note that there is a much 3400 smaller, but still non-zero probability that two different keys have 3401 the same fingerprint. 3402 3403 Also note that if V3 and V4 format keys share the same RSA key 3404 material, they will have different key IDs as well as different 3405 fingerprints. 3406 3407 Finally, the key ID and fingerprint of a subkey are calculated in 3408 the same way as for a primary key, including the 0x99 as the first 3409 octet (even though this is not a valid packet ID for a public 3410 subkey). 3411 341212. Notes on Algorithms 3413 341412.1. Symmetric Algorithm Preferences 3415 3416Callas, et al. Expires Jan 08, 2006 [Page 61] 3417 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3418 3419 3420 The symmetric algorithm preference is an ordered list of algorithms 3421 that the keyholder accepts. Since it is found on a self-signature, 3422 it is possible that a keyholder may have different preferences. For 3423 example, Alice may have TripleDES only specified for 3424 "alice@work.com" but CAST5, Blowfish, and TripleDES specified for 3425 "alice@home.org". Note that it is also possible for preferences to 3426 be in a subkey's binding signature. 3427 3428 Since TripleDES is the MUST-implement algorithm, if it is not 3429 explicitly in the list, it is tacitly at the end. However, it is 3430 good form to place it there explicitly. Note also that if an 3431 implementation does not implement the preference, then it is 3432 implicitly a TripleDES-only implementation. 3433 3434 An implementation MUST NOT use a symmetric algorithm that is not in 3435 the recipient's preference list. When encrypting to more than one 3436 recipient, the implementation finds a suitable algorithm by taking 3437 the intersection of the preferences of the recipients. Note that the 3438 MUST-implement algorithm, TripleDES, ensures that the intersection 3439 is not null. The implementation may use any mechanism to pick an 3440 algorithm in the intersection. 3441 3442 If an implementation can decrypt a message that a keyholder doesn't 3443 have in their preferences, the implementation SHOULD decrypt the 3444 message anyway, but MUST warn the keyholder that the protocol has 3445 been violated. (For example, suppose that Alice, above, has software 3446 that implements all algorithms in this specification. Nonetheless, 3447 she prefers subsets for work or home. If she is sent a message 3448 encrypted with IDEA, which is not in her preferences, the software 3449 warns her that someone sent her an IDEA-encrypted message, but it 3450 would ideally decrypt it anyway.) 3451 345212.2. Other Algorithm Preferences 3453 3454 Other algorithm preferences work similarly to the symmetric 3455 algorithm preference, in that they specify which algorithms the 3456 keyholder accepts. There are two interesting cases that other 3457 comments need to be made about, though, the compression preferences 3458 and the hash preferences. 3459 346012.2.1. Compression Preferences 3461 3462 Compression has been an integral part of PGP since its first days. 3463 OpenPGP and all previous versions of PGP have offered compression. 3464 In this specification, the default is for messages to be compressed, 3465 although an implementation is not required to do so. Consequently, 3466 the compression preference gives a way for a keyholder to request 3467 that messages not be compressed, presumably because they are using a 3468 minimal implementation that does not include compression. 3469 Additionally, this gives a keyholder a way to state that it can 3470 support alternate algorithms. 3471 3472Callas, et al. Expires Jan 08, 2006 [Page 62] 3473 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3474 3475 Like the algorithm preferences, an implementation MUST NOT use an 3476 algorithm that is not in the preference vector. If the preferences 3477 are not present, then they are assumed to be [ZIP(1), 3478 UNCOMPRESSED(0)]. 3479 3480 Additionally, an implementation MUST implement this preference to 3481 the degree of recognizing when to send an uncompressed message. A 3482 robust implementation would satisfy this requirement by looking at 3483 the recipient's preference and acting accordingly. A minimal 3484 implementation can satisfy this requirement by never generating a 3485 compressed message, since all implementations can handle messages 3486 that have not been compressed. 3487 348812.2.2. Hash Algorithm Preferences 3489 3490 Typically, the choice of a hash algorithm is something the signer 3491 does, rather than the verifier, because a signer rarely knows who is 3492 going to be verifying the signature. This preference, though, allows 3493 a protocol based upon digital signatures ease in negotiation. 3494 3495 Thus, if Alice is authenticating herself to Bob with a signature, it 3496 makes sense for her to use a hash algorithm that Bob's software 3497 uses. This preference allows Bob to state in his key which 3498 algorithms Alice may use. 3499 3500 Since SHA1 is the MUST-implement hash algorithm, if it is not 3501 explicitly in the list, it is tacitly at the end. However, it is 3502 good form to place it there explicitly. 3503 350412.3. Plaintext 3505 3506 Algorithm 0, "plaintext," may only be used to denote secret keys 3507 that are stored in the clear. Implementations MUST NOT use plaintext 3508 in Symmetrically Encrypted Data Packets; they must use Literal Data 3509 Packets to encode unencrypted or literal data. 3510 351112.4. RSA 3512 3513 There are algorithm types for RSA-signature-only, and 3514 RSA-encrypt-only keys. These types are deprecated. The "key flags" 3515 subpacket in a signature is a much better way to express the same 3516 idea, and generalizes it to all algorithms. An implementation SHOULD 3517 NOT create such a key, but MAY interpret it. 3518 3519 An implementation SHOULD NOT implement RSA keys of size less than 3520 1024 bits. 3521 352212.5. DSA 3523 3524 An implementation SHOULD NOT implement DSA keys of size less than 3525 1024 bits. Note that present DSA is limited to a maximum of 1024 bit 3526 keys, which are recommended for long-term use. Also, DSA keys MUST 3527 3528Callas, et al. Expires Jan 08, 2006 [Page 63] 3529 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3530 3531 be an even multiple of 64 bits long. 3532 353312.6. Elgamal 3534 3535 An implementation SHOULD NOT implement Elgamal keys of size less 3536 than 1024 bits. 3537 353812.7. Reserved Algorithm Numbers 3539 3540 A number of algorithm IDs have been reserved for algorithms that 3541 would be useful to use in an OpenPGP implementation, yet there are 3542 issues that prevent an implementer from actually implementing the 3543 algorithm. These are marked in the Public Algorithms section as 3544 "(reserved for)". 3545 3546 The reserved public key algorithms, Elliptic Curve (18), ECDSA (19), 3547 and X9.42 (21) do not have the necessary parameters, parameter 3548 order, or semantics defined. 3549 3550 Previous versions of OpenPGP permitted Elgamal [ELGAMAL] signatures 3551 with a public key identifier of 20. These are no longer permitted. 3552 An implementation MUST NOT generate such keys. An implementation 3553 MUST NOT generate Elgamal signatures. 3554 355512.8. OpenPGP CFB mode 3556 3557 OpenPGP does symmetric encryption using a variant of Cipher Feedback 3558 Mode (CFB mode). This section describes the procedure it uses in 3559 detail. This mode is what is used for Symmetrically Encrypted Data 3560 Packets; the mechanism used for encrypting secret key material is 3561 similar, but described in those sections above. 3562 3563 In the description below, the value BS is the block size in octets 3564 of the cipher. Most ciphers have a block size of 8 octets. The AES 3565 and Twofish have a block size of 16 octets. Also note that the 3566 description below assumes that the IV and CFB arrays start with an 3567 index of 1 (unlike the C language, which assumes arrays start with a 3568 zero index). 3569 3570 OpenPGP CFB mode uses an initialization vector (IV) of all zeros, 3571 and prefixes the plaintext with BS+2 octets of random data, such 3572 that octets BS+1 and BS+2 match octets BS-1 and BS. It does a CFB 3573 "resync" after encrypting those BS+2 octets. 3574 3575 Thus, for an algorithm that has a block size of 8 octets (64 bits), 3576 the IV is 10 octets long and octets 7 and 8 of the IV are the same 3577 as octets 9 and 10. For an algorithm with a block size of 16 octets 3578 (128 bits), the IV is 18 octets long, and octets 17 and 18 replicate 3579 octets 15 and 16. Those extra two octets are an easy check for a 3580 correct key. 3581 3582 3583 3584Callas, et al. Expires Jan 08, 2006 [Page 64] 3585 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3586 3587 Step by step, here is the procedure: 3588 3589 1. The feedback register (FR) is set to the IV, which is all zeros. 3590 3591 2. FR is encrypted to produce FRE (FR Encrypted). This is the 3592 encryption of an all-zero value. 3593 3594 3. FRE is xored with the first BS octets of random data prefixed to 3595 the plaintext to produce C[1] through C[BS], the first BS octets 3596 of ciphertext. 3597 3598 4. FR is loaded with C[1] through C[BS]. 3599 3600 5. FR is encrypted to produce FRE, the encryption of the first BS 3601 octets of ciphertext. 3602 3603 6. The left two octets of FRE get xored with the next two octets of 3604 data that were prefixed to the plaintext. This produces C[BS+1] 3605 and C[BS+2], the next two octets of ciphertext. 3606 3607 7. (The resync step) FR is loaded with C[3] through C[BS+2]. 3608 3609 8. FR is encrypted to produce FRE. 3610 3611 9. FRE is xored with the first BS octets of the given plaintext, 3612 now that we have finished encrypting the BS+2 octets of prefixed 3613 data. This produces C[BS+3] through C[BS+(BS+2)], the next BS 3614 octets of ciphertext. 3615 3616 10. FR is loaded with C[BS+3] to C[BS + (BS+2)] (which is C11-C18 3617 for an 8-octet block). 3618 3619 11. FR is encrypted to produce FRE. 3620 3621 12. FRE is xored with the next BS octets of plaintext, to produce 3622 the next BS octets of ciphertext. These are loaded into FR and 3623 the process is repeated until the plaintext is used up. 3624 362513. Security Considerations 3626 3627 * As with any technology involving cryptography, you should check 3628 the current literature to determine if any algorithms used here 3629 have been found to be vulnerable to attack. 3630 3631 * This specification uses Public Key Cryptography technologies. It 3632 is assumed that the private key portion of a public-private key 3633 pair is controlled and secured by the proper party or parties. 3634 3635 * Certain operations in this specification involve the use of 3636 random numbers. An appropriate entropy source should be used to 3637 generate these numbers. See RFC 1750. 3638 3639 3640Callas, et al. Expires Jan 08, 2006 [Page 65] 3641 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3642 3643 * The MD5 hash algorithm has been found to have weaknesses, with 3644 collisions found in a number of cases. MD5 is deprecated for use 3645 in OpenPGP. Implementations MUST NOT generate new signatures 3646 using MD5 as a hash function. They MAY continue to consider old 3647 signatures that used MD5 as valid. 3648 3649 * SHA384 requires the same work as SHA512. In general, there are 3650 few reasons to use it -- you need a situation where one needs 3651 more security than SHA256, but do not want to have the 512-bit 3652 data length. 3653 3654 * Many security protocol designers think that it is a bad idea to 3655 use a single key for both privacy (encryption) and integrity 3656 (signatures). In fact, this was one of the motivating forces 3657 behind the V4 key format with separate signature and encryption 3658 keys. If you as an implementer promote dual-use keys, you should 3659 at least be aware of this controversy. 3660 3661 * The DSA algorithm will work with any 160-bit hash, but it is 3662 sensitive to the quality of the hash algorithm, if the hash 3663 algorithm is broken, it can leak the secret key. The Digital 3664 Signature Standard (DSS) specifies that DSA be used with SHA-1. 3665 RIPEMD-160 is considered by many cryptographers to be as strong. 3666 An implementation should take care which hash algorithms are 3667 used with DSA, as a weak hash can not only allow a signature to 3668 be forged, but could leak the secret key. 3669 3670 * There is a somewhat-related potential security problem in 3671 signatures. If an attacker can find a message that hashes to the 3672 same hash with a different algorithm, a bogus signature 3673 structure can be constructed that evaluates correctly. 3674 3675 For example, suppose Alice DSA signs message M using hash 3676 algorithm H. Suppose that Mallet finds a message M' that has the 3677 same hash value as M with H'. Mallet can then construct a 3678 signature block that verifies as Alice's signature of M' with 3679 H'. However, this would also constitute a weakness in either H 3680 or H' or both. Should this ever occur, a revision will have to 3681 be made to this document to revise the allowed hash algorithms. 3682 3683 * If you are building an authentication system, the recipient may 3684 specify a preferred signing algorithm. However, the signer would 3685 be foolish to use a weak algorithm simply because the recipient 3686 requests it. 3687 3688 * Some of the encryption algorithms mentioned in this document 3689 have been analyzed less than others. For example, although 3690 CAST5 is presently considered strong, it has been analyzed less 3691 than TripleDES. Other algorithms may have other controversies 3692 surrounding them. 3693 3694 3695 3696Callas, et al. Expires Jan 08, 2006 [Page 66] 3697 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3698 3699 * In late summer 2002, Jallad, Katz, and Schneier published an 3700 interesting attack on the OpenPGP protocol and some of its 3701 implementations [JKS02]. In this attack, the attacker modifies a 3702 message and sends it to a user who then returns the erroneously 3703 decrypted message to the attacker. The attacker is thus using 3704 the user as a random oracle, and can often decrypt the message. 3705 3706 Compressing data can ameliorate this attack. The incorrectly 3707 decrypted data nearly always decompresses in ways that defeats 3708 the attack. However, this is not a rigorous fix, and leaves open 3709 some small vulnerabilities. For example, if an implementation 3710 does not compress a message before encryption (perhaps because 3711 it knows it was already compressed), then that message is 3712 vulnerable. Because of this happenstance -- that modification 3713 attacks can be thwarted by decompression errors, an 3714 implementation SHOULD treat a decompression error as a security 3715 problem, not merely a data problem. 3716 3717 This attack can be defeated by the use of Modification 3718 Detection, provided that the implementation does not let the 3719 user naively return the data to the attacker. An implementation 3720 MUST treat an MDC failure as a security problem, not merely a 3721 data problem. 3722 3723 In either case, the implementation MAY allow the user access to 3724 the erroneous data, but MUST warn the user as to potential 3725 security problems should that data be returned to the sender. 3726 3727 While this attack is somewhat obscure, requiring a special set 3728 of circumstances to create it, it is nonetheless quite serious 3729 as it permits someone to trick a user to decrypt a message. 3730 Consequently, it is important that: 3731 3732 1. Implementers treat MDC errors and decompression failures as 3733 security problems. 3734 3735 2. Implementers implement Modification Detection with all due 3736 speed and encourage its spread. 3737 3738 3. Users migrate to implementations that support Modification 3739 Detection with all due speed. 3740 3741 * PKCS1 has been found to be vulnerable to attacks in which a 3742 system that reports errors in padding differently from errors in 3743 decryption becomes a random oracle that can leak the private key 3744 in mere millions of queries. Implementations must be aware of 3745 this attack and prevent it from happening. The simplest solution 3746 is report a single error code for all variants of decryption 3747 errors so as not to leak information to an attacker. 3748 3749 3750 3751 3752Callas, et al. Expires Jan 08, 2006 [Page 67] 3753 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3754 3755 * Some technologies mentioned here may be subject to government 3756 control in some countries. 3757 3758 * In winter 2005, Serge Mister and Robert Zuccherato from Entrust 3759 released a paper describing a way that the "quick check" in 3760 OpenPGP CFB mode can be used with a random oracle to decrypt two 3761 octets of every cipher block [MZ05]. They recommend as 3762 prevention not using the quick check at all. 3763 3764 Many implementers have taken this advice to heart for any data 3765 that is both symmetrically encrypted, but also the session key 3766 is public-key encrypted. In this case, the quick check is not 3767 needed as the public key encryption of the session key should 3768 guarantee that it is the right session key. In other cases, the 3769 implementation should use the quick check with care. On the one 3770 hand, there is a danger to using it if there is a random oracle 3771 that can leak information to an attacker. On the other hand, it 3772 is inconvenient to the user to be informed that they typed in 3773 the wrong passphrase only after a petabyte of data is decrypted. 3774 There are many cases in cryptographic engineering where the 3775 implementer must use care and wisdom, and this is another. 3776 377714. Implementation Nits 3778 3779 This section is a collection of comments to help an implementer, 3780 particularly with an eye to backward compatibility. Previous 3781 implementations of PGP are not OpenPGP-compliant. Often the 3782 differences are small, but small differences are frequently more 3783 vexing than large differences. Thus, this is a non-comprehensive 3784 list of potential problems and gotchas for a developer who is trying 3785 to be backward-compatible. 3786 3787 * The IDEA algorithm is patented, and yet it is required for PGP 3788 2.x interoperability. It is also the defacto preferred algorithm 3789 for a V3 key with a V3 self-signature (or no self-signature). 3790 3791 * When exporting a private key, PGP 2.x generates the header 3792 "BEGIN PGP SECRET KEY BLOCK" instead of "BEGIN PGP PRIVATE KEY 3793 BLOCK". All previous versions ignore the implied data type, and 3794 look directly at the packet data type. 3795 3796 * PGP 2.0 through 2.5 generated V2 Public Key Packets. These are 3797 identical to the deprecated V3 keys except for the version 3798 number. An implementation MUST NOT generate them and may accept 3799 or reject them as it sees fit. Some older PGP versions generated 3800 V2 PKESK packets (Tag 1) as well. An implementation may accept 3801 or reject V2 PKESK packets as it sees fit, and MUST NOT generate 3802 them. 3803 3804 * PGP 2.6.x will not accept key-material packets with versions 3805 greater than 3. 3806 3807 3808Callas, et al. Expires Jan 08, 2006 [Page 68] 3809 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3810 3811 * There are many ways possible for two keys to have the same key 3812 material, but different fingerprints (and thus key IDs). Perhaps 3813 the most interesting is an RSA key that has been "upgraded" to 3814 V4 format, but since a V4 fingerprint is constructed by hashing 3815 the key creation time along with other things, two V4 keys 3816 created at different times, yet with the same key material will 3817 have different fingerprints. 3818 3819 * If an implementation is using zlib to interoperate with PGP 2.x, 3820 then the "windowBits" parameter should be set to -13. 3821 3822 * PGP 2.6.X and 5.0 do not trim trailing whitespace from a 3823 "canonical text" signature. They only remove it from cleartext 3824 signatures. These signatures are not OpenPGP compliant -- 3825 OpenPGP requires trimming the whitespace. If you wish to 3826 interoperate with PGP 2.6.X or PGP 5, you may wish to accept 3827 these non-compliant signatures. 3828 382915. Authors and Working Group Chair 3830 3831 The working group can be contacted via the current chair: 3832 3833 Derek Atkins 3834 IHTFP Consulting, Inc. 3835 6 Farragut Ave 3836 Somerville, MA 02144 USA 3837 Email: derek@ihtfp.com 3838 Tel: +1 617 623 3745 3839 3840 The principal authors of this draft are: 3841 3842 Jon Callas 3843 3844 Email: jon@callas.org 3845 Tel: +1 (408) 448-6801 3846 3847 Lutz Donnerhacke 3848 IKS GmbH 3849 Wildenbruchstr. 15 3850 07745 Jena, Germany 3851 3852 EMail: lutz@iks-jena.de 3853 Tel: +49-3641-675642 3854 3855 Hal Finney 3856 Network Associates, Inc. 3857 3965 Freedom Circle 3858 Santa Clara, CA 95054, USA 3859 3860 Email: hal@finney.org 3861 3862 3863 3864Callas, et al. Expires Jan 08, 2006 [Page 69] 3865 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3866 3867 Rodney Thayer 3868 3869 Email: rodney@tillerman.to 3870 3871 This memo also draws on much previous work from a number of other 3872 authors who include: Derek Atkins, Charles Breed, Dave Del Torto, 3873 Marc Dyksterhouse, Gail Haspert, Gene Hoffman, Paul Hoffman, Raph 3874 Levien, Colin Plumb, Will Price, David Shaw, William Stallings, Mark 3875 Weaver, and Philip R. Zimmermann. 3876 387716. References (Normative) 3878 3879 3880 [AES] Advanced Encryption Standards Questions and Answers 3881 <http://csrc.nist.gov/encryption/aes/round2/ 3882 aesfact.html> 3883 3884 <http://csrc.nist.gov/encryption/aes/round2/ 3885 r2algs.html#Rijndael> 3886 3887 [BLOWFISH] Schneier, B. "Description of a New Variable-Length 3888 Key, 64-Bit Block Cipher (Blowfish)" Fast Software 3889 Encryption, Cambridge Security Workshop Proceedings 3890 (December 1993), Springer-Verlag, 1994, pp191-204 3891 <http://www.counterpane.com/bfsverlag.html> 3892 3893 [BZ2] J. Seward, jseward@acm.org, "The Bzip2 and libbzip2 3894 home page" 3895 <http://sources.redhat.com/bzip2/> 3896 [ELGAMAL] T. Elgamal, "A Public-Key Cryptosystem and a 3897 Signature Scheme Based on Discrete Logarithms," 3898 IEEE Transactions on Information Theory, v. IT-31, 3899 n. 4, 1985, pp. 469-472. 3900 3901 [FIPS180] Secure Hash Signature Standard (SHS) (FIPS PUB 3902 180-2). 3903 <http://csrc.nist.gov/publications/fips/ 3904 fips180-2/fips180-2withchangenotice.pdf> 3905 3906 [FIPS186] Digital Signature Standard (DSS) (FIPS PUB 186-2). 3907 <http://csrc.nist.gov/publications/fips/fips186-2/ 3908 fips186-2-change1.pdf> 3909 3910 [HAC] Alfred Menezes, Paul van Oorschot, and Scott 3911 Vanstone, "Handbook of Applied Cryptography," CRC 3912 Press, 1996. 3913 <http://www.cacr.math.uwaterloo.ca/hac/> 3914 [IDEA] Lai, X, "On the design and security of block 3915 ciphers", ETH Series in Information Processing, 3916 J.L. Massey (editor), Vol. 1, Hartung-Gorre Verlag 3917 Knostanz, Technische Hochschule (Zurich), 1992 3918 [ISO10646] ISO/IEC 10646-1:1993. International Standard -- 3919 3920Callas, et al. Expires Jan 08, 2006 [Page 70] 3921 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3922 3923 Information technology -- Universal Multiple-Octet 3924 Coded Character Set (UCS) -- Part 1: Architecture 3925 and Basic Multilingual Plane. 3926 [JFIF] JPEG File Interchange Format (Version 1.02). 3927 Eric Hamilton, C-Cube Microsystems, Milpitas, CA, 3928 September 1, 1992. 3929 3930 [RFC822] Crocker, D., "Standard for the format of ARPA 3931 Internet text messages", STD 11, RFC 822, August 3932 1982. 3933 [RFC1423] Balenson, D., "Privacy Enhancement for Internet 3934 Electronic Mail: Part III: Algorithms, Modes, and 3935 Identifiers", RFC 1423, October 1993. 3936 [RFC1641] Goldsmith, D. and M. Davis, "Using Unicode with 3937 MIME", RFC 1641, July 1994. 3938 [RFC1750] Eastlake, D., Crocker, S. and J. Schiller, 3939 "Randomness Recommendations for Security", RFC 3940 1750, December 1994. 3941 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format 3942 Specification version 1.3.", RFC 1951, May 1996. 3943 [RFC1991] Atkins, D., Stallings, W. and P. Zimmermann, "PGP 3944 Message Exchange Formats", RFC 1991, August 1996. 3945 [RFC2045] Borenstein, N. and N. Freed, "Multipurpose Internet 3946 Mail Extensions (MIME) Part One: Format of Internet 3947 Message Bodies.", RFC 2045, November 1996. 3948 [RFC2144] Adams, C., "The CAST-128 Encryption Algorithm", RFC 3949 2144, May 1997. 3950 [RFC2279] Yergeau., F., "UTF-8, a transformation format of 3951 Unicode and ISO 10646", RFC 2279, January 1998. 3952 [RFC2437] B. Kaliski and J. Staddon, " PKCS #1: RSA 3953 Cryptography Specifications Version 2.0", 3954 RFC 2437, October 1998. 3955 [RFC3156] M. Elkins, D. Del Torto, R. Levien, T. Roessler, 3956 "MIME Security with OpenPGP", RFC 3156, 3957 August 2001. 3958 [SCHNEIER] Schneier, B., "Applied Cryptography Second Edition: 3959 protocols, algorithms, and source code in C", 1996. 3960 [TWOFISH] B. Schneier, J. Kelsey, D. Whiting, D. Wagner, C. 3961 Hall, and N. Ferguson, "The Twofish Encryption 3962 Algorithm", John Wiley & Sons, 1999. 3963 396417. References (Non-Normative) 3965 3966 3967 [BLEICHENBACHER] Bleichenbacher, Daniel, "Generating Elgamal 3968 signatures without knowing the secret key," 3969 Eurocrypt 96. Note that the version in the 3970 proceedings has an error. A revised version is 3971 available at the time of writing from 3972 <ftp://ftp.inf.ethz.ch/pub/publications/papers/ti 3973 /isc/ElGamal.ps> 3974 [DONNERHACKE] Donnerhacke, L., et. al, "PGP263in - an improved 3975 3976Callas, et al. Expires Jan 08, 2006 [Page 71] 3977 INTERNET-DRAFT OpenPGP Message Format Jul 08, 2005 3978 3979 international version of PGP", ftp://ftp.iks- 3980 jena.de/mitarb/lutz/crypt/software/pgp/ 3981 [JKS02] Kahil Jallad, Jonathan Katz, Bruce Schneier 3982 "Implementation of Chosen-Ciphertext Attacks 3983 against PGP and GnuPG" 3984 http://www.counterpane.com/pgp-attack.html 3985 3986 [MZ05] Serge Mister, Robert Zuccherato, "An Attack on 3987 CFB Mode Encryption As Used By OpenPGP," IACR 3988 ePrint Archive: Report 2005/033, 8 Feb 2005 3989 http://eprint.iacr.org/2005/033 3990 3991 [RFC1983] Malkin, G., "Internet Users' Glossary", FYI 18, RFC 3992 1983, August 1996. 3993 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3994 Requirement Level", BCP 14, RFC 2119, March 1997. 3995 3996 3997 399818. Full Copyright Statement 3999 4000 Copyright 2005 by The Internet Society. All Rights Reserved. 4001 4002 This document is subject to the rights, licenses and restrictions 4003 contained in BCP 78, and except as set forth therein, the authors 4004 retain all their rights. 4005 4006 This document and the information contained herein are provided on 4007 an "AS IS" basis and the contributor, the organization he/she 4008 represents or is sponsored by (if any), the internet society and the 4009 internet engineering task force disclaim all warranties, express or 4010 implied, including but not limited to any warranty that the use of 4011 the information herein will not infringe any rights or any implied 4012 warranties of merchantability or fitness for a particular purpose. 4013 4014 This document and translations of it may be copied and furnished to 4015 others, and derivative works that comment on or otherwise explain it 4016 or assist in its implementation may be prepared, copied, published 4017 and distributed, in whole or in part, without restriction of any 4018 kind, provided that the above copyright notice and this paragraph 4019 are included on all such copies and derivative works. However, this 4020 document itself may not be modified in any way, such as by removing 4021 the copyright notice or references to the Internet Society or other 4022 Internet organizations, except as needed for the purpose of 4023 developing Internet standards in which case the procedures for 4024 copyrights defined in the Internet Standards process must be 4025 followed, or as required to translate it into languages other than 4026 English. 4027 4028 The limited permissions granted above are perpetual and will not be 4029 revoked by the Internet Society or its successors or assigns. 4030 4031 4032Callas, et al. Expires Jan 08, 2006 [Page 72] 4033 4034 4035