1Network Working Group Jon Callas 2Internet-Draft PGP Corporation 3Intended status: Standards Track 4Expires October 2007 Lutz Donnerhacke 5Apr 2007 6 7Obsoletes: 1991, 2440 Hal Finney 8 PGP Corporation 9 10 David Shaw 11 12 Rodney Thayer 13 14 OpenPGP Message Format 15 draft-ietf-openpgp-rfc2440bis-22 16 17 18Status of this Memo 19 20 By submitting this Internet-Draft, each author represents that any 21 applicable patent or other IPR claims of which he or she is aware 22 have been or will be disclosed, and any of which he or she becomes 23 aware will be disclosed, in accordance with Section 6 of BCP 79. 24 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF), its areas, and its working groups. Note that 27 other groups may also distribute working documents as 28 Internet-Drafts. 29 30 Internet-Drafts are draft documents valid for a maximum of six 31 months and may be updated, replaced, or obsoleted by other documents 32 at any time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 34 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/1id-abstracts.html 37 38 The list of Internet-Draft Shadow Directories can be accessed at 39 http://www.ietf.org/shadow.html 40 41Copyright Notice 42 43 Copyright (C) The IETF Trust (2007). 44 45Abstract 46 47 This document is maintained in order to publish all necessary 48 information needed to develop interoperable applications based on 49 the OpenPGP format. It is not a step-by-step cookbook for writing an 50 application. It describes only the format and methods needed to 51 read, check, generate, and write conforming packets crossing any 52 network. It does not deal with storage and implementation questions. 53 It does, however, discuss implementation issues necessary to avoid 54 security flaws. 55 56Callas, et al. Expires Oct 24, 2007 [Page 1] 57 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 58 59 OpenPGP software uses a combination of strong public-key and 60 symmetric cryptography to provide security services for electronic 61 communications and data storage. These services include 62 confidentiality, key management, authentication, and digital 63 signatures. This document specifies the message formats used in 64 OpenPGP. 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 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 Oct 24, 2007 [Page 2] 113 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 114 115Table of Contents 116 117 Status of this Memo 1 118 Copyright Notice 1 119 Abstract 1 120 Table of Contents 3 121 1. Introduction 7 122 1.1. Terms 7 123 2. General functions 7 124 2.1. Confidentiality via Encryption 8 125 2.2. Authentication via Digital signature 9 126 2.3. Compression 9 127 2.4. Conversion to Radix-64 9 128 2.5. Signature-Only Applications 10 129 3. Data Element Formats 10 130 3.1. Scalar numbers 10 131 3.2. Multiprecision Integers 10 132 3.3. Key IDs 11 133 3.4. Text 11 134 3.5. Time fields 11 135 3.6. Keyrings 11 136 3.7. String-to-key (S2K) specifiers 11 137 3.7.1. String-to-key (S2K) specifier types 11 138 3.7.1.1. Simple S2K 12 139 3.7.1.2. Salted S2K 12 140 3.7.1.3. Iterated and Salted S2K 12 141 3.7.2. String-to-key usage 13 142 3.7.2.1. Secret key encryption 13 143 3.7.2.2. Symmetric-key message encryption 14 144 4. Packet Syntax 14 145 4.1. Overview 14 146 4.2. Packet Headers 14 147 4.2.1. Old-Format Packet Lengths 15 148 4.2.2. New-Format Packet Lengths 15 149 4.2.2.1. One-Octet Lengths 16 150 4.2.2.2. Two-Octet Lengths 16 151 4.2.2.3. Five-Octet Lengths 16 152 4.2.2.4. Partial Body Lengths 16 153 4.2.3. Packet Length Examples 17 154 4.3. Packet Tags 17 155 5. Packet Types 18 156 5.1. Public-Key Encrypted Session Key Packets (Tag 1) 18 157 5.2. Signature Packet (Tag 2) 19 158 5.2.1. Signature Types 20 159 5.2.2. Version 3 Signature Packet Format 22 160 5.2.3. Version 4 Signature Packet Format 24 161 5.2.3.1. Signature Subpacket Specification 25 162 5.2.3.2. Signature Subpacket Types 27 163 5.2.3.3. Notes on Self-Signatures 27 164 5.2.3.4. Signature creation time 28 165 5.2.3.5. Issuer 28 166 5.2.3.6. Key expiration time 28 167 168Callas, et al. Expires Oct 24, 2007 [Page 3] 169 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 170 171 5.2.3.7. Preferred symmetric algorithms 28 172 5.2.3.8. Preferred hash algorithms 29 173 5.2.3.9. Preferred compression algorithms 29 174 5.2.3.10.Signature expiration time 29 175 5.2.3.11.Exportable Certification 29 176 5.2.3.12.Revocable 30 177 5.2.3.13.Trust signature 30 178 5.2.3.14.Regular expression 30 179 5.2.3.15.Revocation key 31 180 5.2.3.16.Notation Data 31 181 5.2.3.17.Key server preferences 32 182 5.2.3.18.Preferred key server 32 183 5.2.3.19.Primary User ID 32 184 5.2.3.20.Policy URI 33 185 5.2.3.21.Key Flags 33 186 5.2.3.22.Signer's User ID 34 187 5.2.3.23.Reason for Revocation 34 188 5.2.3.24.Features 35 189 5.2.3.25.Signature Target 35 190 5.2.3.26.Embedded Signature 36 191 5.2.4. Computing Signatures 36 192 5.2.4.1. Subpacket Hints 37 193 5.3. Symmetric-Key Encrypted Session Key Packets (Tag 3) 37 194 5.4. One-Pass Signature Packets (Tag 4) 38 195 5.5. Key Material Packet 39 196 5.5.1. Key Packet Variants 39 197 5.5.1.1. Public Key Packet (Tag 6) 39 198 5.5.1.2. Public Subkey Packet (Tag 14) 39 199 5.5.1.3. Secret Key Packet (Tag 5) 39 200 5.5.1.4. Secret Subkey Packet (Tag 7) 40 201 5.5.2. Public Key Packet Formats 40 202 5.5.3. Secret Key Packet Formats 41 203 5.6. Compressed Data Packet (Tag 8) 43 204 5.7. Symmetrically Encrypted Data Packet (Tag 9) 44 205 5.8. Marker Packet (Obsolete Literal Packet) (Tag 10) 44 206 5.9. Literal Data Packet (Tag 11) 45 207 5.10. Trust Packet (Tag 12) 46 208 5.11. User ID Packet (Tag 13) 46 209 5.12. User Attribute Packet (Tag 17) 46 210 5.12.1. The Image Attribute Subpacket 47 211 5.13. Sym. Encrypted Integrity Protected Data Packet (Tag 18) 47 212 5.14. Modification Detection Code Packet (Tag 19) 50 213 6. Radix-64 Conversions 51 214 6.1. An Implementation of the CRC-24 in "C" 51 215 6.2. Forming ASCII Armor 52 216 6.3. Encoding Binary in Radix-64 54 217 6.4. Decoding Radix-64 55 218 6.5. Examples of Radix-64 56 219 6.6. Example of an ASCII Armored Message 56 220 7. Cleartext signature framework 56 221 7.1. Dash-Escaped Text 57 222 8. Regular Expressions 58 223 224Callas, et al. Expires Oct 24, 2007 [Page 4] 225 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 226 227 9. Constants 58 228 9.1. Public Key Algorithms 59 229 9.2. Symmetric Key Algorithms 59 230 9.3. Compression Algorithms 60 231 9.4. Hash Algorithms 60 232 10. IANA Considerations 60 233 10.1. New String-to-Key specifier types 60 234 10.2. New Packets 61 235 10.2.1. User Attribute Types 61 236 10.2.1.1.Image Format Subpacket Types 61 237 10.2.2. New Signature Subpackets 61 238 10.2.2.1.Signature Notation Data Subpackets 61 239 10.2.2.2.Key Server Preference Extensions 62 240 10.2.2.3.Key Flags Extensions 62 241 10.2.2.4.Reason For Revocation Extensions 62 242 10.2.2.5.Implementation Features 62 243 10.2.3. New Packet Versions 62 244 10.3. New Algorithms 63 245 10.3.1. Public Key Algorithms 63 246 10.3.2. Symmetric Key Algorithms 63 247 10.3.3. Hash Algorithms 63 248 10.3.4. Compression Algorithms 64 249 11. Packet Composition 64 250 11.1. Transferable Public Keys 64 251 11.2. Transferable Secret Keys 65 252 11.3. OpenPGP Messages 65 253 11.4. Detached Signatures 66 254 12. Enhanced Key Formats 66 255 12.1. Key Structures 66 256 12.2. Key IDs and Fingerprints 67 257 13. Notes on Algorithms 68 258 13.1. PKCS#1 Encoding In OpenPGP 68 259 13.1.1. EME-PKCS1-v1_5-ENCODE 69 260 13.1.2. EME-PKCS1-v1_5-DECODE 69 261 13.1.3. EMSA-PKCS1-v1_5 70 262 13.2. Symmetric Algorithm Preferences 71 263 13.3. Other Algorithm Preferences 71 264 13.3.1. Compression Preferences 71 265 13.3.2. Hash Algorithm Preferences 72 266 13.4. Plaintext 72 267 13.5. RSA 72 268 13.6. DSA 73 269 13.7. Elgamal 73 270 13.8. Reserved Algorithm Numbers 73 271 13.9. OpenPGP CFB mode 74 272 13.10. Private or Experimental Parameters 75 273 13.11. Extension of the MDC System 75 274 13.12. Meta-Considerations for Expansion 76 275 14. Security Considerations 76 276 15. Implementation Nits 79 277 16. Authors' Addresses 80 278 17. References (Normative) 81 279 280Callas, et al. Expires Oct 24, 2007 [Page 5] 281 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 282 283 18. References (Informative) 83 284 19. Full Copyright Statement 84 285 20. Intellectual Property 84 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336Callas, et al. Expires Oct 24, 2007 [Page 6] 337 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 338 3391. Introduction 340 341 This document provides information on the message-exchange packet 342 formats used by OpenPGP to provide encryption, decryption, signing, 343 and key management functions. It is a revision of RFC 2440, "OpenPGP 344 Message Format", which itself replaces RFC 1991, "PGP Message 345 Exchange Formats." [RFC1991] [RFC2440] 346 3471.1. Terms 348 349 * OpenPGP - This is a definition for security software that uses 350 PGP 5.x as a basis, formalized in RFC 2440 and this document. 351 352 * PGP - Pretty Good Privacy. PGP is a family of software systems 353 developed by Philip R. Zimmermann from which OpenPGP is based. 354 355 * PGP 2.6.x - This version of PGP has many variants, hence the 356 term PGP 2.6.x. It used only RSA, MD5, and IDEA for its 357 cryptographic transforms. An informational RFC, RFC 1991, was 358 written describing this version of PGP. 359 360 * PGP 5.x - This version of PGP is formerly known as "PGP 3" in 361 the community and also in the predecessor of this document, RFC 362 1991. It has new formats and corrects a number of problems in 363 the PGP 2.6.x design. It is referred to here as PGP 5.x because 364 that software was the first release of the "PGP 3" code base. 365 366 * GnuPG - GNU Privacy Guard, also called GPG. GnuPG is an OpenPGP 367 implementation that avoids all encumbered algorithms. 368 Consequently, early versions of GnuPG did not include RSA public 369 keys. GnuPG may or may not have (depending on version) support 370 for IDEA or other encumbered algorithms. 371 372 "PGP", "Pretty Good", and "Pretty Good Privacy" are trademarks of 373 PGP Corporation and are used with permission. The term "OpenPGP" 374 refers to the protocol described in this and related documents. 375 376 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 377 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 378 document are to be interpreted as described in RFC 2119. 379 380 The key words "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME 381 FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG 382 APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in 383 this document when used to describe namespace allocation are to be 384 interpreted as described in RFC 2434. 385 3862. General functions 387 388 OpenPGP provides data integrity services for messages and data files 389 by using these core technologies: 390 391 392Callas, et al. Expires Oct 24, 2007 [Page 7] 393 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 394 395 - digital signatures 396 397 - encryption 398 399 - compression 400 401 - radix-64 conversion 402 403 In addition, OpenPGP provides key management and certificate 404 services, but many of these are beyond the scope of this document. 405 4062.1. Confidentiality via Encryption 407 408 OpenPGP combines symmetric-key encryption and public key encryption 409 to provide confidentiality. When made confidential, first the object 410 is encrypted using a symmetric encryption algorithm. Each symmetric 411 key is used only once, for a single object. A new "session key" is 412 generated as a random number for each object (sometimes referred to 413 as a session). Since it is used only once, the session key is bound 414 to the message and transmitted with it. To protect the key, it is 415 encrypted with the receiver's public key. The sequence is as 416 follows: 417 418 1. The sender creates a message. 419 420 2. The sending OpenPGP generates a random number to be used as a 421 session key for this message only. 422 423 3. The session key is encrypted using each recipient's public key. 424 These "encrypted session keys" start the message. 425 426 4. The sending OpenPGP encrypts the message using the session key, 427 which forms the remainder of the message. Note that the message 428 is also usually compressed. 429 430 5. The receiving OpenPGP decrypts the session key using the 431 recipient's private key. 432 433 6. The receiving OpenPGP decrypts the message using the session 434 key. If the message was compressed, it will be decompressed. 435 436 With symmetric-key encryption, an object may be encrypted with a 437 symmetric key derived from a passphrase (or other shared secret), or 438 a two-stage mechanism similar to the public-key method described 439 above in which a session key is itself encrypted with a symmetric 440 algorithm keyed from a shared secret. 441 442 Both digital signature and confidentiality services may be applied 443 to the same message. First, a signature is generated for the message 444 and attached to the message. Then, the message plus signature is 445 encrypted using a symmetric session key. Finally, the session key is 446 encrypted using public-key encryption and prefixed to the encrypted 447 448Callas, et al. Expires Oct 24, 2007 [Page 8] 449 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 450 451 block. 452 4532.2. Authentication via Digital signature 454 455 The digital signature uses a hash code or message digest algorithm, 456 and a public-key signature algorithm. The sequence is as follows: 457 458 1. The sender creates a message. 459 460 2. The sending software generates a hash code of the message. 461 462 3. The sending software generates a signature from the hash code 463 using the sender's private key. 464 465 4. The binary signature is attached to the message. 466 467 5. The receiving software keeps a copy of the message signature. 468 469 6. The receiving software generates a new hash code for the 470 received message and verifies it using the message's signature. 471 If the verification is successful, the message is accepted as 472 authentic. 473 4742.3. Compression 475 476 OpenPGP implementations SHOULD compress the message after applying 477 the signature but before encryption. 478 479 If an implementation does not implement compression, its authors 480 should be aware that most OpenPGP messages in the world are 481 compressed. Thus, it may even be wise for a space-constrained 482 implementation to implement decompression, but not compression. 483 484 Furthermore, compression has the added side-effect that some types 485 of attacks can be thwarted by the fact that slightly altered, 486 compressed data rarely uncompresses without severe errors. This is 487 hardly rigorous, but it is operationally useful. These attacks can 488 be rigorously prevented by implementing and using Modification 489 Detection Codes as described in sections following. 490 4912.4. Conversion to Radix-64 492 493 OpenPGP's underlying native representation for encrypted messages, 494 signature certificates, and keys is a stream of arbitrary octets. 495 Some systems only permit the use of blocks consisting of seven-bit, 496 printable text. For transporting OpenPGP's native raw binary octets 497 through channels that are not safe to raw binary data, a printable 498 encoding of these binary octets is needed. OpenPGP provides the 499 service of converting the raw 8-bit binary octet stream to a stream 500 of printable ASCII characters, called Radix-64 encoding or ASCII 501 Armor. 502 503 504Callas, et al. Expires Oct 24, 2007 [Page 9] 505 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 506 507 Implementations SHOULD provide Radix-64 conversions. 508 5092.5. Signature-Only Applications 510 511 OpenPGP is designed for applications that use both encryption and 512 signatures, but there are a number of problems that are solved by a 513 signature-only implementation. Although this specification requires 514 both encryption and signatures, it is reasonable for there to be 515 subset implementations that are non-conformant only in that they 516 omit encryption. 517 5183. Data Element Formats 519 520 This section describes the data elements used by OpenPGP. 521 5223.1. Scalar numbers 523 524 Scalar numbers are unsigned, and are always stored in big-endian 525 format. Using n[k] to refer to the kth octet being interpreted, the 526 value of a two-octet scalar is ((n[0] << 8) + n[1]). The value of a 527 four-octet scalar is ((n[0] << 24) + (n[1] << 16) + (n[2] << 8) + 528 n[3]). 529 5303.2. Multiprecision Integers 531 532 Multiprecision Integers (also called MPIs) are unsigned integers 533 used to hold large integers such as the ones used in cryptographic 534 calculations. 535 536 An MPI consists of two pieces: a two-octet scalar that is the length 537 of the MPI in bits followed by a string of octets that contain the 538 actual integer. 539 540 These octets form a big-endian number; a big-endian number can be 541 made into an MPI by prefixing it with the appropriate length. 542 543 Examples: 544 545 (all numbers are in hexadecimal) 546 547 The string of octets [00 01 01] forms an MPI with the value 1. The 548 string [00 09 01 FF] forms an MPI with the value of 511. 549 550 Additional rules: 551 552 The size of an MPI is ((MPI.length + 7) / 8) + 2 octets. 553 554 The length field of an MPI describes the length starting from its 555 most significant non-zero bit. Thus, the MPI [00 02 01] is not 556 formed correctly. It should be [00 01 01]. 557 558 559 560Callas, et al. Expires Oct 24, 2007 [Page 10] 561 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 562 563 Unused bits of an MPI MUST be zero. 564 565 Also note that when an MPI is encrypted, the length refers to the 566 plaintext MPI. It may be ill-formed in its ciphertext. 567 5683.3. Key IDs 569 570 A Key ID is an eight-octet scalar that identifies a key. 571 Implementations SHOULD NOT assume that Key IDs are unique. The 572 section, "Enhanced Key Formats" below describes how Key IDs are 573 formed. 574 5753.4. Text 576 577 Unless otherwise specified, the character set for text is the UTF-8 578 [RFC3629] encoding of Unicode [ISO10646]. 579 5803.5. Time fields 581 582 A time field is an unsigned four-octet number containing the number 583 of seconds elapsed since midnight, 1 January 1970 UTC. 584 5853.6. Keyrings 586 587 A keyring is a collection of one or more keys in a file or database. 588 Traditionally, a keyring is simply a sequential list of keys, but 589 may be any suitable database. It is beyond the scope of this 590 standard to discuss the details of keyrings or other databases. 591 5923.7. String-to-key (S2K) specifiers 593 594 String-to-key (S2K) specifiers are used to convert passphrase 595 strings into symmetric-key encryption/decryption keys. They are used 596 in two places, currently: to encrypt the secret part of private keys 597 in the private keyring, and to convert passphrases to encryption 598 keys for symmetrically encrypted messages. 599 6003.7.1. String-to-key (S2K) specifier types 601 602 There are three types of S2K specifiers currently supported, and 603 some reserved values: 604 605 ID S2K Type 606 -- --- ---- 607 0 Simple S2K 608 1 Salted S2K 609 2 Reserved value 610 3 Iterated and Salted S2K 611 100 to 110 Private/Experimental S2K 612 613 614 615 616Callas, et al. Expires Oct 24, 2007 [Page 11] 617 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 618 619 These are described as follows: 620 6213.7.1.1. Simple S2K 622 623 This directly hashes the string to produce the key data. See below 624 for how this hashing is done. 625 626 Octet 0: 0x00 627 Octet 1: hash algorithm 628 629 Simple S2K hashes the passphrase to produce the session key. The 630 manner in which this is done depends on the size of the session key 631 (which will depend on the cipher used) and the size of the hash 632 algorithm's output. If the hash size is greater than the session key 633 size, the high-order (leftmost) octets of the hash are used as the 634 key. 635 636 If the hash size is less than the key size, multiple instances of 637 the hash context are created -- enough to produce the required key 638 data. These instances are preloaded with 0, 1, 2, ... octets of 639 zeros (that is to say, the first instance has no preloading, the 640 second gets preloaded with 1 octet of zero, the third is preloaded 641 with two octets of zeros, and so forth). 642 643 As the data is hashed, it is given independently to each hash 644 context. Since the contexts have been initialized differently, they 645 will each produce different hash output. Once the passphrase is 646 hashed, the output data from the multiple hashes is concatenated, 647 first hash leftmost, to produce the key data, with any excess octets 648 on the right discarded. 649 6503.7.1.2. Salted S2K 651 652 This includes a "salt" value in the S2K specifier -- some arbitrary 653 data -- that gets hashed along with the passphrase string, to help 654 prevent dictionary attacks. 655 656 Octet 0: 0x01 657 Octet 1: hash algorithm 658 Octets 2-9: 8-octet salt value 659 660 Salted S2K is exactly like Simple S2K, except that the input to the 661 hash function(s) consists of the 8 octets of salt from the S2K 662 specifier, followed by the passphrase. 663 6643.7.1.3. Iterated and Salted S2K 665 666 This includes both a salt and an octet count. The salt is combined 667 with the passphrase and the resulting value is hashed repeatedly. 668 This further increases the amount of work an attacker must do to try 669 dictionary attacks. 670 671 672Callas, et al. Expires Oct 24, 2007 [Page 12] 673 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 674 675 Octet 0: 0x03 676 Octet 1: hash algorithm 677 Octets 2-9: 8-octet salt value 678 Octet 10: count, a one-octet, coded value 679 680 The count is coded into a one-octet number using the following 681 formula: 682 683 #define EXPBIAS 6 684 count = ((Int32)16 + (c & 15)) << ((c >> 4) + EXPBIAS); 685 686 The above formula is in C, where "Int32" is a type for a 32-bit 687 integer, and the variable "c" is the coded count, Octet 10. 688 689 Iterated-Salted S2K hashes the passphrase and salt data multiple 690 times. The total number of octets to be hashed is specified in the 691 encoded count in the S2K specifier. Note that the resulting count 692 value is an octet count of how many octets will be hashed, not an 693 iteration count. 694 695 Initially, one or more hash contexts are set up as with the other 696 S2K algorithms, depending on how many octets of key data are needed. 697 Then the salt, followed by the passphrase data is repeatedly hashed 698 until the number of octets specified by the octet count has been 699 hashed. The one exception is that if the octet count is less than 700 the size of the salt plus passphrase, the full salt plus passphrase 701 will be hashed even though that is greater than the octet count. 702 After the hashing is done the data is unloaded from the hash 703 context(s) as with the other S2K algorithms. 704 7053.7.2. String-to-key usage 706 707 Implementations SHOULD use salted or iterated-and-salted S2K 708 specifiers, as simple S2K specifiers are more vulnerable to 709 dictionary attacks. 710 7113.7.2.1. Secret key encryption 712 713 An S2K specifier can be stored in the secret keyring to specify how 714 to convert the passphrase to a key that unlocks the secret data. 715 Older versions of PGP just stored a cipher algorithm octet preceding 716 the secret data or a zero to indicate that the secret data was 717 unencrypted. The MD5 hash function was always used to convert the 718 passphrase to a key for the specified cipher algorithm. 719 720 For compatibility, when an S2K specifier is used, the special value 721 254 or 255 is stored in the position where the hash algorithm octet 722 would have been in the old data structure. This is then followed 723 immediately by a one-octet algorithm identifier, and then by the S2K 724 specifier as encoded above. 725 726 727 728Callas, et al. Expires Oct 24, 2007 [Page 13] 729 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 730 731 Therefore, preceding the secret data there will be one of these 732 possibilities: 733 734 0: secret data is unencrypted (no passphrase) 735 255 or 254: followed by algorithm octet and S2K specifier 736 Cipher alg: use Simple S2K algorithm using MD5 hash 737 738 This last possibility, the cipher algorithm number with an implicit 739 use of MD5 and IDEA, is provided for backward compatibility; it MAY 740 be understood, but SHOULD NOT be generated, and is deprecated. 741 742 These are followed by an Initial Vector of the same length as the 743 block size of the cipher for the decryption of the secret values, if 744 they are encrypted, and then the secret key values themselves. 745 7463.7.2.2. Symmetric-key message encryption 747 748 OpenPGP can create a Symmetric-key Encrypted Session Key (ESK) 749 packet at the front of a message. This is used to allow S2K 750 specifiers to be used for the passphrase conversion or to create 751 messages with a mix of symmetric-key ESKs and public-key ESKs. This 752 allows a message to be decrypted either with a passphrase or a 753 public key pair. 754 755 PGP 2.X always used IDEA with Simple string-to-key conversion when 756 encrypting a message with a symmetric algorithm. This is deprecated, 757 but MAY be used for backward-compatibility. 758 7594. Packet Syntax 760 761 This section describes the packets used by OpenPGP. 762 7634.1. Overview 764 765 An OpenPGP message is constructed from a number of records that are 766 traditionally called packets. A packet is a chunk of data that has a 767 tag specifying its meaning. An OpenPGP message, keyring, 768 certificate, and so forth consists of a number of packets. Some of 769 those packets may contain other OpenPGP packets (for example, a 770 compressed data packet, when uncompressed, contains OpenPGP 771 packets). 772 773 Each packet consists of a packet header, followed by the packet 774 body. The packet header is of variable length. 775 7764.2. Packet Headers 777 778 The first octet of the packet header is called the "Packet Tag." It 779 determines the format of the header and denotes the packet contents. 780 The remainder of the packet header is the length of the packet. 781 782 783 784Callas, et al. Expires Oct 24, 2007 [Page 14] 785 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 786 787 Note that the most significant bit is the left-most bit, called bit 788 7. A mask for this bit is 0x80 in hexadecimal. 789 790 +---------------+ 791 PTag |7 6 5 4 3 2 1 0| 792 +---------------+ 793 Bit 7 -- Always one 794 Bit 6 -- New packet format if set 795 796 PGP 2.6.x only uses old format packets. Thus, software that 797 interoperates with those versions of PGP must only use old format 798 packets. If interoperability is not an issue, the new packet format 799 is RECOMMENDED. Note that old format packets have four bits of 800 packet tags, and new format packets have six; some features cannot 801 be used and still be backward-compatible. 802 803 Also note that packets with a tag greater than or equal to 16 MUST 804 use new format packets. The old format packets can only express tags 805 less than or equal to 15. 806 807 Old format packets contain: 808 809 Bits 5-2 -- packet tag 810 Bits 1-0 - length-type 811 812 New format packets contain: 813 814 Bits 5-0 -- packet tag 815 8164.2.1. Old-Format Packet Lengths 817 818 The meaning of the length-type in old-format packets is: 819 820 0 - The packet has a one-octet length. The header is 2 octets long. 821 822 1 - The packet has a two-octet length. The header is 3 octets long. 823 824 2 - The packet has a four-octet length. The header is 5 octets long. 825 826 3 - The packet is of indeterminate length. The header is 1 octet 827 long, and the implementation must determine how long the packet 828 is. If the packet is in a file, this means that the packet 829 extends until the end of the file. In general, an implementation 830 SHOULD NOT use indeterminate length packets except where the end 831 of the data will be clear from the context, and even then it is 832 better to use a definite length, or a new-format header. The 833 new-format headers described below have a mechanism for 834 precisely encoding data of indeterminate length. 835 8364.2.2. New-Format Packet Lengths 837 838 New format packets have four possible ways of encoding length: 839 840Callas, et al. Expires Oct 24, 2007 [Page 15] 841 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 842 843 1. A one-octet Body Length header encodes packet lengths of up to 844 191 octets. 845 846 2. A two-octet Body Length header encodes packet lengths of 192 to 847 8383 octets. 848 849 3. A five-octet Body Length header encodes packet lengths of up to 850 4,294,967,295 (0xFFFFFFFF) octets in length. (This actually 851 encodes a four-octet scalar number.) 852 853 4. When the length of the packet body is not known in advance by 854 the issuer, Partial Body Length headers encode a packet of 855 indeterminate length, effectively making it a stream. 856 8574.2.2.1. One-Octet Lengths 858 859 A one-octet Body Length header encodes a length of from 0 to 191 860 octets. This type of length header is recognized because the one 861 octet value is less than 192. The body length is equal to: 862 863 bodyLen = 1st_octet; 864 8654.2.2.2. Two-Octet Lengths 866 867 A two-octet Body Length header encodes a length of from 192 to 8383 868 octets. It is recognized because its first octet is in the range 192 869 to 223. The body length is equal to: 870 871 bodyLen = ((1st_octet - 192) << 8) + (2nd_octet) + 192 872 8734.2.2.3. Five-Octet Lengths 874 875 A five-octet Body Length header consists of a single octet holding 876 the value 255, followed by a four-octet scalar. The body length is 877 equal to: 878 879 bodyLen = (2nd_octet << 24) | (3rd_octet << 16) | 880 (4th_octet << 8) | 5th_octet 881 882 This basic set of one, two, and five-octet lengths is also used 883 internally to some packets. 884 8854.2.2.4. Partial Body Lengths 886 887 A Partial Body Length header is one octet long and encodes the 888 length of only part of the data packet. This length is a power of 2, 889 from 1 to 1,073,741,824 (2 to the 30th power). It is recognized by 890 its one octet value that is greater than or equal to 224, and less 891 than 255. The partial body length is equal to: 892 893 894 895 896Callas, et al. Expires Oct 24, 2007 [Page 16] 897 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 898 899 partialBodyLen = 1 << (1st_octet & 0x1f); 900 901 Each Partial Body Length header is followed by a portion of the 902 packet body data. The Partial Body Length header specifies this 903 portion's length. Another length header (one octet, two-octet, 904 five-octet, or partial) follows that portion. The last length header 905 in the packet MUST NOT be a partial Body Length header. Partial Body 906 Length headers may only be used for the non-final parts of the 907 packet. 908 909 Note also that the last Body Length header can be a zero-length 910 header. 911 912 An implementation MAY use Partial Body Lengths for data packets, be 913 they literal, compressed, or encrypted. The first partial length 914 MUST be at least 512 octets long. Partial Body Lengths MUST NOT be 915 used for any other packet types. 916 9174.2.3. Packet Length Examples 918 919 These examples show ways that new-format packets might encode the 920 packet lengths. 921 922 A packet with length 100 may have its length encoded in one octet: 923 0x64. This is followed by 100 octets of data. 924 925 A packet with length 1723 may have its length coded in two octets: 926 0xC5, 0xFB. This header is followed by the 1723 octets of data. 927 928 A packet with length 100000 may have its length encoded in five 929 octets: 0xFF, 0x00, 0x01, 0x86, 0xA0. 930 931 It might also be encoded in the following octet stream: 0xEF, first 932 32768 octets of data; 0xE1, next two octets of data; 0xE0, next one 933 octet of data; 0xF0, next 65536 octets of data; 0xC5, 0xDD, last 934 1693 octets of data. This is just one possible encoding, and many 935 variations are possible on the size of the Partial Body Length 936 headers, as long as a regular Body Length header encodes the last 937 portion of the data. 938 939 Please note that in all of these explanations, the total length of 940 the packet is the length of the header(s) plus the length of the 941 body. 942 9434.3. Packet Tags 944 945 The packet tag denotes what type of packet the body holds. Note that 946 old format headers can only have tags less than 16, whereas new 947 format headers can have tags as great as 63. The defined tags (in 948 decimal) are: 949 950 951 952Callas, et al. Expires Oct 24, 2007 [Page 17] 953 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 954 955 0 -- Reserved - a packet tag MUST NOT have this value 956 1 -- Public-Key Encrypted Session Key Packet 957 2 -- Signature Packet 958 3 -- Symmetric-Key Encrypted Session Key Packet 959 4 -- One-Pass Signature Packet 960 5 -- Secret Key Packet 961 6 -- Public Key Packet 962 7 -- Secret Subkey Packet 963 8 -- Compressed Data Packet 964 9 -- Symmetrically Encrypted Data Packet 965 10 -- Marker Packet 966 11 -- Literal Data Packet 967 12 -- Trust Packet 968 13 -- User ID Packet 969 14 -- Public Subkey Packet 970 17 -- User Attribute Packet 971 18 -- Sym. Encrypted and Integrity Protected Data Packet 972 19 -- Modification Detection Code Packet 973 60 to 63 -- Private or Experimental Values 974 9755. Packet Types 976 9775.1. Public-Key Encrypted Session Key Packets (Tag 1) 978 979 A Public-Key Encrypted Session Key packet holds the session key used 980 to encrypt a message. Zero or more Public-Key Encrypted Session Key 981 packets and/or Symmetric-Key Encrypted Session Key packets may 982 precede a Symmetrically Encrypted Data Packet, which holds an 983 encrypted message. The message is encrypted with the session key, 984 and the session key is itself encrypted and stored in the Encrypted 985 Session Key packet(s). The Symmetrically Encrypted Data Packet is 986 preceded by one Public-Key Encrypted Session Key packet for each 987 OpenPGP key to which the message is encrypted. The recipient of the 988 message finds a session key that is encrypted to their public key, 989 decrypts the session key, and then uses the session key to decrypt 990 the message. 991 992 The body of this packet consists of: 993 994 - A one-octet number giving the version number of the packet type. 995 The currently defined value for packet version is 3. 996 997 - An eight-octet number that gives the key ID of the public key 998 that the session key is encrypted to. If the session key is 999 encrypted to a subkey then the key ID of this subkey is used 1000 here instead of the key ID of the primary key. 1001 1002 - A one-octet number giving the public key algorithm used. 1003 1004 - A string of octets that is the encrypted session key. This 1005 string takes up the remainder of the packet, and its contents 1006 are dependent on the public key algorithm used. 1007 1008Callas, et al. Expires Oct 24, 2007 [Page 18] 1009 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1010 1011 Algorithm Specific Fields for RSA encryption 1012 1013 - multiprecision integer (MPI) of RSA encrypted value m**e mod n. 1014 1015 Algorithm Specific Fields for Elgamal encryption: 1016 1017 - MPI of Elgamal (Diffie-Hellman) value g**k mod p. 1018 1019 - MPI of Elgamal (Diffie-Hellman) value m * y**k mod p. 1020 1021 The value "m" in the above formulas is derived from the session key 1022 as follows. First the session key is prefixed with a one-octet 1023 algorithm identifier that specifies the symmetric encryption 1024 algorithm used to encrypt the following Symmetrically Encrypted Data 1025 Packet. Then a two-octet checksum is appended which is equal to the 1026 sum of the preceding session key octets, not including the algorithm 1027 identifier, modulo 65536. This value is then encoded as described in 1028 PKCS#1 block encoding EME-PKCS1-v1_5 in Section 12.1 of RFC 3447 to 1029 form the "m" value used in the formulas above. See Section 13.1 of 1030 this document for notes on OpenPGP's use of PKCS#1. 1031 1032 Note that when an implementation forms several PKESKs with one 1033 session key, forming a message that can be decrypted by several 1034 keys, the implementation MUST make a new PKCS#1 encoding for each 1035 key. 1036 1037 An implementation MAY accept or use a Key ID of zero as a "wild 1038 card" or "speculative" Key ID. In this case, the receiving 1039 implementation would try all available private keys, checking for a 1040 valid decrypted session key. This format helps reduce traffic 1041 analysis of messages. 1042 10435.2. Signature Packet (Tag 2) 1044 1045 A signature packet describes a binding between some public key and 1046 some data. The most common signatures are a signature of a file or a 1047 block of text, and a signature that is a certification of a User ID. 1048 1049 Two versions of signature packets are defined. Version 3 provides 1050 basic signature information, while version 4 provides an expandable 1051 format with subpackets that can specify more information about the 1052 signature. PGP 2.6.x only accepts version 3 signatures. 1053 1054 Implementations SHOULD accept V3 signatures. Implementations SHOULD 1055 generate V4 signatures. 1056 1057 Note that if an implementation is creating an encrypted and signed 1058 message that is encrypted to a V3 key, it is reasonable to create a 1059 V3 signature. 1060 1061 1062 1063 1064Callas, et al. Expires Oct 24, 2007 [Page 19] 1065 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1066 10675.2.1. Signature Types 1068 1069 There are a number of possible meanings for a signature, which are 1070 indicated in a signature type octet in any given signature. Please 1071 note that the vagueness of these meanings is not a flaw, but a 1072 feature of the system. Because OpenPGP places final authority for 1073 validity upon the receiver of a signature, it may be that one 1074 signer's casual act might be more rigorous than some other 1075 authority's positive act. See section 5.2.4, "Computing Signatures," 1076 for detailed information on how to compute and verify signatures of 1077 each type. 1078 1079 These meanings are: 1080 1081 0x00: Signature of a binary document. 1082 This means the signer owns it, created it, or certifies that it 1083 has not been modified. 1084 1085 0x01: Signature of a canonical text document. 1086 This means the signer owns it, created it, or certifies that it 1087 has not been modified. The signature is calculated over the text 1088 data with its line endings converted to <CR><LF>. 1089 1090 0x02: Standalone signature. 1091 This signature is a signature of only its own subpacket 1092 contents. It is calculated identically to a signature over a 1093 zero-length binary document. Note that it doesn't make sense to 1094 have a V3 standalone signature. 1095 1096 0x10: Generic certification of a User ID and Public Key packet. 1097 The issuer of this certification does not make any particular 1098 assertion as to how well the certifier has checked that the 1099 owner of the key is in fact the person described by the User ID. 1100 1101 0x11: Persona certification of a User ID and Public Key packet. 1102 The issuer of this certification has not done any verification 1103 of the claim that the owner of this key is the User ID 1104 specified. 1105 1106 0x12: Casual certification of a User ID and Public Key packet. 1107 The issuer of this certification has done some casual 1108 verification of the claim of identity. 1109 1110 0x13: Positive certification of a User ID and Public Key packet. 1111 The issuer of this certification has done substantial 1112 verification of the claim of identity. 1113 1114 Most OpenPGP implementations make their "key signatures" as 0x10 1115 certifications. Some implementations can issue 0x11-0x13 1116 certifications, but few differentiate between the types. 1117 1118 1119 1120Callas, et al. Expires Oct 24, 2007 [Page 20] 1121 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1122 1123 0x18: Subkey Binding Signature 1124 This signature is a statement by the top-level signing key that 1125 indicates that it owns the subkey. This signature is calculated 1126 directly on the primary key and subkey, and not on any User ID 1127 or other packets. A signature that binds a signing subkey MUST 1128 have an embedded signature subpacket in this binding signature 1129 which contains a 0x19 signature made by the signing subkey on 1130 the primary key and subkey. 1131 1132 0x19 Primary Key Binding Signature 1133 This signature is a statement by a signing subkey, indicating 1134 that it is owned by the primary key and subkey. This signature 1135 is calculated the same way as a 0x18 signature: directly on the 1136 primary key and subkey, and not on any User ID or other packets. 1137 1138 0x1F: Signature directly on a key 1139 This signature is calculated directly on a key. It binds the 1140 information in the signature subpackets to the key, and is 1141 appropriate to be used for subpackets that provide information 1142 about the key, such as the revocation key subpacket. It is also 1143 appropriate for statements that non-self certifiers want to make 1144 about the key itself, rather than the binding between a key and 1145 a name. 1146 1147 0x20: Key revocation signature 1148 The signature is calculated directly on the key being revoked. A 1149 revoked key is not to be used. Only revocation signatures by the 1150 key being revoked, or by an authorized revocation key, should be 1151 considered valid revocation signatures. 1152 1153 0x28: Subkey revocation signature 1154 The signature is calculated directly on the subkey being 1155 revoked. A revoked subkey is not to be used. Only revocation 1156 signatures by the top-level signature key that is bound to this 1157 subkey, or by an authorized revocation key, should be considered 1158 valid revocation signatures. 1159 1160 0x30: Certification revocation signature 1161 This signature revokes an earlier User ID certification 1162 signature (signature class 0x10 through 0x13) or direct-key 1163 signature (0x1F). It should be issued by the same key that 1164 issued the revoked signature or an authorized revocation key. 1165 The signature is computed over the same data as the certificate 1166 that it revokes, and should have a later creation date than that 1167 certificate. 1168 1169 0x40: Timestamp signature. 1170 This signature is only meaningful for the timestamp contained in 1171 it. 1172 1173 1174 1175 1176Callas, et al. Expires Oct 24, 2007 [Page 21] 1177 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1178 1179 0x50: Third-Party Confirmation signature. 1180 This signature is a signature over some other OpenPGP signature 1181 packet(s). It is analogous to a notary seal on the signed data. 1182 A third-party signature SHOULD include Signature Target 1183 subpacket(s) to give easy identification. Note that we really do 1184 mean SHOULD. There are plausible uses for this (such as a blind 1185 party that only sees the signature, not the key nor source 1186 document) that cannot include a target subpacket. 1187 11885.2.2. Version 3 Signature Packet Format 1189 1190 The body of a version 3 Signature Packet contains: 1191 1192 - One-octet version number (3). 1193 1194 - One-octet length of following hashed material. MUST be 5. 1195 1196 - One-octet signature type. 1197 1198 - Four-octet creation time. 1199 1200 - Eight-octet key ID of signer. 1201 1202 - One-octet public key algorithm. 1203 1204 - One-octet hash algorithm. 1205 1206 - Two-octet field holding left 16 bits of signed hash value. 1207 1208 - One or more multiprecision integers comprising the signature. 1209 This portion is algorithm specific, as described below. 1210 1211 The concatenation of the data to be signed, the signature type and 1212 creation time from the signature packet (5 additional octets) is 1213 hashed. The resulting hash value is used in the signature algorithm. 1214 The high 16 bits (first two octets) of the hash are included in the 1215 signature packet to provide a quick test to reject some invalid 1216 signatures. 1217 1218 Algorithm Specific Fields for RSA signatures: 1219 1220 - multiprecision integer (MPI) of RSA signature value m**d mod n. 1221 1222 Algorithm Specific Fields for DSA signatures: 1223 1224 - MPI of DSA value r. 1225 1226 - MPI of DSA value s. 1227 1228 The signature calculation is based on a hash of the signed data, as 1229 described above. The details of the calculation are different for 1230 DSA signatures than for RSA signatures. 1231 1232Callas, et al. Expires Oct 24, 2007 [Page 22] 1233 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1234 1235 With RSA signatures, the hash value is encoded as described in 1236 PKCS#1 section 9.2.1 of RFC 3447 encoded using PKCS#1 encoding type 1237 EMSA-PKCS1-v1_5 as described in section 12.1 of RFC 3447. This 1238 requires inserting the hash value as an octet string into an ASN.1 1239 structure. The object identifier for the type of hash being used is 1240 included in the structure. The hexadecimal representations for the 1241 currently defined hash algorithms are: 1242 1243 - MD5: 0x2A, 0x86, 0x48, 0x86, 0xF7, 0x0D, 0x02, 0x05 1244 1245 - RIPEMD-160: 0x2B, 0x24, 0x03, 0x02, 0x01 1246 1247 - SHA-1: 0x2B, 0x0E, 0x03, 0x02, 0x1A 1248 1249 - SHA224: 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x04 1250 1251 - SHA256: 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01 1252 1253 - SHA384: 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x02 1254 1255 - SHA512: 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x03 1256 1257 The ASN.1 OIDs are: 1258 1259 - MD5: 1.2.840.113549.2.5 1260 1261 - RIPEMD-160: 1.3.36.3.2.1 1262 1263 - SHA-1: 1.3.14.3.2.26 1264 1265 - SHA224: 2.16.840.1.101.3.4.2.4 1266 1267 - SHA256: 2.16.840.1.101.3.4.2.1 1268 1269 - SHA384: 2.16.840.1.101.3.4.2.2 1270 1271 - SHA512: 2.16.840.1.101.3.4.2.3 1272 1273 The full hash prefixes for these are: 1274 1275 MD5: 0x30, 0x20, 0x30, 0x0C, 0x06, 0x08, 0x2A, 0x86, 1276 0x48, 0x86, 0xF7, 0x0D, 0x02, 0x05, 0x05, 0x00, 1277 0x04, 0x10 1278 1279 RIPEMD-160: 0x30, 0x21, 0x30, 0x09, 0x06, 0x05, 0x2B, 0x24, 1280 0x03, 0x02, 0x01, 0x05, 0x00, 0x04, 0x14 1281 1282 SHA-1: 0x30, 0x21, 0x30, 0x09, 0x06, 0x05, 0x2b, 0x0E, 1283 0x03, 0x02, 0x1A, 0x05, 0x00, 0x04, 0x14 1284 1285 1286 1287 1288Callas, et al. Expires Oct 24, 2007 [Page 23] 1289 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1290 1291 SHA224: 0x30, 0x31, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 1292 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x04, 0x05, 1293 0x00, 0x04, 0x1C 1294 1295 SHA256: 0x30, 0x31, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 1296 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01, 0x05, 1297 0x00, 0x04, 0x20 1298 1299 SHA384: 0x30, 0x41, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 1300 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x02, 0x05, 1301 0x00, 0x04, 0x30 1302 1303 SHA512: 0x30, 0x51, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 1304 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x03, 0x05, 1305 0x00, 0x04, 0x40 1306 1307 DSA signatures MUST use hashes that are equal in size to the number 1308 of bits of q, the group generated by the DSA key's generator value. 1309 If the output size of the chosen hash is larger than the number of 1310 bits of q, the hash result is truncated to fit by taking the number 1311 of leftmost bits equal to the number of bits of q. This (possibly 1312 truncated) hash function result is treated as a number and used 1313 directly in the DSA signature algorithm. 1314 13155.2.3. Version 4 Signature Packet Format 1316 1317 The body of a version 4 Signature Packet contains: 1318 1319 - One-octet version number (4). 1320 1321 - One-octet signature type. 1322 1323 - One-octet public key algorithm. 1324 1325 - One-octet hash algorithm. 1326 1327 - Two-octet scalar octet count for following hashed subpacket 1328 data. Note that this is the length in octets of all of the 1329 hashed subpackets; a pointer incremented by this number will 1330 skip over the hashed subpackets. 1331 1332 - Hashed subpacket data set. (zero or more subpackets) 1333 1334 - Two-octet scalar octet count for the following unhashed 1335 subpacket data. Note that this is the length in octets of all of 1336 the unhashed subpackets; a pointer incremented by this number 1337 will skip over the unhashed subpackets. 1338 1339 - Unhashed subpacket data set. (zero or more subpackets) 1340 1341 1342 1343 1344Callas, et al. Expires Oct 24, 2007 [Page 24] 1345 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1346 1347 - Two-octet field holding the left 16 bits of the signed hash 1348 value. 1349 1350 - One or more multiprecision integers comprising the signature. 1351 This portion is algorithm specific, as described above. 1352 1353 The concatenation of the data being signed and the signature data 1354 from the version number through the hashed subpacket data 1355 (inclusive) is hashed. The resulting hash value is what is signed. 1356 The left 16 bits of the hash are included in the signature packet to 1357 provide a quick test to reject some invalid signatures. 1358 1359 There are two fields consisting of signature subpackets. The first 1360 field is hashed with the rest of the signature data, while the 1361 second is unhashed. The second set of subpackets is not 1362 cryptographically protected by the signature and should include only 1363 advisory information. 1364 1365 The algorithms for converting the hash function result to a 1366 signature are described in a section below. 1367 13685.2.3.1. Signature Subpacket Specification 1369 1370 A subpacket data set consists of zero or more signature subpackets. 1371 In signature packets the subpacket data set is preceded by a 1372 two-octet scalar count of the length in octets of all the 1373 subpackets. A pointer incremented by this number will skip over the 1374 subpacket data set. 1375 1376 Each subpacket consists of a subpacket header and a body. The header 1377 consists of: 1378 1379 - the subpacket length (1, 2, or 5 octets) 1380 1381 - the subpacket type (1 octet) 1382 1383 and is followed by the subpacket specific data. 1384 1385 The length includes the type octet but not this length. Its format 1386 is similar to the "new" format packet header lengths, but cannot 1387 have partial body lengths. That is: 1388 1389 if the 1st octet < 192, then 1390 lengthOfLength = 1 1391 subpacketLen = 1st_octet 1392 1393 if the 1st octet >= 192 and < 255, then 1394 lengthOfLength = 2 1395 subpacketLen = ((1st_octet - 192) << 8) + (2nd_octet) + 192 1396 1397 1398 1399 1400Callas, et al. Expires Oct 24, 2007 [Page 25] 1401 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1402 1403 if the 1st octet = 255, then 1404 lengthOfLength = 5 1405 subpacket length = [four-octet scalar starting at 2nd_octet] 1406 1407 The value of the subpacket type octet may be: 1408 1409 0 = reserved 1410 1 = reserved 1411 2 = signature creation time 1412 3 = signature expiration time 1413 4 = exportable certification 1414 5 = trust signature 1415 6 = regular expression 1416 7 = revocable 1417 8 = reserved 1418 9 = key expiration time 1419 10 = placeholder for backward compatibility 1420 11 = preferred symmetric algorithms 1421 12 = revocation key 1422 13 = reserved 1423 14 = reserved 1424 15 = reserved 1425 16 = issuer key ID 1426 17 = reserved 1427 18 = reserved 1428 19 = reserved 1429 20 = notation data 1430 21 = preferred hash algorithms 1431 22 = preferred compression algorithms 1432 23 = key server preferences 1433 24 = preferred key server 1434 25 = primary User ID 1435 26 = policy URI 1436 27 = key flags 1437 28 = signer's User ID 1438 29 = reason for revocation 1439 30 = features 1440 31 = signature target 1441 32 = embedded signature 1442 1443 100 to 110 = private or experimental 1444 1445 An implementation SHOULD ignore any subpacket of a type that it does 1446 not recognize. 1447 1448 Bit 7 of the subpacket type is the "critical" bit. If set, it 1449 denotes that the subpacket is one that is critical for the evaluator 1450 of the signature to recognize. If a subpacket is encountered that is 1451 marked critical but is unknown to the evaluating software, the 1452 evaluator SHOULD consider the signature to be in error. 1453 1454 1455 1456Callas, et al. Expires Oct 24, 2007 [Page 26] 1457 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1458 1459 An evaluator may "recognize" a subpacket, but not implement it. The 1460 purpose of the critical bit is to allow the signer to tell an 1461 evaluator that it would prefer a new, unknown feature to generate an 1462 error than be ignored. 1463 1464 Implementations SHOULD implement "preferences" and the "reason for 1465 revocation" subpackets. Note, however, that if an implementation 1466 chooses not to implement some of the preferences, it is required to 1467 behave in a polite manner to respect the wishes of those users who 1468 do implement these preferences. 1469 14705.2.3.2. Signature Subpacket Types 1471 1472 A number of subpackets are currently defined. Some subpackets apply 1473 to the signature itself and some are attributes of the key. 1474 Subpackets that are found on a self-signature are placed on a 1475 certification made by the key itself. Note that a key may have more 1476 than one User ID, and thus may have more than one self-signature, 1477 and differing subpackets. 1478 1479 A subpacket may be found either in the hashed or unhashed subpacket 1480 sections of a signature. If a subpacket is not hashed, then the 1481 information in it cannot be considered definitive because it is not 1482 part of the signature proper. 1483 14845.2.3.3. Notes on Self-Signatures 1485 1486 A self-signature is a binding signature made by the key the 1487 signature refers to. There are three types of self-signatures, the 1488 certification signatures (types 0x10-0x13), the direct-key signature 1489 (type 0x1f), and the subkey binding signature (type 0x18). For 1490 certification self-signatures, each User ID may have a 1491 self-signature, and thus different subpackets in those 1492 self-signatures. For subkey binding signatures, each subkey in fact 1493 has a self-signature. Subpackets that appear in a certification 1494 self-signature apply to the username, and subpackets that appear in 1495 the subkey self-signature apply to the subkey. Lastly, subpackets on 1496 the direct-key signature apply to the entire key. 1497 1498 Implementing software should interpret a self-signature's preference 1499 subpackets as narrowly as possible. For example, suppose a key has 1500 two usernames, Alice and Bob. Suppose that Alice prefers the 1501 symmetric algorithm CAST5, and Bob prefers IDEA or TripleDES. If the 1502 software locates this key via Alice's name, then the preferred 1503 algorithm is CAST5, if software locates the key via Bob's name, then 1504 the preferred algorithm is IDEA. If the key is located by key ID, 1505 the algorithm of the primary User ID of the key provides the 1506 preferred symmetric algorithm. 1507 1508 Revoking a self-signature or allowing it to expire has a semantic 1509 meaning that varies with the signature type. Revoking the 1510 self-signature on a User ID effectively retires that user name. The 1511 1512Callas, et al. Expires Oct 24, 2007 [Page 27] 1513 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1514 1515 self-signature is a statement, "My name X is tied to my signing key 1516 K" and is corroborated by other users' certifications. If another 1517 user revokes their certification, they are effectively saying that 1518 they no longer believe that name and that key are tied together. 1519 Similarly, if the user themselves revokes their self-signature, it 1520 means the user no longer goes by that name, no longer has that email 1521 address, etc. Revoking a binding signature effectively retires that 1522 subkey. Revoking a direct-key signature cancels that signature. 1523 Please see the "Reason for Revocation" subpacket below for more 1524 relevant detail. 1525 1526 Since a self-signature contains important information about the 1527 key's use, an implementation SHOULD allow the user to rewrite the 1528 self-signature, and important information in it, such as preferences 1529 and key expiration. 1530 1531 It is good practice to verify that a self-signature imported into an 1532 implementation doesn't advertise features that the implementation 1533 doesn't support, rewriting the signature as appropriate. 1534 1535 An implementation that encounters multiple self-signatures on the 1536 same object may resolve the ambiguity in any way it sees fit, but it 1537 is RECOMMENDED that priority be given to the most recent 1538 self-signature. 1539 15405.2.3.4. Signature creation time 1541 1542 (4 octet time field) 1543 1544 The time the signature was made. 1545 1546 MUST be present in the hashed area. 1547 15485.2.3.5. Issuer 1549 1550 (8 octet key ID) 1551 1552 The OpenPGP key ID of the key issuing the signature. 1553 15545.2.3.6. Key expiration time 1555 1556 (4 octet time field) 1557 1558 The validity period of the key. This is the number of seconds after 1559 the key creation time that the key expires. If this is not present 1560 or has a value of zero, the key never expires. This is found only on 1561 a self-signature. 1562 15635.2.3.7. Preferred symmetric algorithms 1564 1565 (array of one-octet values) 1566 1567 1568Callas, et al. Expires Oct 24, 2007 [Page 28] 1569 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1570 1571 Symmetric algorithm numbers that indicate which algorithms the key 1572 holder prefers to use. The subpacket body is an ordered list of 1573 octets with the most preferred listed first. It is assumed that only 1574 algorithms listed are supported by the recipient's software. 1575 Algorithm numbers are in section 9. This is only found on a 1576 self-signature. 1577 15785.2.3.8. Preferred hash algorithms 1579 1580 (array of one-octet values) 1581 1582 Message digest algorithm numbers that indicate which algorithms the 1583 key holder prefers to receive. Like the preferred symmetric 1584 algorithms, the list is ordered. Algorithm numbers are in section 9. 1585 This is only found on a self-signature. 1586 15875.2.3.9. Preferred compression algorithms 1588 1589 (array of one-octet values) 1590 1591 Compression algorithm numbers that indicate which algorithms the key 1592 holder prefers to use. Like the preferred symmetric algorithms, the 1593 list is ordered. Algorithm numbers are in section 9. If this 1594 subpacket is not included, ZIP is preferred. A zero denotes that 1595 uncompressed data is preferred; the key holder's software might have 1596 no compression software in that implementation. This is only found 1597 on a self-signature. 1598 15995.2.3.10. Signature expiration time 1600 1601 (4 octet time field) 1602 1603 The validity period of the signature. This is the number of seconds 1604 after the signature creation time that the signature expires. If 1605 this is not present or has a value of zero, it never expires. 1606 16075.2.3.11. Exportable Certification 1608 1609 (1 octet of exportability, 0 for not, 1 for exportable) 1610 1611 This subpacket denotes whether a certification signature is 1612 "exportable," to be used by other users than the signature's issuer. 1613 The packet body contains a Boolean flag indicating whether the 1614 signature is exportable. If this packet is not present, the 1615 certification is exportable; it is equivalent to a flag containing a 1616 1. 1617 1618 Non-exportable, or "local," certifications are signatures made by a 1619 user to mark a key as valid within that user's implementation only. 1620 Thus, when an implementation prepares a user's copy of a key for 1621 transport to another user (this is the process of "exporting" the 1622 key), any local certification signatures are deleted from the key. 1623 1624Callas, et al. Expires Oct 24, 2007 [Page 29] 1625 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1626 1627 The receiver of a transported key "imports" it, and likewise trims 1628 any local certifications. In normal operation, there won't be any, 1629 assuming the import is performed on an exported key. However, there 1630 are instances where this can reasonably happen. For example, if an 1631 implementation allows keys to be imported from a key database in 1632 addition to an exported key, then this situation can arise. 1633 1634 Some implementations do not represent the interest of a single user 1635 (for example, a key server). Such implementations always trim local 1636 certifications from any key they handle. 1637 16385.2.3.12. Revocable 1639 1640 (1 octet of revocability, 0 for not, 1 for revocable) 1641 1642 Signature's revocability status. The packet body contains a Boolean 1643 flag indicating whether the signature is revocable. Signatures that 1644 are not revocable have any later revocation signatures ignored. They 1645 represent a commitment by the signer that he cannot revoke his 1646 signature for the life of his key. If this packet is not present, 1647 the signature is revocable. 1648 16495.2.3.13. Trust signature 1650 1651 (1 octet "level" (depth), 1 octet of trust amount) 1652 1653 Signer asserts that the key is not only valid, but also trustworthy, 1654 at the specified level. Level 0 has the same meaning as an ordinary 1655 validity signature. Level 1 means that the signed key is asserted to 1656 be a valid trusted introducer, with the 2nd octet of the body 1657 specifying the degree of trust. Level 2 means that the signed key is 1658 asserted to be trusted to issue level 1 trust signatures, i.e. that 1659 it is a "meta introducer". Generally, a level n trust signature 1660 asserts that a key is trusted to issue level n-1 trust signatures. 1661 The trust amount is in a range from 0-255, interpreted such that 1662 values less than 120 indicate partial trust and values of 120 or 1663 greater indicate complete trust. Implementations SHOULD emit values 1664 of 60 for partial trust and 120 for complete trust. 1665 16665.2.3.14. Regular expression 1667 1668 (null-terminated regular expression) 1669 1670 Used in conjunction with trust signature packets (of level > 0) to 1671 limit the scope of trust that is extended. Only signatures by the 1672 target key on User IDs that match the regular expression in the body 1673 of this packet have trust extended by the trust signature subpacket. 1674 The regular expression uses the same syntax as the Henry Spencer's 1675 "almost public domain" regular expression package. A description of 1676 the syntax is found in a section below. 1677 1678 1679 1680Callas, et al. Expires Oct 24, 2007 [Page 30] 1681 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1682 16835.2.3.15. Revocation key 1684 1685 (1 octet of class, 1 octet of PK algorithm ID, 20 octets of 1686 fingerprint) 1687 1688 Authorizes the specified key to issue revocation signatures for this 1689 key. Class octet must have bit 0x80 set. If the bit 0x40 is set, 1690 then this means that the revocation information is sensitive. Other 1691 bits are for future expansion to other kinds of authorizations. This 1692 is found on a self-signature. 1693 1694 If the "sensitive" flag is set, the keyholder feels this subpacket 1695 contains private trust information that describes a real-world 1696 sensitive relationship. If this flag is set, implementations SHOULD 1697 NOT export this signature to other users except in cases where the 1698 data needs to be available: when the signature is being sent to the 1699 designated revoker, or when it is accompanied by a revocation 1700 signature from that revoker. Note that it may be appropriate to 1701 isolate this subpacket within a separate signature so that it is not 1702 combined with other subpackets that need to be exported. 1703 17045.2.3.16. Notation Data 1705 1706 (4 octets of flags, 2 octets of name length (M), 1707 2 octets of value length (N), 1708 M octets of name data, 1709 N octets of value data) 1710 1711 This subpacket describes a "notation" on the signature that the 1712 issuer wishes to make. The notation has a name and a value, each of 1713 which are strings of octets. There may be more than one notation in 1714 a signature. Notations can be used for any extension the issuer of 1715 the signature cares to make. The "flags" field holds four octets of 1716 flags. 1717 1718 All undefined flags MUST be zero. Defined flags are: 1719 1720 First octet: 0x80 = human-readable. This note value is text. 1721 Other octets: none. 1722 1723 Notation names are arbitrary strings encoded in UTF-8. They reside 1724 two name spaces: The IETF name space and the user name space. 1725 1726 The IETF name space is registered with IANA. These names MUST NOT 1727 contain the "@" character (0x40). This this is a tag for the user 1728 name space. 1729 1730 Names in the user name space consist of a UTF-8 string tag followed 1731 by "@" followed by a DNS domain name. Note that the tag MUST NOT 1732 contain an "@" character. For example, the "sample" tag used by 1733 Example Corporation could be "sample@example.com". 1734 1735 1736Callas, et al. Expires Oct 24, 2007 [Page 31] 1737 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1738 1739 Names in a user space are owned and controlled by the owners of that 1740 domain. Obviously, it's of bad form to create a new name in a DNS 1741 space that you don't own. 1742 1743 Since the user name space is in the form of an email address, 1744 implementers MAY wish to arrange for that address to reach a person 1745 who can be consulted about the use of the named tag. Note that due 1746 to UTF-8 encoding, not all valid user space name tags are valid 1747 email addresses. 1748 1749 If there is a critical notation, the criticality applies to that 1750 specific notation and not to notations in general. 1751 17525.2.3.17. Key server preferences 1753 1754 (N octets of flags) 1755 1756 This is a list of one-bit flags that indicate preferences that the 1757 key holder has about how the key is handled on a key server. All 1758 undefined flags MUST be zero. 1759 1760 First octet: 0x80 = No-modify 1761 the key holder requests that this key only be modified or 1762 updated by the key holder or an administrator of the key server. 1763 1764 This is found only on a self-signature. 1765 17665.2.3.18. Preferred key server 1767 1768 (String) 1769 1770 This is a URI of a key server that the key holder prefers be used 1771 for updates. Note that keys with multiple User IDs can have a 1772 preferred key server for each User ID. Note also that since this is 1773 a URI, the key server can actually be a copy of the key retrieved by 1774 ftp, http, finger, etc. 1775 17765.2.3.19. Primary User ID 1777 1778 (1 octet, Boolean) 1779 1780 This is a flag in a User ID's self signature that states whether 1781 this User ID is the main User ID for this key. It is reasonable for 1782 an implementation to resolve ambiguities in preferences, etc. by 1783 referring to the primary User ID. If this flag is absent, its value 1784 is zero. If more than one User ID in a key is marked as primary, the 1785 implementation may resolve the ambiguity in any way it sees fit, but 1786 it is RECOMMENDED that priority be given to the User ID with the 1787 most recent self-signature. 1788 1789 1790 1791 1792Callas, et al. Expires Oct 24, 2007 [Page 32] 1793 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1794 1795 When appearing on a self-signature on a User ID packet, this 1796 subpacket applies only to User ID packets. When appearing on a 1797 self-signature on a User Attribute packet, this subpacket applies 1798 only to User Attribute packets. That is to say, there are two 1799 different and independent "primaries" - one for User IDs, and one 1800 for User Attributes. 1801 18025.2.3.20. Policy URI 1803 1804 (String) 1805 1806 This subpacket contains a URI of a document that describes the 1807 policy that the signature was issued under. 1808 18095.2.3.21. Key Flags 1810 1811 (N octets of flags) 1812 1813 This subpacket contains a list of binary flags that hold information 1814 about a key. It is a string of octets, and an implementation MUST 1815 NOT assume a fixed size. This is so it can grow over time. If a list 1816 is shorter than an implementation expects, the unstated flags are 1817 considered to be zero. The defined flags are: 1818 1819 First octet: 1820 1821 0x01 - This key may be used to certify other keys. 1822 1823 0x02 - This key may be used to sign data. 1824 1825 0x04 - This key may be used to encrypt communications. 1826 1827 0x08 - This key may be used to encrypt storage. 1828 1829 0x10 - The private component of this key may have been split by 1830 a secret-sharing mechanism. 1831 1832 0x20 - This key may be used for authentication. 1833 1834 0x80 - The private component of this key may be in the 1835 possession of more than one person. 1836 1837 Usage notes: 1838 1839 The flags in this packet may appear in self-signatures or in 1840 certification signatures. They mean different things depending on 1841 who is making the statement -- for example, a certification 1842 signature that has the "sign data" flag is stating that the 1843 certification is for that use. On the other hand, the 1844 "communications encryption" flag in a self-signature is stating a 1845 preference that a given key be used for communications. Note 1846 however, that it is a thorny issue to determine what is 1847 1848Callas, et al. Expires Oct 24, 2007 [Page 33] 1849 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1850 1851 "communications" and what is "storage." This decision is left wholly 1852 up to the implementation; the authors of this document do not claim 1853 any special wisdom on the issue, and realize that accepted opinion 1854 may change. 1855 1856 The "split key" (0x10) and "group key" (0x80) flags are placed on a 1857 self-signature only; they are meaningless on a certification 1858 signature. They SHOULD be placed only on a direct-key signature 1859 (type 0x1f) or a subkey signature (type 0x18), one that refers to 1860 the key the flag applies to. 1861 18625.2.3.22. Signer's User ID 1863 1864 (String) 1865 1866 This subpacket allows a keyholder to state which User ID is 1867 responsible for the signing. Many keyholders use a single key for 1868 different purposes, such as business communications as well as 1869 personal communications. This subpacket allows such a keyholder to 1870 state which of their roles is making a signature. 1871 1872 This subpacket is not appropriate to use to refer to a User 1873 Attribute packet. 1874 18755.2.3.23. Reason for Revocation 1876 1877 (1 octet of revocation code, N octets of reason string) 1878 1879 This subpacket is used only in key revocation and certification 1880 revocation signatures. It describes the reason why the key or 1881 certificate was revoked. 1882 1883 The first octet contains a machine-readable code that denotes the 1884 reason for the revocation: 1885 1886 0 - No reason specified (key revocations or cert revocations) 1887 1 - Key is superseded (key revocations) 1888 2 - Key material has been compromised (key revocations) 1889 3 - Key is retired and no longer used (key revocations) 1890 32 - User ID information is no longer valid (cert revocations) 1891 1892 Following the revocation code is a string of octets which gives 1893 information about the reason for revocation in human-readable form 1894 (UTF-8). The string may be null, that is, of zero length. The length 1895 of the subpacket is the length of the reason string plus one. 1896 1897 An implementation SHOULD implement this subpacket, include it in all 1898 revocation signatures, and interpret revocations appropriately. 1899 There are important semantic differences between the reasons, and 1900 there are thus important reasons for revoking signatures. 1901 1902 1903 1904Callas, et al. Expires Oct 24, 2007 [Page 34] 1905 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1906 1907 If a key has been revoked because of a compromise, all signatures 1908 created by that key are suspect. However, if it was merely 1909 superseded or retired, old signatures are still valid. If the 1910 revoked signature is the self-signature for certifying a User ID, a 1911 revocation denotes that that user name is no longer in use. Such a 1912 revocation SHOULD include an 0x20 code. 1913 1914 Note that any signature may be revoked, including a certification on 1915 some other person's key. There are many good reasons for revoking a 1916 certification signature, such as the case where the keyholder leaves 1917 the employ of a business with an email address. A revoked 1918 certification is no longer a part of validity calculations. 1919 19205.2.3.24. Features 1921 1922 (N octets of flags) 1923 1924 The features subpacket denotes which advanced OpenPGP features a 1925 user's implementation supports. This is so that as features are 1926 added to OpenPGP that cannot be backwards-compatible, a user can 1927 state that they can use that feature. The flags are single bits that 1928 indicate that a given feature is supported. 1929 1930 This subpacket is similar to a preferences subpacket, and only 1931 appears in a self-signature. 1932 1933 An implementation SHOULD NOT use a feature listed when sending to a 1934 user who does not state that they can use it. 1935 1936 Defined features are: 1937 1938 First octet: 1939 1940 0x01 - Modification Detection (packets 18 and 19) 1941 1942 If an implementation implements any of the defined features, it 1943 SHOULD implement the features subpacket, too. 1944 1945 An implementation may freely infer features from other suitable 1946 implementation-dependent mechanisms. 1947 19485.2.3.25. Signature Target 1949 1950 (1 octet PK algorithm, 1 octet hash algorithm, N octets hash) 1951 1952 This subpacket identifies a specific target signature that a 1953 signature refers to. For revocation signatures, this subpacket 1954 provides explicit designation of which signature is being revoked. 1955 For a third-party or timestamp signature, this designates what 1956 signature is signed. All arguments are an identifier of that target 1957 signature. 1958 1959 1960Callas, et al. Expires Oct 24, 2007 [Page 35] 1961 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 1962 1963 The N octets of hash data MUST be the size of the hash of the 1964 signature. For example, a target signature with a SHA-1 hash MUST 1965 have 20 octets of hash data. 1966 19675.2.3.26. Embedded Signature 1968 1969 (1 signature packet body) 1970 1971 This subpacket contains a complete signature packet body as 1972 specified in section 5.2 above. It is useful when one signature 1973 needs to refer to, or be incorporated in, another signature. 1974 19755.2.4. Computing Signatures 1976 1977 All signatures are formed by producing a hash over the signature 1978 data, and then using the resulting hash in the signature algorithm. 1979 1980 For binary document signatures (type 0x00), the document data is 1981 hashed directly. For text document signatures (type 0x01), the 1982 document is canonicalized by converting line endings to <CR><LF>, 1983 and the resulting data is hashed. 1984 1985 When a signature is made over a key, the hash data starts with the 1986 octet 0x99, followed by a two-octet length of the key, and then body 1987 of the key packet. (Note that this is an old-style packet header for 1988 a key packet with two-octet length.) A subkey binding signature 1989 (type 0x18) or primary key binding signature (type 0x19) then hashes 1990 the subkey using the same format as the main key (also using 0x99 as 1991 the first octet). Key revocation signatures (types 0x20 and 0x28) 1992 hash only the key being revoked. 1993 1994 A certification signature (type 0x10 through 0x13) hashes the User 1995 ID being bound to the key into the hash context after the above 1996 data. A V3 certification hashes the contents of the User ID or 1997 attribute packet packet, without any header. A V4 certification 1998 hashes the constant 0xb4 for User ID certifications or the constant 1999 0xd1 for User Attribute certifications, followed by a four-octet 2000 number giving the length of the User ID or User Attribute data, and 2001 then the User ID or User Attribute data. 2002 2003 When a signature is made over a signature packet (type 0x50), the 2004 hash data starts with the octet 0x88, followed by the four-octet 2005 length of the signature, and then the body of the signature packet. 2006 (Note that this is an old-style packet header for a signature packet 2007 with the length-of-length set to zero). The unhashed subpacket data 2008 of the signature packet being hashed is not included in the hash and 2009 the unhashed subpacket data length value is set to zero. 2010 2011 Once the data body is hashed, then a trailer is hashed. A V3 2012 signature hashes five octets of the packet body, starting from the 2013 signature type field. This data is the signature type, followed by 2014 the four-octet signature time. A V4 signature hashes the packet body 2015 2016Callas, et al. Expires Oct 24, 2007 [Page 36] 2017 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2018 2019 starting from its first field, the version number, through the end 2020 of the hashed subpacket data. Thus, the fields hashed are the 2021 signature version, the signature type, the public key algorithm, the 2022 hash algorithm, the hashed subpacket length, and the hashed 2023 subpacket body. 2024 2025 V4 signatures also hash in a final trailer of six octets: the 2026 version of the signature packet, i.e. 0x04; 0xFF; a four-octet, 2027 big-endian number that is the length of the hashed data from the 2028 signature packet (note that this number does not include these final 2029 six octets. 2030 2031 After all this has been hashed in a single hash context the 2032 resulting hash field is used in the signature algorithm, and placed 2033 at the end of the signature packet. 2034 20355.2.4.1. Subpacket Hints 2036 2037 It is certainly possible for a signature to contain conflicting 2038 information in subpackets. For example, a signature may contain 2039 multiple copies of a preference or multiple expiration times. In 2040 most cases, an implementation SHOULD use the last subpacket in the 2041 signature, but MAY use any conflict resolution scheme that makes 2042 more sense. Please note that we are intentionally leaving conflict 2043 resolution to the implementer; most conflicts are simply syntax 2044 errors, and the wishy-washy language here allows a receiver to be 2045 generous in what they accept, while putting pressure on a creator to 2046 be stingy in what they generate. 2047 2048 Some apparent conflicts may actually make sense -- for example, 2049 suppose a keyholder has an V3 key and a V4 key that share the same 2050 RSA key material. Either of these keys can verify a signature 2051 created by the other, and it may be reasonable for a signature to 2052 contain an issuer subpacket for each key, as a way of explicitly 2053 tying those keys to the signature. 2054 20555.3. Symmetric-Key Encrypted Session Key Packets (Tag 3) 2056 2057 The Symmetric-Key Encrypted Session Key packet holds the 2058 symmetric-key encryption of a session key used to encrypt a message. 2059 Zero or more Public-Key Encrypted Session Key packets and/or 2060 Symmetric-Key Encrypted Session Key packets may precede a 2061 Symmetrically Encrypted Data Packet that holds an encrypted message. 2062 The message is encrypted with a session key, and the session key is 2063 itself encrypted and stored in the Encrypted Session Key packet or 2064 the Symmetric-Key Encrypted Session Key packet. 2065 2066 If the Symmetrically Encrypted Data Packet is preceded by one or 2067 more Symmetric-Key Encrypted Session Key packets, each specifies a 2068 passphrase that may be used to decrypt the message. This allows a 2069 message to be encrypted to a number of public keys, and also to one 2070 or more passphrases. This packet type is new, and is not generated 2071 2072Callas, et al. Expires Oct 24, 2007 [Page 37] 2073 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2074 2075 by PGP 2.x or PGP 5.0. 2076 2077 The body of this packet consists of: 2078 2079 - A one-octet version number. The only currently defined version 2080 is 4. 2081 2082 - A one-octet number describing the symmetric algorithm used. 2083 2084 - A string-to-key (S2K) specifier, length as defined above. 2085 2086 - Optionally, the encrypted session key itself, which is decrypted 2087 with the string-to-key object. 2088 2089 If the encrypted session key is not present (which can be detected 2090 on the basis of packet length and S2K specifier size), then the S2K 2091 algorithm applied to the passphrase produces the session key for 2092 decrypting the file, using the symmetric cipher algorithm from the 2093 Symmetric-Key Encrypted Session Key packet. 2094 2095 If the encrypted session key is present, the result of applying the 2096 S2K algorithm to the passphrase is used to decrypt just that 2097 encrypted session key field, using CFB mode with an IV of all zeros. 2098 The decryption result consists of a one-octet algorithm identifier 2099 that specifies the symmetric-key encryption algorithm used to 2100 encrypt the following Symmetrically Encrypted Data Packet, followed 2101 by the session key octets themselves. 2102 2103 Note: because an all-zero IV is used for this decryption, the S2K 2104 specifier MUST use a salt value, either a Salted S2K or an 2105 Iterated-Salted S2K. The salt value will insure that the decryption 2106 key is not repeated even if the passphrase is reused. 2107 21085.4. One-Pass Signature Packets (Tag 4) 2109 2110 The One-Pass Signature packet precedes the signed data and contains 2111 enough information to allow the receiver to begin calculating any 2112 hashes needed to verify the signature. It allows the Signature 2113 Packet to be placed at the end of the message, so that the signer 2114 can compute the entire signed message in one pass. 2115 2116 A One-Pass Signature does not interoperate with PGP 2.6.x or 2117 earlier. 2118 2119 The body of this packet consists of: 2120 2121 - A one-octet version number. The current version is 3. 2122 2123 - A one-octet signature type. Signature types are described in 2124 section 5.2.1. 2125 2126 2127 2128Callas, et al. Expires Oct 24, 2007 [Page 38] 2129 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2130 2131 - A one-octet number describing the hash algorithm used. 2132 2133 - A one-octet number describing the public key algorithm used. 2134 2135 - An eight-octet number holding the key ID of the signing key. 2136 2137 - A one-octet number holding a flag showing whether the signature 2138 is nested. A zero value indicates that the next packet is 2139 another One-Pass Signature packet that describes another 2140 signature to be applied to the same message data. 2141 2142 Note that if a message contains more than one one-pass signature, 2143 then the signature packets bracket the message; that is, the first 2144 signature packet after the message corresponds to the last one-pass 2145 packet and the final signature packet corresponds to the first 2146 one-pass packet. 2147 21485.5. Key Material Packet 2149 2150 A key material packet contains all the information about a public or 2151 private key. There are four variants of this packet type, and two 2152 major versions. Consequently, this section is complex. 2153 21545.5.1. Key Packet Variants 2155 21565.5.1.1. Public Key Packet (Tag 6) 2157 2158 A Public Key packet starts a series of packets that forms an OpenPGP 2159 key (sometimes called an OpenPGP certificate). 2160 21615.5.1.2. Public Subkey Packet (Tag 14) 2162 2163 A Public Subkey packet (tag 14) has exactly the same format as a 2164 Public Key packet, but denotes a subkey. One or more subkeys may be 2165 associated with a top-level key. By convention, the top-level key 2166 provides signature services, and the subkeys provide encryption 2167 services. 2168 2169 Note: in PGP 2.6.x, tag 14 was intended to indicate a comment 2170 packet. This tag was selected for reuse because no previous version 2171 of PGP ever emitted comment packets but they did properly ignore 2172 them. Public Subkey packets are ignored by PGP 2.6.x and do not 2173 cause it to fail, providing a limited degree of backward 2174 compatibility. 2175 21765.5.1.3. Secret Key Packet (Tag 5) 2177 2178 A Secret Key packet contains all the information that is found in a 2179 Public Key packet, including the public key material, but also 2180 includes the secret key material after all the public key fields. 2181 2182 2183 2184Callas, et al. Expires Oct 24, 2007 [Page 39] 2185 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2186 21875.5.1.4. Secret Subkey Packet (Tag 7) 2188 2189 A Secret Subkey packet (tag 7) is the subkey analog of the Secret 2190 Key packet, and has exactly the same format. 2191 21925.5.2. Public Key Packet Formats 2193 2194 There are two versions of key-material packets. Version 3 packets 2195 were first generated by PGP 2.6. Version 4 keys first appeared in 2196 PGP 5.0, and are the preferred key version for OpenPGP. 2197 2198 OpenPGP implementations MUST create keys with version 4 format. V3 2199 keys are deprecated; an implementation MUST NOT generate a V3 key, 2200 but MAY accept it. 2201 2202 A version 3 public key or public subkey packet contains: 2203 2204 - A one-octet version number (3). 2205 2206 - A four-octet number denoting the time that the key was created. 2207 2208 - A two-octet number denoting the time in days that this key is 2209 valid. If this number is zero, then it does not expire. 2210 2211 - A one-octet number denoting the public key algorithm of this key 2212 2213 - A series of multiprecision integers comprising the key material: 2214 2215 - a multiprecision integer (MPI) of RSA public modulus n; 2216 2217 - an MPI of RSA public encryption exponent e. 2218 2219 V3 keys are deprecated. They contain three weaknesses in them. 2220 First, it is relatively easy to construct a V3 key that has the same 2221 key ID as any other key because the key ID is simply the low 64 bits 2222 of the public modulus. Secondly, because the fingerprint of a V3 key 2223 hashes the key material, but not its length, there is an increased 2224 opportunity for fingerprint collisions. Third, there are weaknesses 2225 in the MD5 hash algorithm that make developers prefer other 2226 algorithms. See below for a fuller discussion of key IDs and 2227 fingerprints. 2228 2229 V2 keys are identical to the deprecated V3 keys except for the 2230 version number. An implementation MUST NOT generate them and MAY 2231 accept or reject them as it sees fit. 2232 2233 The version 4 format is similar to the version 3 format except for 2234 the absence of a validity period. This has been moved to the 2235 signature packet. In addition, fingerprints of version 4 keys are 2236 calculated differently from version 3 keys, as described in section 2237 "Enhanced Key Formats." 2238 2239 2240Callas, et al. Expires Oct 24, 2007 [Page 40] 2241 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2242 2243 A version 4 packet contains: 2244 2245 - A one-octet version number (4). 2246 2247 - A four-octet number denoting the time that the key was created. 2248 2249 - A one-octet number denoting the public key algorithm of this key 2250 2251 - A series of multiprecision integers comprising the key material. 2252 This algorithm-specific portion is: 2253 2254 Algorithm Specific Fields for RSA public keys: 2255 2256 - multiprecision integer (MPI) of RSA public modulus n; 2257 2258 - MPI of RSA public encryption exponent e. 2259 2260 Algorithm Specific Fields for DSA public keys: 2261 2262 - MPI of DSA prime p; 2263 2264 - MPI of DSA group order q (q is a prime divisor of p-1); 2265 2266 - MPI of DSA group generator g; 2267 2268 - MPI of DSA public key value y (= g**x mod p where x is 2269 secret). 2270 2271 Algorithm Specific Fields for Elgamal public keys: 2272 2273 - MPI of Elgamal prime p; 2274 2275 - MPI of Elgamal group generator g; 2276 2277 - MPI of Elgamal public key value y (= g**x mod p where x is 2278 secret). 2279 22805.5.3. Secret Key Packet Formats 2281 2282 The Secret Key and Secret Subkey packets contain all the data of the 2283 Public Key and Public Subkey packets, with additional 2284 algorithm-specific secret key data appended, usually in encrypted 2285 form. 2286 2287 The packet contains: 2288 2289 - A Public Key or Public Subkey packet, as described above 2290 2291 - One octet indicating string-to-key usage conventions. Zero 2292 indicates that the secret key data is not encrypted. 255 or 254 2293 indicates that a string-to-key specifier is being given. Any 2294 other value is a symmetric-key encryption algorithm identifier. 2295 2296Callas, et al. Expires Oct 24, 2007 [Page 41] 2297 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2298 2299 - [Optional] If string-to-key usage octet was 255 or 254, a 2300 one-octet symmetric encryption algorithm. 2301 2302 - [Optional] If string-to-key usage octet was 255 or 254, a 2303 string-to-key specifier. The length of the string-to-key 2304 specifier is implied by its type, as described above. 2305 2306 - [Optional] If secret data is encrypted (string-to-key usage 2307 octet not zero), an Initial Vector (IV) of the same length as 2308 the cipher's block size. 2309 2310 - Plain or encrypted multiprecision integers comprising the secret 2311 key data. These algorithm-specific fields are as described 2312 below. 2313 2314 - If the string-to-key usage octet is zero or 255, then a 2315 two-octet checksum of the plaintext of the algorithm-specific 2316 portion (sum of all octets, mod 65536). If the string-to-key 2317 usage octet was 254, then a 20-octet SHA-1 hash of the plaintext 2318 of the algorithm-specific portion. This checksum or hash is 2319 encrypted together with the algorithm-specific fields (if 2320 string-to-key usage octet is not zero). Note that for all other 2321 values, a two-octet checksum is required. 2322 2323 Algorithm Specific Fields for RSA secret keys: 2324 2325 - multiprecision integer (MPI) of RSA secret exponent d. 2326 2327 - MPI of RSA secret prime value p. 2328 2329 - MPI of RSA secret prime value q (p < q). 2330 2331 - MPI of u, the multiplicative inverse of p, mod q. 2332 2333 Algorithm Specific Fields for DSA secret keys: 2334 2335 - MPI of DSA secret exponent x. 2336 2337 Algorithm Specific Fields for Elgamal secret keys: 2338 2339 - MPI of Elgamal secret exponent x. 2340 2341 Secret MPI values can be encrypted using a passphrase. If a 2342 string-to-key specifier is given, that describes the algorithm for 2343 converting the passphrase to a key, else a simple MD5 hash of the 2344 passphrase is used. Implementations MUST use a string-to-key 2345 specifier; the simple hash is for backward compatibility and is 2346 deprecated, though implementations MAY continue to use existing 2347 private keys in the old format. The cipher for encrypting the MPIs 2348 is specified in the secret key packet. 2349 2350 2351 2352Callas, et al. Expires Oct 24, 2007 [Page 42] 2353 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2354 2355 Encryption/decryption of the secret data is done in CFB mode using 2356 the key created from the passphrase and the Initial Vector from the 2357 packet. A different mode is used with V3 keys (which are only RSA) 2358 than with other key formats. With V3 keys, the MPI bit count prefix 2359 (i.e., the first two octets) is not encrypted. Only the MPI 2360 non-prefix data is encrypted. Furthermore, the CFB state is 2361 resynchronized at the beginning of each new MPI value, so that the 2362 CFB block boundary is aligned with the start of the MPI data. 2363 2364 With V4 keys, a simpler method is used. All secret MPI values are 2365 encrypted in CFB mode, including the MPI bitcount prefix. 2366 2367 The two-octet checksum that follows the algorithm-specific portion 2368 is the algebraic sum, mod 65536, of the plaintext of all the 2369 algorithm-specific octets (including MPI prefix and data). With V3 2370 keys, the checksum is stored in the clear. With V4 keys, the 2371 checksum is encrypted like the algorithm-specific data. This value 2372 is used to check that the passphrase was correct. However, this 2373 checksum is deprecated; an implementation SHOULD NOT use it, but 2374 should rather use the SHA-1 hash denoted with a usage octet of 254. 2375 The reason for this is that there are some attacks that involve 2376 undetectably modifying the secret key. 2377 23785.6. Compressed Data Packet (Tag 8) 2379 2380 The Compressed Data packet contains compressed data. Typically, this 2381 packet is found as the contents of an encrypted packet, or following 2382 a Signature or One-Pass Signature packet, and contains a literal 2383 data packet. 2384 2385 The body of this packet consists of: 2386 2387 - One octet that gives the algorithm used to compress the packet. 2388 2389 - The remainder of the packet is compressed data. 2390 2391 A Compressed Data Packet's body contains an block that compresses 2392 some set of packets. See section "Packet Composition" for details on 2393 how messages are formed. 2394 2395 ZIP-compressed packets are compressed with raw RFC 1951 DEFLATE 2396 blocks. Note that PGP V2.6 uses 13 bits of compression. If an 2397 implementation uses more bits of compression, PGP V2.6 cannot 2398 decompress it. 2399 2400 ZLIB-compressed packets are compressed with RFC 1950 ZLIB-style 2401 blocks. 2402 2403 BZip2-compressed packets are compressed using the BZip2 [BZ2] 2404 algorithm. 2405 2406 2407 2408Callas, et al. Expires Oct 24, 2007 [Page 43] 2409 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2410 24115.7. Symmetrically Encrypted Data Packet (Tag 9) 2412 2413 The Symmetrically Encrypted Data packet contains data encrypted with 2414 a symmetric-key algorithm. When it has been decrypted, it contains 2415 other packets (usually a literal data packet or compressed data 2416 packet, but in theory other Symmetrically Encrypted Data Packets or 2417 sequences of packets that form whole OpenPGP messages). 2418 2419 The body of this packet consists of: 2420 2421 - Encrypted data, the output of the selected symmetric-key cipher 2422 operating in OpenPGP's variant of Cipher Feedback (CFB) mode. 2423 2424 The symmetric cipher used may be specified in an Public-Key or 2425 Symmetric-Key Encrypted Session Key packet that precedes the 2426 Symmetrically Encrypted Data Packet. In that case, the cipher 2427 algorithm octet is prefixed to the session key before it is 2428 encrypted. If no packets of these types precede the encrypted data, 2429 the IDEA algorithm is used with the session key calculated as the 2430 MD5 hash of the passphrase, though this use is deprecated. 2431 2432 The data is encrypted in CFB mode, with a CFB shift size equal to 2433 the cipher's block size. The Initial Vector (IV) is specified as all 2434 zeros. Instead of using an IV, OpenPGP prefixes a string of length 2435 equal to the block size of the cipher plus two to the data before it 2436 is encrypted. The first block-size octets (for example, 8 octets for 2437 a 64-bit block length) are random, and the following two octets are 2438 copies of the last two octets of the IV. For example, in an 8 octet 2439 block, octet 9 is a repeat of octet 7, and octet 10 is a repeat of 2440 octet 8. In a cipher of length 16, octet 17 is a repeat of octet 15 2441 and octet 18 is a repeat of octet 16. As a pedantic clarification, 2442 in both these examples, we consider the first octet to be numbered 2443 1. 2444 2445 After encrypting the first block-size-plus-two octets, the CFB state 2446 is resynchronized. The last block-size octets of ciphertext are 2447 passed through the cipher and the block boundary is reset. 2448 2449 The repetition of 16 bits in the random data prefixed to the message 2450 allows the receiver to immediately check whether the session key is 2451 incorrect. See the Security Considerations section for hints on the 2452 proper use of this "quick check." 2453 24545.8. Marker Packet (Obsolete Literal Packet) (Tag 10) 2455 2456 An experimental version of PGP used this packet as the Literal 2457 packet, but no released version of PGP generated Literal packets 2458 with this tag. With PGP 5.x, this packet has been re-assigned and is 2459 reserved for use as the Marker packet. 2460 2461 2462 2463 2464Callas, et al. Expires Oct 24, 2007 [Page 44] 2465 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2466 2467 The body of this packet consists of: 2468 2469 - The three octets 0x50, 0x47, 0x50 (which spell "PGP" in UTF-8). 2470 2471 Such a packet MUST be ignored when received. It may be placed at the 2472 beginning of a message that uses features not available in PGP 2.6.x 2473 in order to cause that version to report that newer software is 2474 necessary to process the message. 2475 24765.9. Literal Data Packet (Tag 11) 2477 2478 A Literal Data packet contains the body of a message; data that is 2479 not to be further interpreted. 2480 2481 The body of this packet consists of: 2482 2483 - A one-octet field that describes how the data is formatted. 2484 2485 If it is a 'b' (0x62), then the literal packet contains binary data. 2486 If it is a 't' (0x74), then it contains text data, and thus may need 2487 line ends converted to local form, or other text-mode changes. The 2488 tag 'u' (0x75) means the same as 't', but also indicates that 2489 implementation believes that the literal data contains UTF-8 text. 2490 2491 Early versions of PGP also defined a value of 'l' as a 'local' mode 2492 for machine-local conversions. RFC 1991 incorrectly stated this 2493 local mode flag as '1' (ASCII numeral one). Both of these local 2494 modes are deprecated. 2495 2496 - File name as a string (one-octet length, followed by a file 2497 name). This may be a zero-length string. Commonly, if the source 2498 of the encrypted data is a file, this will be the name of the 2499 encrypted file. An implementation MAY consider the file name in 2500 the literal packet to be a more authoritative name than the 2501 actual file name. 2502 2503 If the special name "_CONSOLE" is used, the message is considered to 2504 be "for your eyes only". This advises that the message data is 2505 unusually sensitive, and the receiving program should process it 2506 more carefully, perhaps avoiding storing the received data to disk, 2507 for example. 2508 2509 - A four-octet number that indicates a date associated with the 2510 literal data. Commonly, the date might be the modification date 2511 of a file, or the time the packet was created, or a zero that 2512 indicates no specific time. 2513 2514 - The remainder of the packet is literal data. 2515 2516 Text data is stored with <CR><LF> text endings (i.e. network-normal 2517 line endings). These should be converted to native line endings by 2518 the receiving software. 2519 2520Callas, et al. Expires Oct 24, 2007 [Page 45] 2521 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2522 25235.10. Trust Packet (Tag 12) 2524 2525 The Trust packet is used only within keyrings and is not normally 2526 exported. Trust packets contain data that record the user's 2527 specifications of which key holders are trustworthy introducers, 2528 along with other information that implementing software uses for 2529 trust information. The format of trust packets is defined by a given 2530 implementation. 2531 2532 Trust packets SHOULD NOT be emitted to output streams that are 2533 transferred to other users, and they SHOULD be ignored on any input 2534 other than local keyring files. 2535 25365.11. User ID Packet (Tag 13) 2537 2538 A User ID packet consists of UTF-8 text that is intended to 2539 represent the name and email address of the key holder. By 2540 convention, it includes an RFC 2822 mail name-addr, but there are no 2541 restrictions on its content. The packet length in the header 2542 specifies the length of the User ID. 2543 25445.12. User Attribute Packet (Tag 17) 2545 2546 The User Attribute packet is a variation of the User ID packet. It 2547 is capable of storing more types of data than the User ID packet 2548 which is limited to text. Like the User ID packet, a User Attribute 2549 packet may be certified by the key owner ("self-signed") or any 2550 other key owner who cares to certify it. Except as noted, a User 2551 Attribute packet may be used anywhere that a User ID packet may be 2552 used. 2553 2554 While User Attribute packets are not a required part of the OpenPGP 2555 standard, implementations SHOULD provide at least enough 2556 compatibility to properly handle a certification signature on the 2557 User Attribute packet. A simple way to do this is by treating the 2558 User Attribute packet as a User ID packet with opaque contents, but 2559 an implementation may use any method desired. 2560 2561 The User Attribute packet is made up of one or more attribute 2562 subpackets. Each subpacket consists of a subpacket header and a 2563 body. The header consists of: 2564 2565 - the subpacket length (1, 2, or 5 octets) 2566 2567 - the subpacket type (1 octet) 2568 2569 and is followed by the subpacket specific data. 2570 2571 The only currently defined subpacket type is 1, signifying an image. 2572 An implementation SHOULD ignore any subpacket of a type that it does 2573 not recognize. Subpacket types 100 through 110 are reserved for 2574 private or experimental use. 2575 2576Callas, et al. Expires Oct 24, 2007 [Page 46] 2577 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2578 25795.12.1. The Image Attribute Subpacket 2580 2581 The image attribute subpacket is used to encode an image, presumably 2582 (but not required to be) that of the key owner. 2583 2584 The image attribute subpacket begins with an image header. The first 2585 two octets of the image header contain the length of the image 2586 header. Note that unlike other multi-octet numerical values in this 2587 document, due to an historical accident this value is encoded as a 2588 little-endian number. The image header length is followed by a 2589 single octet for the image header version. The only currently 2590 defined version of the image header is 1, which is a 16 octet image 2591 header. The first three octets of a version 1 image header are thus 2592 0x10 0x00 0x01. 2593 2594 The fourth octet of a version 1 image header designates the encoding 2595 format of the image. The only currently defined encoding format is 2596 the value 1 to indicate JPEG. Image format types 100 through 110 are 2597 reserved for private or experimental use. The rest of the version 1 2598 image header is made up of 12 reserved octets, all of which MUST be 2599 set to 0. 2600 2601 The rest of the image subpacket contains the image itself. As the 2602 only currently defined image type is JPEG, the image is encoded in 2603 the JPEG File Interchange Format (JFIF), a standard file format for 2604 JPEG images. [JFIF] 2605 2606 An implementation MAY try and determine the type of an image by 2607 examination of the image data if it is unable to handle a particular 2608 version of the image header or if a specified encoding format value 2609 is not recognized. 2610 26115.13. Sym. Encrypted Integrity Protected Data Packet (Tag 18) 2612 2613 The Symmetrically Encrypted Integrity Protected Data Packet is a 2614 variant of the Symmetrically Encrypted Data Packet. It is a new 2615 feature created for OpenPGP that addresses the problem of detecting 2616 a modification to encrypted data. It is used in combination with a 2617 Modification Detection Code Packet. 2618 2619 There is a corresponding feature in the features signature subpacket 2620 that denotes that an implementation can properly use this packet 2621 type. An implementation MUST support decrypting these packets and 2622 SHOULD prefer generating them to the older Symmetrically Encrypted 2623 Data Packet when possible. Since this data packet protects against 2624 modification attacks, this standard encourages its proliferation. 2625 While blanket adoption of this data packet would create 2626 interoperability problems, rapid adoption is nevertheless important. 2627 An implementation SHOULD specifically denote support for this 2628 packet, but it MAY infer it from other mechanisms. 2629 2630 2631 2632Callas, et al. Expires Oct 24, 2007 [Page 47] 2633 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2634 2635 For example, an implementation might infer from the use of a cipher 2636 such as AES or Twofish that a user supports this feature. It might 2637 place in the unhashed portion of another user's key signature a 2638 features subpacket. It might also present a user with an opportunity 2639 to regenerate their own self-signature with a features subpacket. 2640 2641 This packet contains data encrypted with a symmetric-key algorithm 2642 and protected against modification by the SHA-1 hash algorithm. When 2643 it has been decrypted, it will typically contain other packets 2644 (often a literal data packet or compressed data packet). The last 2645 decrypted packet in this packet's payload MUST be a Modification 2646 Detection Code packet. 2647 2648 The body of this packet consists of: 2649 2650 - A one-octet version number. The only currently defined value is 2651 1. 2652 2653 - Encrypted data, the output of the selected symmetric-key cipher 2654 operating in Cipher Feedback mode with shift amount equal to the 2655 block size of the cipher (CFB-n where n is the block size). 2656 2657 The symmetric cipher used MUST be specified in a Public-Key or 2658 Symmetric-Key Encrypted Session Key packet that precedes the 2659 Symmetrically Encrypted Data Packet. In either case, the cipher 2660 algorithm octet is prefixed to the session key before it is 2661 encrypted. 2662 2663 The data is encrypted in CFB mode, with a CFB shift size equal to 2664 the cipher's block size. The Initial Vector (IV) is specified as all 2665 zeros. Instead of using an IV, OpenPGP prefixes an octet string to 2666 the data before it is encrypted. The length of the octet string 2667 equals the block size of the cipher in octets, plus two. The first 2668 octets in the group, of length equal to the block size of the 2669 cipher, are random; the last two octets are each copies of their 2nd 2670 preceding octet. For example, with a cipher whose block size is 128 2671 bits or 16 octets, the prefix data will contain 16 random octets, 2672 then two more octets, which are copies of the 15th and 16th octets, 2673 respectively. Unlike the Symmetrically Encrypted Data Packet, no 2674 special CFB resynchronization is done after encrypting this prefix 2675 data. See OpenPGP CFB Mode below for more details. 2676 2677 The repetition of 16 bits in the random data prefixed to the message 2678 allows the receiver to immediately check whether the session key is 2679 incorrect. 2680 2681 The plaintext of the data to be encrypted is passed through the 2682 SHA-1 hash function, and the result of the hash is appended to the 2683 plaintext in a Modification Detection Code packet. The input to the 2684 hash function includes the prefix data described above; it includes 2685 all of the plaintext, and then also includes two octets of values 2686 0xD3, 0x14. These represent the encoding of a Modification Detection 2687 2688Callas, et al. Expires Oct 24, 2007 [Page 48] 2689 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2690 2691 Code packet tag and length field of 20 octets. 2692 2693 The resulting hash value is stored in a Modification Detection Code 2694 packet which MUST use the two octet encoding just given to represent 2695 its tag and length field. The body of the MDC packet is the 20 octet 2696 output of the SHA-1 hash. 2697 2698 The Modification Detection Code packet is appended to the plaintext 2699 and encrypted along with the plaintext using the same CFB context. 2700 2701 During decryption, the plaintext data should be hashed with SHA-1, 2702 including the prefix data as well as the packet tag and length field 2703 of the Modification Detection Code packet. The body of the MDC 2704 packet, upon decryption, is compared with the result of the SHA-1 2705 hash. 2706 2707 Any failure of the MDC indicates that the message has been modified 2708 and MUST be treated as a security problem. Failures include a 2709 difference in the hash values, but also the absence of an MDC 2710 packet, or an MDC packet in any position other than the end of the 2711 plaintext. Any failure SHOULD be reported to the user. 2712 2713 Note: future designs of new versions of this packet should consider 2714 rollback attacks since it will be possible for an attacker to change 2715 the version back to 1. 2716 2717 NON-NORMATIVE EXPLANATION 2718 2719 The MDC system, as packets 18 and 19 are called, were created to 2720 provide an integrity mechanism that is less strong than a 2721 signature, yet stronger than bare CFB encryption. 2722 2723 It is a limitation of CFB encryption that damage to the 2724 ciphertext will corrupt the affected cipher blocks and the block 2725 following. Additionally, if data is removed from the end of a 2726 CFB-encrypted block, that removal is undetectable. (Note also 2727 that CBC mode has a similar limitation, but data removed from 2728 the front of the block is undetectable.) 2729 2730 The obvious way to protect or authenticate an encrypted block is 2731 to digitally sign it. However, many people do not wish to 2732 habitually sign data, for a large number of reasons beyond the 2733 scope of this document. Suffice it to say that many people 2734 consider properties such as deniability to be as valuable as 2735 integrity. 2736 2737 OpenPGP addresses this desire to have more security than raw 2738 encryption and yet preserve deniability with the MDC system. An 2739 MDC is intentionally not a MAC. Its name was not selected by 2740 accident. It is analogous to a checksum. 2741 2742 2743 2744Callas, et al. Expires Oct 24, 2007 [Page 49] 2745 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2746 2747 Despite the fact that it is a relatively modest system, it has 2748 proved itself in the real world. It is an effective defense to 2749 several attacks that have surfaced since it has been created. It 2750 has met its modest goals admirably. 2751 2752 Consequently, because it is a modest security system, it has 2753 modest requirements on the hash function(s) it employs. It does 2754 not rely on a hash function being collision-free, it relies on a 2755 hash function being one-way. If a forger, Frank, wishes to send 2756 Alice a (digitally) unsigned message that says, "I've always 2757 secretly loved you, signed Bob" it is far easier for him to 2758 construct a new message than it is to modify anything 2759 intercepted from Bob. (Note also that if Bob wishes to 2760 communicate secretly with Alice, but without authentication nor 2761 identification and with a threat model that includes forgers, he 2762 has a problem that transcends mere cryptography.) 2763 2764 Note also that unlike nearly every other OpenPGP subsystem, 2765 there are no parameters in the MDC system. It hard-defines SHA-1 2766 as its hash function. This is not an accident. It is an 2767 intentional choice to avoid downgrade and cross-grade attacks 2768 while making a simple, fast system. (A downgrade attack would be 2769 an attack that replaced SHA-256 with SHA-1, for example. A 2770 cross-grade attack would replace SHA-1 with another 160-bit 2771 hash, such as RIPE-MD/160, for example.) 2772 2773 However, given the present state of hash function cryptanalysis 2774 and cryptography, it may be desirable to upgrade the MDC system 2775 to a new hash function. See section 10.5 in the IANA 2776 considerations for guidance. 2777 27785.14. Modification Detection Code Packet (Tag 19) 2779 2780 The Modification Detection Code packet contains a SHA-1 hash of 2781 plaintext data which is used to detect message modification. It is 2782 only used with a Symmetrically Encrypted Integrity Protected Data 2783 packet. The Modification Detection Code packet MUST be the last 2784 packet in the plaintext data which is encrypted in the Symmetrically 2785 Encrypted Integrity Protected Data packet, and MUST appear in no 2786 other place. 2787 2788 A Modification Detection Code packet MUST have a length of 20 2789 octets. 2790 2791 The body of this packet consists of: 2792 2793 - A 20-octet SHA-1 hash of the preceding plaintext data of the 2794 Symmetrically Encrypted Integrity Protected Data packet, 2795 including prefix data, the tag octet, and length octet of the 2796 Modification Detection Code packet. 2797 2798 2799 2800Callas, et al. Expires Oct 24, 2007 [Page 50] 2801 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2802 2803 Note that the Modification Detection Code packet MUST always use a 2804 new-format encoding of the packet tag, and a one-octet encoding of 2805 the packet length. The reason for this is that the hashing rules for 2806 modification detection include a one-octet tag and one-octet length 2807 in the data hash. While this is a bit restrictive, it reduces 2808 complexity. 2809 28106. Radix-64 Conversions 2811 2812 As stated in the introduction, OpenPGP's underlying native 2813 representation for objects is a stream of arbitrary octets, and some 2814 systems desire these objects to be immune to damage caused by 2815 character set translation, data conversions, etc. 2816 2817 In principle, any printable encoding scheme that met the 2818 requirements of the unsafe channel would suffice, since it would not 2819 change the underlying binary bit streams of the native OpenPGP data 2820 structures. The OpenPGP standard specifies one such printable 2821 encoding scheme to ensure interoperability. 2822 2823 OpenPGP's Radix-64 encoding is composed of two parts: a base64 2824 encoding of the binary data, and a checksum. The base64 encoding is 2825 identical to the MIME base64 content-transfer-encoding [RFC2045]. 2826 2827 The checksum is a 24-bit CRC converted to four characters of 2828 radix-64 encoding by the same MIME base64 transformation, preceded 2829 by an equals sign (=). The CRC is computed by using the generator 2830 0x864CFB and an initialization of 0xB704CE. The accumulation is done 2831 on the data before it is converted to radix-64, rather than on the 2832 converted data. A sample implementation of this algorithm is in the 2833 next section. 2834 2835 The checksum with its leading equal sign MAY appear on the first 2836 line after the Base64 encoded data. 2837 2838 Rationale for CRC-24: The size of 24 bits fits evenly into printable 2839 base64. The nonzero initialization can detect more errors than a 2840 zero initialization. 2841 28426.1. An Implementation of the CRC-24 in "C" 2843 2844 #define CRC24_INIT 0xb704ceL 2845 #define CRC24_POLY 0x1864cfbL 2846 2847 typedef long crc24; 2848 crc24 crc_octets(unsigned char *octets, size_t len) 2849 { 2850 crc24 crc = CRC24_INIT; 2851 int i; 2852 2853 2854 2855 2856Callas, et al. Expires Oct 24, 2007 [Page 51] 2857 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2858 2859 while (len--) { 2860 crc ^= (*octets++) << 16; 2861 for (i = 0; i < 8; i++) { 2862 crc <<= 1; 2863 if (crc & 0x1000000) 2864 crc ^= CRC24_POLY; 2865 } 2866 } 2867 return crc & 0xffffffL; 2868 } 2869 28706.2. Forming ASCII Armor 2871 2872 When OpenPGP encodes data into ASCII Armor, it puts specific headers 2873 around the Radix-64 encoded data, so OpenPGP can reconstruct the 2874 data later. An OpenPGP implementation MAY use ASCII armor to protect 2875 raw binary data. OpenPGP informs the user what kind of data is 2876 encoded in the ASCII armor through the use of the headers. 2877 2878 Concatenating the following data creates ASCII Armor: 2879 2880 - An Armor Header Line, appropriate for the type of data 2881 2882 - Armor Headers 2883 2884 - A blank (zero-length, or containing only whitespace) line 2885 2886 - The ASCII-Armored data 2887 2888 - An Armor Checksum 2889 2890 - The Armor Tail, which depends on the Armor Header Line. 2891 2892 An Armor Header Line consists of the appropriate header line text 2893 surrounded by five (5) dashes ('-', 0x2D) on either side of the 2894 header line text. The header line text is chosen based upon the type 2895 of data that is being encoded in Armor, and how it is being encoded. 2896 Header line texts include the following strings: 2897 2898 BEGIN PGP MESSAGE 2899 Used for signed, encrypted, or compressed files. 2900 2901 BEGIN PGP PUBLIC KEY BLOCK 2902 Used for armoring public keys 2903 2904 BEGIN PGP PRIVATE KEY BLOCK 2905 Used for armoring private keys 2906 2907 BEGIN PGP MESSAGE, PART X/Y 2908 Used for multi-part messages, where the armor is split amongst Y 2909 parts, and this is the Xth part out of Y. 2910 2911 2912Callas, et al. Expires Oct 24, 2007 [Page 52] 2913 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2914 2915 BEGIN PGP MESSAGE, PART X 2916 Used for multi-part messages, where this is the Xth part of an 2917 unspecified number of parts. Requires the MESSAGE-ID Armor 2918 Header to be used. 2919 2920 BEGIN PGP SIGNATURE 2921 Used for detached signatures, OpenPGP/MIME signatures, and 2922 cleartext signatures. Note that PGP 2.x uses BEGIN PGP MESSAGE 2923 for detached signatures. 2924 2925 Note that all these Armor Header Lines are to consist of a complete 2926 line. That is to say, there is always a line ending preceding the 2927 starting five dashes, and following the ending five dashes. The 2928 header lines, therefore, MUST start at the beginning of a line, and 2929 MUST NOT have text other than whitespace following them on the same 2930 line. These line endings are considered a part of the Armor Header 2931 Line for the purposes of determining the content they delimit. This 2932 is particularly important when computing a cleartext signature (see 2933 below). 2934 2935 The Armor Headers are pairs of strings that can give the user or the 2936 receiving OpenPGP implementation some information about how to 2937 decode or use the message. The Armor Headers are a part of the 2938 armor, not a part of the message, and hence are not protected by any 2939 signatures applied to the message. 2940 2941 The format of an Armor Header is that of a key-value pair. A colon 2942 (':' 0x38) and a single space (0x20) separate the key and value. 2943 OpenPGP should consider improperly formatted Armor Headers to be 2944 corruption of the ASCII Armor. Unknown keys should be reported to 2945 the user, but OpenPGP should continue to process the message. 2946 2947 Note that some transport methods are sensitive to line length. While 2948 there is a limit of 76 characters for the Radix-64 data (section 2949 6.3), there is no limit to the length of Armor Headers. Care should 2950 be taken that the Armor Headers are short enough to survive 2951 transport. One way to do this is to repeat an Armor Header key 2952 multiple times with different values for each so that no one line is 2953 overly long. 2954 2955 Currently defined Armor Header Keys are: 2956 2957 - "Version", that states the OpenPGP implementation and version 2958 used to encode the message. 2959 2960 - "Comment", a user-defined comment. OpenPGP defines all text to 2961 be in UTF-8. A comment may be any UTF-8 string. However, the 2962 whole point of armoring is to provide seven-bit-clean data. 2963 Consequently, if a comment has characters that are outside the 2964 US-ASCII range of UTF, they may very well not survive transport. 2965 2966 2967 2968Callas, et al. Expires Oct 24, 2007 [Page 53] 2969 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 2970 2971 - "MessageID", a 32-character string of printable characters. The 2972 string must be the same for all parts of a multi-part message 2973 that uses the "PART X" Armor Header. MessageID strings should be 2974 unique enough that the recipient of the mail can associate all 2975 the parts of a message with each other. A good checksum or 2976 cryptographic hash function is sufficient. 2977 2978 The MessageID SHOULD NOT appear unless it is in a multi-part 2979 message. If it appears at all, it MUST be computed from the 2980 finished (encrypted, signed, etc.) message in a deterministic 2981 fashion, rather than contain a purely random value. This is to 2982 allow the legitimate recipient to determine that the MessageID 2983 cannot serve as a covert means of leaking cryptographic key 2984 information. 2985 2986 - "Hash", a comma-separated list of hash algorithms used in this 2987 message. This is used only in cleartext signed messages. 2988 2989 - "Charset", a description of the character set that the plaintext 2990 is in. Please note that OpenPGP defines text to be in UTF-8. An 2991 implementation will get best results by translating into and out 2992 of UTF-8. However, there are many instances where this is easier 2993 said than done. Also, there are communities of users who have no 2994 need for UTF-8 because they are all happy with a character set 2995 like ISO Latin-5 or a Japanese character set. In such instances, 2996 an implementation MAY override the UTF-8 default by using this 2997 header key. An implementation MAY implement this key and any 2998 translations it cares to; an implementation MAY ignore it and 2999 assume all text is UTF-8. 3000 3001 The Armor Tail Line is composed in the same manner as the Armor 3002 Header Line, except the string "BEGIN" is replaced by the string 3003 "END". 3004 30056.3. Encoding Binary in Radix-64 3006 3007 The encoding process represents 24-bit groups of input bits as 3008 output strings of 4 encoded characters. Proceeding from left to 3009 right, a 24-bit input group is formed by concatenating three 8-bit 3010 input groups. These 24 bits are then treated as four concatenated 3011 6-bit groups, each of which is translated into a single digit in the 3012 Radix-64 alphabet. When encoding a bit stream with the Radix-64 3013 encoding, the bit stream must be presumed to be ordered with the 3014 most-significant-bit first. That is, the first bit in the stream 3015 will be the high-order bit in the first 8-bit octet, and the eighth 3016 bit will be the low-order bit in the first 8-bit octet, and so on. 3017 3018 +--first octet--+-second octet--+--third octet--+ 3019 |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0| 3020 +-----------+---+-------+-------+---+-----------+ 3021 |5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0|5 4 3 2 1 0| 3022 +--1.index--+--2.index--+--3.index--+--4.index--+ 3023 3024Callas, et al. Expires Oct 24, 2007 [Page 54] 3025 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3026 3027 Each 6-bit group is used as an index into an array of 64 printable 3028 characters from the table below. The character referenced by the 3029 index is placed in the output string. 3030 3031 Value Encoding Value Encoding Value Encoding Value Encoding 3032 0 A 17 R 34 i 51 z 3033 1 B 18 S 35 j 52 0 3034 2 C 19 T 36 k 53 1 3035 3 D 20 U 37 l 54 2 3036 4 E 21 V 38 m 55 3 3037 5 F 22 W 39 n 56 4 3038 6 G 23 X 40 o 57 5 3039 7 H 24 Y 41 p 58 6 3040 8 I 25 Z 42 q 59 7 3041 9 J 26 a 43 r 60 8 3042 10 K 27 b 44 s 61 9 3043 11 L 28 c 45 t 62 + 3044 12 M 29 d 46 u 63 / 3045 13 N 30 e 47 v 3046 14 O 31 f 48 w (pad) = 3047 15 P 32 g 49 x 3048 16 Q 33 h 50 y 3049 3050 The encoded output stream must be represented in lines of no more 3051 than 76 characters each. 3052 3053 Special processing is performed if fewer than 24 bits are available 3054 at the end of the data being encoded. There are three possibilities: 3055 3056 1. The last data group has 24 bits (3 octets). No special 3057 processing is needed. 3058 3059 2. The last data group has 16 bits (2 octets). The first two 6-bit 3060 groups are processed as above. The third (incomplete) data group 3061 has two zero-value bits added to it, and is processed as above. 3062 A pad character (=) is added to the output. 3063 3064 3. The last data group has 8 bits (1 octet). The first 6-bit group 3065 is processed as above. The second (incomplete) data group has 3066 four zero-value bits added to it, and is processed as above. Two 3067 pad characters (=) are added to the output. 3068 30696.4. Decoding Radix-64 3070 3071 In Radix-64 data, characters other than those in the table, line 3072 breaks, and other white space probably indicate a transmission 3073 error, about which a warning message or even a message rejection 3074 might be appropriate under some circumstances. Decoding software 3075 must ignore all white space. 3076 3077 3078 3079 3080Callas, et al. Expires Oct 24, 2007 [Page 55] 3081 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3082 3083 Because it is used only for padding at the end of the data, the 3084 occurrence of any "=" characters may be taken as evidence that the 3085 end of the data has been reached (without truncation in transit). No 3086 such assurance is possible, however, when the number of octets 3087 transmitted was a multiple of three and no "=" characters are 3088 present. 3089 30906.5. Examples of Radix-64 3091 3092 Input data: 0x14fb9c03d97e 3093 Hex: 1 4 f b 9 c | 0 3 d 9 7 e 3094 8-bit: 00010100 11111011 10011100 | 00000011 11011001 11111110 3095 6-bit: 000101 001111 101110 011100 | 000000 111101 100111 111110 3096 Decimal: 5 15 46 28 0 61 37 62 3097 Output: F P u c A 9 l + 3098 Input data: 0x14fb9c03d9 3099 Hex: 1 4 f b 9 c | 0 3 d 9 3100 8-bit: 00010100 11111011 10011100 | 00000011 11011001 3101 pad with 00 3102 6-bit: 000101 001111 101110 011100 | 000000 111101 100100 3103 Decimal: 5 15 46 28 0 61 36 3104 pad with = 3105 Output: F P u c A 9 k = 3106 Input data: 0x14fb9c03 3107 Hex: 1 4 f b 9 c | 0 3 3108 8-bit: 00010100 11111011 10011100 | 00000011 3109 pad with 0000 3110 6-bit: 000101 001111 101110 011100 | 000000 110000 3111 Decimal: 5 15 46 28 0 48 3112 pad with = = 3113 Output: F P u c A w = = 3114 31156.6. Example of an ASCII Armored Message 3116 3117 -----BEGIN PGP MESSAGE----- 3118 Version: OpenPrivacy 0.99 3119 3120 yDgBO22WxBHv7O8X7O/jygAEzol56iUKiXmV+XmpCtmpqQUKiQrFqclFqUDBovzS 3121 vBSFjNSiVHsuAA== 3122 =njUN 3123 -----END PGP MESSAGE----- 3124 3125 Note that this example has extra indenting; an actual armored 3126 message would have no leading whitespace. 3127 31287. Cleartext signature framework 3129 3130 It is desirable to be able to sign a textual octet stream without 3131 ASCII armoring the stream itself, so the signed text is still 3132 readable without special software. In order to bind a signature to 3133 such a cleartext, this framework is used. (Note that this framework 3134 is not intended to be reversible. RFC 3156 defines another way to 3135 3136Callas, et al. Expires Oct 24, 2007 [Page 56] 3137 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3138 3139 sign cleartext messages for environments that support MIME.) 3140 3141 The cleartext signed message consists of: 3142 3143 - The cleartext header '-----BEGIN PGP SIGNED MESSAGE-----' on a 3144 single line, 3145 3146 - One or more "Hash" Armor Headers, 3147 3148 - Exactly one empty line not included into the message digest, 3149 3150 - The dash-escaped cleartext that is included into the message 3151 digest, 3152 3153 - The ASCII armored signature(s) including the '-----BEGIN PGP 3154 SIGNATURE-----' Armor Header and Armor Tail Lines. 3155 3156 If the "Hash" armor header is given, the specified message digest 3157 algorithm(s) are used for the signature. If there are no such 3158 headers, MD5 is used. If MD5 is the only hash used, then an 3159 implementation MAY omit this header for improved V2.x compatibility. 3160 If more than one message digest is used in the signature, the "Hash" 3161 armor header contains a comma-delimited list of used message 3162 digests. 3163 3164 Current message digest names are described below with the algorithm 3165 IDs. 3166 3167 An implementation SHOULD add a line break after the cleartext, but 3168 MAY omit it if the cleartext ends with a line break. This is for 3169 visual clarity. 3170 31717.1. Dash-Escaped Text 3172 3173 The cleartext content of the message must also be dash-escaped. 3174 3175 Dash escaped cleartext is the ordinary cleartext where every line 3176 starting with a dash '-' (0x2D) is prefixed by the sequence dash '-' 3177 (0x2D) and space ' ' (0x20). This prevents the parser from 3178 recognizing armor headers of the cleartext itself. An implementation 3179 MAY dash escape any line, SHOULD dash escape lines commencing "From" 3180 followed by a space, and MUST dash escape any line commencing in a 3181 dash. The message digest is computed using the cleartext itself, not 3182 the dash escaped form. 3183 3184 As with binary signatures on text documents, a cleartext signature 3185 is calculated on the text using canonical <CR><LF> line endings. The 3186 line ending (i.e. the <CR><LF>) before the '-----BEGIN PGP 3187 SIGNATURE-----' line that terminates the signed text is not 3188 considered part of the signed text. 3189 3190 3191 3192Callas, et al. Expires Oct 24, 2007 [Page 57] 3193 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3194 3195 When reversing dash-escaping, an implementation MUST strip the 3196 string "- " if it occurs at the beginning of a line, and SHOULD warn 3197 on "-" and any character other than a space at the beginning of a 3198 line. 3199 3200 Also, any trailing whitespace -- spaces (0x20) and tabs (0x09) -- at 3201 the end of any line is removed when the cleartext signature is 3202 generated. 3203 32048. Regular Expressions 3205 3206 A regular expression is zero or more branches, separated by '|'. It 3207 matches anything that matches one of the branches. 3208 3209 A branch is zero or more pieces, concatenated. It matches a match 3210 for the first, followed by a match for the second, etc. 3211 3212 A piece is an atom possibly followed by '*', '+', or '?'. An atom 3213 followed by '*' matches a sequence of 0 or more matches of the atom. 3214 An atom followed by '+' matches a sequence of 1 or more matches of 3215 the atom. An atom followed by '?' matches a match of the atom, or 3216 the null string. 3217 3218 An atom is a regular expression in parentheses (matching a match for 3219 the regular expression), a range (see below), '.' (matching any 3220 single character), '^' (matching the null string at the beginning of 3221 the input string), '$' (matching the null string at the end of the 3222 input string), a '\' followed by a single character (matching that 3223 character), or a single character with no other significance 3224 (matching that character). 3225 3226 A range is a sequence of characters enclosed in '[]'. It normally 3227 matches any single character from the sequence. If the sequence 3228 begins with '^', it matches any single character not from the rest 3229 of the sequence. If two characters in the sequence are separated by 3230 '-', this is shorthand for the full list of ASCII characters between 3231 them (e.g. '[0-9]' matches any decimal digit). To include a literal 3232 ']' in the sequence, make it the first character (following a 3233 possible '^'). To include a literal '-', make it the first or last 3234 character. 3235 32369. Constants 3237 3238 This section describes the constants used in OpenPGP. 3239 3240 Note that these tables are not exhaustive lists; an implementation 3241 MAY implement an algorithm not on these lists, so long as the 3242 algorithm number(s) are chosen from the private or experimental 3243 algorithm range. 3244 3245 3246 3247 3248Callas, et al. Expires Oct 24, 2007 [Page 58] 3249 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3250 3251 See the section "Notes on Algorithms" below for more discussion of 3252 the algorithms. 3253 32549.1. Public Key Algorithms 3255 3256 ID Algorithm 3257 -- --------- 3258 1 - RSA (Encrypt or Sign) [HAC] 3259 2 - RSA Encrypt-Only [HAC] 3260 3 - RSA Sign-Only [HAC] 3261 16 - Elgamal (Encrypt-Only), see [ELGAMAL] [HAC] 3262 17 - DSA (Digital Signature Algorithm) [FIPS186] [HAC] 3263 18 - Reserved for Elliptic Curve 3264 19 - Reserved for ECDSA 3265 20 - Reserved (formerly Elgamal Encrypt or Sign) 3266 21 - Reserved for Diffie-Hellman (X9.42, 3267 as defined for IETF-S/MIME) 3268 100 to 110 - Private/Experimental algorithm. 3269 3270 Implementations MUST implement DSA for signatures, and Elgamal for 3271 encryption. Implementations SHOULD implement RSA keys (1). RSA 3272 Encrypt-Only (2) and RSA Sign-Only are deprecated and SHOULD NOT be 3273 generated, but may be interpreted. See Section 13.5. See Section 3274 13.8 for notes on Elliptic Curve (18), ECDSA (19), Elgamal Encrypt 3275 or Sign (20), and X9.42 (21). Implementations MAY implement any 3276 other algorithm. 3277 32789.2. Symmetric Key Algorithms 3279 3280 ID Algorithm 3281 -- --------- 3282 0 - Plaintext or unencrypted data 3283 1 - IDEA [IDEA] 3284 2 - TripleDES (DES-EDE, [SCHNEIER] [HAC] - 3285 168 bit key derived from 192) 3286 3 - CAST5 (128 bit key, as per RFC 2144) 3287 4 - Blowfish (128 bit key, 16 rounds) [BLOWFISH] 3288 5 - Reserved 3289 6 - Reserved 3290 7 - AES with 128-bit key [AES] 3291 8 - AES with 192-bit key 3292 9 - AES with 256-bit key 3293 10 - Twofish with 256-bit key [TWOFISH] 3294 100 to 110 - Private/Experimental algorithm. 3295 3296 Implementations MUST implement TripleDES. Implementations SHOULD 3297 implement AES-128 and CAST5. Implementations that interoperate with 3298 PGP 2.6 or earlier need to support IDEA, as that is the only 3299 symmetric cipher those versions use. Implementations MAY implement 3300 any other algorithm. 3301 3302 3303 3304Callas, et al. Expires Oct 24, 2007 [Page 59] 3305 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3306 33079.3. Compression Algorithms 3308 3309 ID Algorithm 3310 -- --------- 3311 0 - Uncompressed 3312 1 - ZIP [RFC 1951] 3313 2 - ZLIB [RFC 1950] 3314 3 - BZip2 [BZ2] 3315 100 to 110 - Private/Experimental algorithm. 3316 3317 Implementations MUST implement uncompressed data. Implementations 3318 SHOULD implement ZIP. Implementations MAY implement any other 3319 algorithm. 3320 33219.4. Hash Algorithms 3322 3323 ID Algorithm Text Name 3324 -- --------- ---- ---- 3325 1 - MD5 [HAC] "MD5" 3326 2 - SHA-1 [FIPS180] "SHA1" 3327 3 - RIPE-MD/160 [HAC] "RIPEMD160" 3328 4 - Reserved 3329 5 - Reserved 3330 6 - Reserved 3331 7 - Reserved 3332 8 - SHA256 [FIPS180] "SHA256" 3333 9 - SHA384 [FIPS180] "SHA384" 3334 10 - SHA512 [FIPS180] "SHA512" 3335 11 - SHA224 [FIPS180] "SHA224" 3336 100 to 110 - Private/Experimental algorithm. 3337 3338 Implementations MUST implement SHA-1. Implementations MAY implement 3339 other algorithms. MD5 is deprecated. 3340 334110. IANA Considerations 3342 3343 OpenPGP is highly parameterized and consequently there are a number 3344 of considerations for allocating parameters for extensions. This 3345 section describes how IANA should look at extensions to the protocol 3346 as described in this document. 3347 334810.1. New String-to-Key specifier types 3349 3350 OpenPGP S2K specifiers contain a mechanism for new algorithms to 3351 turn a string into a key. This specification creates a registry of 3352 S2K specifier types. The registry includes the S2K type, the name of 3353 the S2K and a reference to the defining specification. The initial 3354 values for this registry can be found in 3.7.1. Adding a new S2K 3355 specifier MUST be done through the IETF CONSENSUS method, as 3356 described in [RFC2434]. 3357 3358 3359 3360Callas, et al. Expires Oct 24, 2007 [Page 60] 3361 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3362 336310.2. New Packets 3364 3365 Major new features of OpenPGP are defined though new packet types. 3366 This specification creates a registry of packet types. The registry 3367 includes the packet type, the name of the packet and a reference to 3368 the defining specification. The initial values for this registry can 3369 be found in 4.3. Adding a new packet type MUST be done through the 3370 IETF CONSENSUS method, as described in [RFC2434]. 3371 337210.2.1. User Attribute Types 3373 3374 The User Attribute packet permits an extensible mechanism for other 3375 types of certificate identification. This specification creates a 3376 registry of User Attribute types. The registry includes the User 3377 Attribute type, the name of the User Attribute and a reference to 3378 the defining specification. The initial values for this registry can 3379 be found in 5.12. Adding a new User Attribute type MUST be done 3380 through the IETF CONSENSUS method, as described in [RFC2434]. 3381 338210.2.1.1. Image Format Subpacket Types 3383 3384 Within User Attribute packets, there is an extensible mechanism for 3385 other types of image-based user attributes. This specification 3386 creates a registry of Image Attribute subpacket types. The registry 3387 includes the Image Attribute subpacket type, the name of the Image 3388 Attribute subpacket and a reference to the defining specification. 3389 The initial values for this registry can be found in 5.12.1. Adding 3390 a new Image Attribute subpacket type MUST be done through the IETF 3391 CONSENSUS method, as described in [RFC2434]. 3392 339310.2.2. New Signature Subpackets 3394 3395 OpenPGP signatures contain a mechanism for signed (or unsigned) data 3396 to be added to them for a variety of purposes in the signature 3397 subpackets as discussed in section 5.2.3.1. This specification 3398 creates a registry of signature subpacket types. The registry 3399 includes the signature subpacket type, the name of the subpacket and 3400 a reference to the defining specification. The initial values for 3401 this registry can be found in 5.2.3.1. Adding a new signature 3402 subpacket MUST be done through the IETF CONSENSUS method, as 3403 described in [RFC2434]. 3404 340510.2.2.1. Signature Notation Data Subpackets 3406 3407 OpenPGP signatures further contain a mechanism for extensions in 3408 signatures. These are the Notation Data subpackets, which contain a 3409 key/value pair. Notations contain a user space which is completely 3410 unmanaged and an IETF space. 3411 3412 This specification creates a registry of Signature Notation Data 3413 types. The registry includes the Signature Notation Data type, the 3414 name of the Signature Notation Data, its allowed values, and a 3415 3416Callas, et al. Expires Oct 24, 2007 [Page 61] 3417 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3418 3419 reference to the defining specification. The initial values for this 3420 registry can be found in 5.2.3.16. Adding a new Signature Notation 3421 Data subpacket MUST be done through the EXPERT REVIEW method, as 3422 described in [RFC2434]. 3423 342410.2.2.2. Key Server Preference Extensions 3425 3426 OpenPGP signatures contain a mechanism for preferences to be 3427 specified about key servers. This specification creates a registry 3428 of key server preferences. The registry includes the key server 3429 preference, the name of the preference and a reference to the 3430 defining specification. The initial values for this registry can be 3431 found in 5.2.3.17. Adding a new key server preference MUST be done 3432 through the IETF CONSENSUS method, as described in [RFC2434]. 3433 343410.2.2.3. Key Flags Extensions 3435 3436 OpenPGP signatures contain a mechanism for flags to be specified 3437 about key usage. This specification creates a registry of key usage 3438 flags. The registry includes the key flags value, the name of the 3439 flag and a reference to the defining specification. The initial 3440 values for this registry can be found in 5.2.3.21. Adding a new key 3441 usage flag MUST be done through the IETF CONSENSUS method, as 3442 described in [RFC2434]. 3443 344410.2.2.4. Reason For Revocation Extensions 3445 3446 OpenPGP signatures contain a mechanism for flags to be specified 3447 about why a key was revoked. This specification creates a registry 3448 of reason-for-revocation flags. The registry includes the 3449 reason-for-revocation flags value, the name of the flag and a 3450 reference to the defining specification. The initial values for this 3451 registry can be found in 5.2.3.23. Adding a new feature flag MUST be 3452 done through the IETF CONSENSUS method, as described in [RFC2434]. 3453 345410.2.2.5. Implementation Features 3455 3456 OpenPGP signatures contain a mechanism for flags to be specified 3457 stating which optional features an implementation supports. This 3458 specification creates a registry of feature-implementation flags. 3459 The registry includes the feature-implementation flags value, the 3460 name of the flag and a reference to the defining specification. The 3461 initial values for this registry can be found in 5.2.3.24. Adding a 3462 new feature-implementation flag MUST be done through the IETF 3463 CONSENSUS method, as described in [RFC2434]. 3464 3465 Also see section 10.6 for more information about when feature flags 3466 are needed. 3467 346810.2.3. New Packet Versions 3469 3470 The core OpenPGP packets all have version numbers, and can be 3471 3472Callas, et al. Expires Oct 24, 2007 [Page 62] 3473 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3474 3475 revised by introducing a new version of an existing packet. This 3476 specification creates a registry of packet types. The registry 3477 includes the packet type, the number of the version and a reference 3478 to the defining specification. The initial values for this registry 3479 can be found in 5. Adding a new packet version MUST be done through 3480 the IETF CONSENSUS method, as described in [RFC2434]. 3481 348210.3. New Algorithms 3483 3484 Chapter 9 lists the core algorithms that OpenPGP uses. Adding in a 3485 new algorithm is usually simple. For example, adding in a new 3486 symmetric cipher usually would not need anything more than 3487 allocating a constant for that cipher. If that cipher had other than 3488 a 64-bit or 128-bit block size, there might need to be additional 3489 documentation describing how OpenPGP-CFB mode would be adjusted. 3490 Similarly, when DSA was expanded from a maximum of 1024-bit public 3491 keys to 3072-bit public keys, the revision of FIPS 186 contained 3492 enough information itself to allow implementation. Changes to this 3493 document were emphasis more than required. 3494 349510.3.1. Public Key Algorithms 3496 3497 OpenPGP specifies a number of public key algorithms. This 3498 specification creates a registry of public key algorithm 3499 identifiers. The registry includes the algorithm name, its key sizes 3500 and parameters, and a reference to the defining specification. The 3501 initial values for this registry can be found in section 9. Adding a 3502 new public key algorithm MUST be done through the IETF CONSENSUS 3503 method, as described in [RFC2434]. 3504 350510.3.2. Symmetric Key Algorithms 3506 3507 OpenPGP specifies a number of symmetric key algorithms. This 3508 specification creates a registry of symmetric key algorithm 3509 identifiers. The registry includes the algorithm name, its key sizes 3510 and block size, and a reference to the defining specification. The 3511 initial values for this registry can be found in section 9. Adding a 3512 new symmetric key algorithm MUST be done through the IETF CONSENSUS 3513 method, as described in [RFC2434]. 3514 351510.3.3. Hash Algorithms 3516 3517 OpenPGP specifies a number of hash algorithms. This specification 3518 creates a registry of hash algorithm identifiers. The registry 3519 includes the algorithm name, a text representation of that name, its 3520 block size, an OID hash prefix, and a reference to the defining 3521 specification. The initial values for this registry can be found in 3522 section 9 for the algorithm identifiers and text names, and section 3523 5.2.2 for the OIDs and expanded signature prefixes. Adding a new 3524 hash algorithm MUST be done through the IETF CONSENSUS method, as 3525 described in [RFC2434]. 3526 3527 3528Callas, et al. Expires Oct 24, 2007 [Page 63] 3529 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3530 353110.3.4. Compression Algorithms 3532 3533 OpenPGP specifies a number of compression algorithms. This 3534 specification creates a registry of compression algorithm 3535 identifiers. The registry includes the algorithm name, and a 3536 reference to the defining specification. The initial values for this 3537 registry can be found in section 9.3. Adding a new compression key 3538 algorithm MUST be done through the IETF CONSENSUS method, as 3539 described in [RFC2434]. 3540 354111. Packet Composition 3542 3543 OpenPGP packets are assembled into sequences in order to create 3544 messages and to transfer keys. Not all possible packet sequences are 3545 meaningful and correct. This section describes the rules for how 3546 packets should be placed into sequences. 3547 354811.1. Transferable Public Keys 3549 3550 OpenPGP users may transfer public keys. The essential elements of a 3551 transferable public key are: 3552 3553 - One Public Key packet 3554 3555 - Zero or more revocation signatures 3556 3557 - One or more User ID packets 3558 3559 - After each User ID packet, zero or more signature packets 3560 (certifications) 3561 3562 - Zero or more User Attribute packets 3563 3564 - After each User Attribute packet, zero or more signature packets 3565 (certifications) 3566 3567 - Zero or more Subkey packets 3568 3569 - After each Subkey packet, one signature packet, plus optionally 3570 a revocation. 3571 3572 The Public Key packet occurs first. Each of the following User ID 3573 packets provides the identity of the owner of this public key. If 3574 there are multiple User ID packets, this corresponds to multiple 3575 means of identifying the same unique individual user; for example, a 3576 user may have more than one email address, and construct a User ID 3577 for each one. 3578 3579 Immediately following each User ID packet, there are zero or more 3580 signature packets. Each signature packet is calculated on the 3581 immediately preceding User ID packet and the initial Public Key 3582 packet. The signature serves to certify the corresponding public key 3583 3584Callas, et al. Expires Oct 24, 2007 [Page 64] 3585 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3586 3587 and User ID. In effect, the signer is testifying to his or her 3588 belief that this public key belongs to the user identified by this 3589 User ID. 3590 3591 Within the same section as the User ID packets, there are zero or 3592 more User Attribute packets. Like the User ID packets, a User 3593 Attribute packet is followed by zero or more signature packets 3594 calculated on the immediately preceding User Attribute packet and 3595 the initial Public Key packet. 3596 3597 User Attribute packets and User ID packets may be freely intermixed 3598 in this section, so long as the signatures that follow them are 3599 maintained on the proper User Attribute or User ID packet. 3600 3601 After the User ID or Attribute packets there may be zero or more 3602 Subkey packets. In general, subkeys are provided in cases where the 3603 top-level public key is a signature-only key. However, any V4 key 3604 may have subkeys, and the subkeys may be encryption-only keys, 3605 signature-only keys, or general-purpose keys. V3 keys MUST NOT have 3606 subkeys. 3607 3608 Each Subkey packet MUST be followed by one Signature packet, which 3609 should be a subkey binding signature issued by the top level key. 3610 For subkeys that can issue signatures, the subkey binding signature 3611 MUST contain an embedded signature subpacket with a primary key 3612 binding signature (0x19) issued by the subkey on the top level key. 3613 3614 Subkey and Key packets may each be followed by a revocation 3615 Signature packet to indicate that the key is revoked. Revocation 3616 signatures are only accepted if they are issued by the key itself, 3617 or by a key that is authorized to issue revocations via a revocation 3618 key subpacket in a self-signature by the top level key. 3619 3620 Transferable public key packet sequences may be concatenated to 3621 allow transferring multiple public keys in one operation. 3622 362311.2. Transferable Secret Keys 3624 3625 OpenPGP users may transfer secret keys. The format of a transferable 3626 secret key is the same as a transferable public key except that 3627 secret key and secret subkey packets are used instead of the public 3628 key and public subkey packets. Implementations SHOULD include 3629 self-signatures on any user IDs and subkeys, as this allows for a 3630 complete public key to be automatically extracted from the 3631 transferable secret key. Implementations MAY choose to omit the 3632 self-signatures, especially if a transferable public key accompanies 3633 the transferable secret key. 3634 363511.3. OpenPGP Messages 3636 3637 An OpenPGP message is a packet or sequence of packets that 3638 corresponds to the following grammatical rules (comma represents 3639 3640Callas, et al. Expires Oct 24, 2007 [Page 65] 3641 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3642 3643 sequential composition, and vertical bar separates alternatives): 3644 3645 OpenPGP Message :- Encrypted Message | Signed Message | 3646 Compressed Message | Literal Message. 3647 3648 Compressed Message :- Compressed Data Packet. 3649 3650 Literal Message :- Literal Data Packet. 3651 3652 ESK :- Public Key Encrypted Session Key Packet | 3653 Symmetric-Key Encrypted Session Key Packet. 3654 3655 ESK Sequence :- ESK | ESK Sequence, ESK. 3656 3657 Encrypted Data :- Symmetrically Encrypted Data Packet | 3658 Symmetrically Encrypted Integrity Protected Data Packet 3659 3660 Encrypted Message :- Encrypted Data | ESK Sequence, Encrypted Data. 3661 3662 One-Pass Signed Message :- One-Pass Signature Packet, 3663 OpenPGP Message, Corresponding Signature Packet. 3664 3665 Signed Message :- Signature Packet, OpenPGP Message | 3666 One-Pass Signed Message. 3667 3668 In addition, decrypting a Symmetrically Encrypted Data Packet or a 3669 Symmetrically Encrypted Integrity Protected Data Packet as well as 3670 decompressing a Compressed Data packet must yield a valid OpenPGP 3671 Message. 3672 367311.4. Detached Signatures 3674 3675 Some OpenPGP applications use so-called "detached signatures." For 3676 example, a program bundle may contain a file, and with it a second 3677 file that is a detached signature of the first file. These detached 3678 signatures are simply a signature packet stored separately from the 3679 data that they are a signature of. 3680 368112. Enhanced Key Formats 3682 368312.1. Key Structures 3684 3685 The format of an OpenPGP V3 key is as follows. Entries in square 3686 brackets are optional and ellipses indicate repetition. 3687 3688 RSA Public Key 3689 [Revocation Self Signature] 3690 User ID [Signature ...] 3691 [User ID [Signature ...] ...] 3692 3693 3694 3695 3696Callas, et al. Expires Oct 24, 2007 [Page 66] 3697 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3698 3699 Each signature certifies the RSA public key and the preceding User 3700 ID. The RSA public key can have many User IDs and each User ID can 3701 have many signatures. V3 keys are deprecated. Implementations MUST 3702 NOT generate new V3 keys, but MAY continue to use existing ones. 3703 3704 The format of an OpenPGP V4 key that uses multiple public keys is 3705 similar except that the other keys are added to the end as "subkeys" 3706 of the primary key. 3707 3708 Primary-Key 3709 [Revocation Self Signature] 3710 [Direct Key Signature...] 3711 User ID [Signature ...] 3712 [User ID [Signature ...] ...] 3713 [User Attribute [Signature ...] ...] 3714 [[Subkey [Binding-Signature-Revocation] 3715 Primary-Key-Binding-Signature] ...] 3716 3717 A subkey always has a single signature after it that is issued using 3718 the primary key to tie the two keys together. This binding signature 3719 may be in either V3 or V4 format, but SHOULD be V4. Subkeys that can 3720 issue signatures MUST have a V4 binding signature due to the 3721 REQUIRED embedded primary key binding signature. 3722 3723 In the above diagram, if the binding signature of a subkey has been 3724 revoked, the revoked key may be removed, leaving only one key. 3725 3726 In a V4 key, the primary key MUST be a key capable of certification. 3727 The subkeys may be keys of any other type. There may be other 3728 constructions of V4 keys, too. For example, there may be a 3729 single-key RSA key in V4 format, a DSA primary key with an RSA 3730 encryption key, or RSA primary key with an Elgamal subkey, etc. 3731 3732 It is also possible to have a signature-only subkey. This permits a 3733 primary key that collects certifications (key signatures) but is 3734 used only used for certifying subkeys that are used for encryption 3735 and signatures. 3736 373712.2. Key IDs and Fingerprints 3738 3739 For a V3 key, the eight-octet key ID consists of the low 64 bits of 3740 the public modulus of the RSA key. 3741 3742 The fingerprint of a V3 key is formed by hashing the body (but not 3743 the two-octet length) of the MPIs that form the key material (public 3744 modulus n, followed by exponent e) with MD5. Note that both V3 keys 3745 and MD5 are deprecated. 3746 3747 A V4 fingerprint is the 160-bit SHA-1 hash of the octet 0x99, 3748 followed by the two-octet packet length, followed by the entire 3749 Public Key packet starting with the version field. The key ID is the 3750 low order 64 bits of the fingerprint. Here are the fields of the 3751 3752Callas, et al. Expires Oct 24, 2007 [Page 67] 3753 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3754 3755 hash material, with the example of a DSA key: 3756 3757 a.1) 0x99 (1 octet) 3758 3759 a.2) high order length octet of (b)-(f) (1 octet) 3760 3761 a.3) low order length octet of (b)-(f) (1 octet) 3762 3763 b) version number = 4 (1 octet); 3764 3765 c) time stamp of key creation (4 octets); 3766 3767 d) algorithm (1 octet): 17 = DSA (example); 3768 3769 e) Algorithm specific fields. 3770 3771 Algorithm Specific Fields for DSA keys (example): 3772 3773 e.1) MPI of DSA prime p; 3774 3775 e.2) MPI of DSA group order q (q is a prime divisor of p-1); 3776 3777 e.3) MPI of DSA group generator g; 3778 3779 e.4) MPI of DSA public key value y (= g**x mod p where x is secret). 3780 3781 Note that it is possible for there to be collisions of key IDs -- 3782 two different keys with the same key ID. Note that there is a much 3783 smaller, but still non-zero probability that two different keys have 3784 the same fingerprint. 3785 3786 Also note that if V3 and V4 format keys share the same RSA key 3787 material, they will have different key IDs as well as different 3788 fingerprints. 3789 3790 Finally, the key ID and fingerprint of a subkey are calculated in 3791 the same way as for a primary key, including the 0x99 as the first 3792 octet (even though this is not a valid packet ID for a public 3793 subkey). 3794 379513. Notes on Algorithms 3796 379713.1. PKCS#1 Encoding In OpenPGP 3798 3799 This standard makes use of the PKCS#1 functions EME-PKCS1-v1_5 and 3800 EMSA-PKCS1-v1_5. However, the calling conventions of these functions 3801 has changed in the past. To avoid potential confusion and 3802 interoperability problems, we are including local copies in this 3803 document, adapted from those in PKCS#1 v2.1 [RFC3447]. RFC-3447 3804 should be treated as the ultimate authority on PKCS#1 for OpenPGP. 3805 Nonetheless, we believe that there is value in having a 3806 self-contained document that avoids problems in the future with 3807 3808Callas, et al. Expires Oct 24, 2007 [Page 68] 3809 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3810 3811 needed changes in the conventions. 3812 381313.1.1. EME-PKCS1-v1_5-ENCODE 3814 3815 Input: 3816 3817 k = the length in octets of the key modulus 3818 3819 M = message to be encoded, an octet string of length mLen, where 3820 mLen <= k - 11 3821 3822 Output: 3823 3824 EM = encoded message, an octet string of length k 3825 3826 Error: "message too long" 3827 3828 1. Length checking: If mLen > k - 11, output "message too long" and 3829 stop. 3830 3831 2. Generate an octet string PS of length k - mLen - 3 consisting of 3832 pseudo-randomly generated nonzero octets. The length of PS will 3833 be at least eight octets. 3834 3835 3. Concatenate PS, the message M, and other padding to form an 3836 encoded message EM of length k octets as 3837 3838 EM = 0x00 || 0x02 || PS || 0x00 || M. 3839 3840 4. Output EM. 3841 384213.1.2. EME-PKCS1-v1_5-DECODE 3843 3844 Input: 3845 3846 EM = encoded message, an octet string 3847 3848 Output: 3849 3850 M = message, an octet string 3851 3852 Error: "decryption error" 3853 3854 To decode an EME-PKCS1_v1_5 message, separate the encoded message EM 3855 into an octet string PS consisting of nonzero octets and a message M 3856 as 3857 3858 EM = 0x00 || 0x02 || PS || 0x00 || M. 3859 3860 If the first octet of EM does not have hexadecimal value 0x00, if 3861 the second octet of EM does not have hexadecimal value 0x02, if 3862 there is no octet with hexadecimal value 0x00 to separate PS from M, 3863 3864Callas, et al. Expires Oct 24, 2007 [Page 69] 3865 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3866 3867 or if the length of PS is less than 8 octets, output "decryption 3868 error" and stop. See also the security note in section 13 regarding 3869 differences in reporting between a decryption error and a padding 3870 error. 3871 387213.1.3. EMSA-PKCS1-v1_5 3873 3874 This encoding method is deterministic and only has an encoding 3875 operation. 3876 3877 Option: 3878 3879 Hash hash function (hLen denotes the length in octets of the hash 3880 function output) 3881 3882 Input: 3883 3884 M = message to be encoded 3885 3886 mL = intended length in octets of the encoded message, at least tLen 3887 + 11, where tLen is the octet length of the DER encoding T of a 3888 certain value computed during the encoding operation 3889 3890 Output: 3891 3892 EM = encoded message, an octet string of length emLen 3893 3894 Errors: "message too long"; "intended encoded message length too 3895 short" 3896 3897 Steps: 3898 3899 1. Apply the hash function to the message M to produce a hash value 3900 H: 3901 3902 H = Hash(M). 3903 3904 If the hash function outputs "message too long," output "message 3905 too long" and stop. 3906 3907 2. Using the list in section 5.2.2, produce an ASN.1 DER value for 3908 the hash function used. Let T be the full hash prefix from 3909 section 5.2.2, and let tLen be the length in octets of T. 3910 3911 3. If emLen < tLen + 11, output "intended encoded message length 3912 too short" and stop. 3913 3914 4. Generate an octet string PS consisting of emLen - tLen - 3 3915 octets with hexadecimal value 0xff. The length of PS will be at 3916 least 8 octets. 3917 3918 3919 3920Callas, et al. Expires Oct 24, 2007 [Page 70] 3921 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3922 3923 5. Concatenate PS, the hash prefix T, and other padding to form the 3924 encoded message EM as 3925 3926 EM = 0x00 || 0x01 || PS || 0x00 || T. 3927 3928 6. Output EM. 3929 393013.2. Symmetric Algorithm Preferences 3931 3932 The symmetric algorithm preference is an ordered list of algorithms 3933 that the keyholder accepts. Since it is found on a self-signature, 3934 it is possible that a keyholder may have multiple, different 3935 preferences. For example, Alice may have TripleDES only specified 3936 for "alice@work.com" but CAST5, Blowfish, and TripleDES specified 3937 for "alice@home.org". Note that it is also possible for preferences 3938 to be in a subkey's binding signature. 3939 3940 Since TripleDES is the MUST-implement algorithm, if it is not 3941 explicitly in the list, it is tacitly at the end. However, it is 3942 good form to place it there explicitly. Note also that if an 3943 implementation does not implement the preference, then it is 3944 implicitly a TripleDES-only implementation. 3945 3946 An implementation MUST NOT use a symmetric algorithm that is not in 3947 the recipient's preference list. When encrypting to more than one 3948 recipient, the implementation finds a suitable algorithm by taking 3949 the intersection of the preferences of the recipients. Note that the 3950 MUST-implement algorithm, TripleDES, ensures that the intersection 3951 is not null. The implementation may use any mechanism to pick an 3952 algorithm in the intersection. 3953 3954 If an implementation can decrypt a message that a keyholder doesn't 3955 have in their preferences, the implementation SHOULD decrypt the 3956 message anyway, but MUST warn the keyholder that the protocol has 3957 been violated. For example, suppose that Alice, above, has software 3958 that implements all algorithms in this specification. Nonetheless, 3959 she prefers subsets for work or home. If she is sent a message 3960 encrypted with IDEA, which is not in her preferences, the software 3961 warns her that someone sent her an IDEA-encrypted message, but it 3962 would ideally decrypt it anyway. 3963 396413.3. Other Algorithm Preferences 3965 3966 Other algorithm preferences work similarly to the symmetric 3967 algorithm preference, in that they specify which algorithms the 3968 keyholder accepts. There are two interesting cases that other 3969 comments need to be made about, though, the compression preferences 3970 and the hash preferences. 3971 397213.3.1. Compression Preferences 3973 3974 Compression has been an integral part of PGP since its first days. 3975 3976Callas, et al. Expires Oct 24, 2007 [Page 71] 3977 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 3978 3979 OpenPGP and all previous versions of PGP have offered compression. 3980 In this specification, the default is for messages to be compressed, 3981 although an implementation is not required to do so. Consequently, 3982 the compression preference gives a way for a keyholder to request 3983 that messages not be compressed, presumably because they are using a 3984 minimal implementation that does not include compression. 3985 Additionally, this gives a keyholder a way to state that it can 3986 support alternate algorithms. 3987 3988 Like the algorithm preferences, an implementation MUST NOT use an 3989 algorithm that is not in the preference vector. If the preferences 3990 are not present, then they are assumed to be [ZIP(1), 3991 UNCOMPRESSED(0)]. 3992 3993 Additionally, an implementation MUST implement this preference to 3994 the degree of recognizing when to send an uncompressed message. A 3995 robust implementation would satisfy this requirement by looking at 3996 the recipient's preference and acting accordingly. A minimal 3997 implementation can satisfy this requirement by never generating a 3998 compressed message, since all implementations can handle messages 3999 that have not been compressed. 4000 400113.3.2. Hash Algorithm Preferences 4002 4003 Typically, the choice of a hash algorithm is something the signer 4004 does, rather than the verifier, because a signer rarely knows who is 4005 going to be verifying the signature. This preference, though, allows 4006 a protocol based upon digital signatures ease in negotiation. 4007 4008 Thus, if Alice is authenticating herself to Bob with a signature, it 4009 makes sense for her to use a hash algorithm that Bob's software 4010 uses. This preference allows Bob to state in his key which 4011 algorithms Alice may use. 4012 4013 Since SHA1 is the MUST-implement hash algorithm, if it is not 4014 explicitly in the list, it is tacitly at the end. However, it is 4015 good form to place it there explicitly. 4016 401713.4. Plaintext 4018 4019 Algorithm 0, "plaintext," may only be used to denote secret keys 4020 that are stored in the clear. Implementations MUST NOT use plaintext 4021 in Symmetrically Encrypted Data Packets; they must use Literal Data 4022 Packets to encode unencrypted or literal data. 4023 402413.5. RSA 4025 4026 There are algorithm types for RSA Sign-Only, and RSA Encrypt-Only 4027 keys. These types are deprecated. The "key flags" subpacket in a 4028 signature is a much better way to express the same idea, and 4029 generalizes it to all algorithms. An implementation SHOULD NOT 4030 create such a key, but MAY interpret it. 4031 4032Callas, et al. Expires Oct 24, 2007 [Page 72] 4033 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 4034 4035 An implementation SHOULD NOT implement RSA keys of size less than 4036 1024 bits. 4037 403813.6. DSA 4039 4040 An implementation SHOULD NOT implement DSA keys of size less than 4041 1024 bits. It MUST NOT implement a DSA key with a q size of less 4042 than 160 bits. DSA keys MUST also be a multiple of 64 bits, and the 4043 q size MUST be a multiple of 8 bits. The Digital Signature Standard 4044 (DSS) [FIPS186] specifies that DSA be used in one of the following 4045 ways: 4046 4047 * 1024-bit key, 160-bit q, SHA-1, SHA-224, SHA-256, SHA-384 or 4048 SHA-512 hash 4049 4050 * 2048-bit key, 224-bit q, SHA-224, SHA-256, SHA-384 or SHA-512 4051 hash 4052 4053 * 2048-bit key, 256-bit q, SHA-256, SHA-384 or SHA-512 hash 4054 4055 * 3072-bit key, 256-bit q, SHA-256, SHA-384 or SHA-512 hash 4056 4057 The above key and q size pairs were chosen to best balance the 4058 strength of the key with the strength of the hash. Implementations 4059 SHOULD use one of the above key and q size pairs when generating DSA 4060 keys. If DSS compliance is desired, one of the specified SHA hashes 4061 must be used as well. [FIPS186] is the ultimate authority on DSS, 4062 and should be consulted for all questions of DSS compliance. 4063 4064 Note that earlier versions of this standard only allowed a 160-bit q 4065 with no truncation allowed, so earlier implementations may not be 4066 able to handle signatures with a different q size or a truncated 4067 hash. 4068 406913.7. Elgamal 4070 4071 An implementation SHOULD NOT implement Elgamal keys of size less 4072 than 1024 bits. 4073 407413.8. Reserved Algorithm Numbers 4075 4076 A number of algorithm IDs have been reserved for algorithms that 4077 would be useful to use in an OpenPGP implementation, yet there are 4078 issues that prevent an implementer from actually implementing the 4079 algorithm. These are marked in the Public Algorithms section as 4080 "(reserved for)". 4081 4082 The reserved public key algorithms, Elliptic Curve (18), ECDSA (19), 4083 and X9.42 (21) do not have the necessary parameters, parameter 4084 order, or semantics defined. 4085 4086 4087 4088Callas, et al. Expires Oct 24, 2007 [Page 73] 4089 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 4090 4091 Previous versions of OpenPGP permitted Elgamal [ELGAMAL] signatures 4092 with a public key identifier of 20. These are no longer permitted. 4093 An implementation MUST NOT generate such keys. An implementation 4094 MUST NOT generate Elgamal signatures. See [BLEICHENBACHER]. 4095 409613.9. OpenPGP CFB mode 4097 4098 OpenPGP does symmetric encryption using a variant of Cipher Feedback 4099 Mode (CFB mode). This section describes the procedure it uses in 4100 detail. This mode is what is used for Symmetrically Encrypted Data 4101 Packets; the mechanism used for encrypting secret key material is 4102 similar, but described in those sections above. 4103 4104 In the description below, the value BS is the block size in octets 4105 of the cipher. Most ciphers have a block size of 8 octets. The AES 4106 and Twofish have a block size of 16 octets. Also note that the 4107 description below assumes that the IV and CFB arrays start with an 4108 index of 1 (unlike the C language, which assumes arrays start with a 4109 zero index). 4110 4111 OpenPGP CFB mode uses an initialization vector (IV) of all zeros, 4112 and prefixes the plaintext with BS+2 octets of random data, such 4113 that octets BS+1 and BS+2 match octets BS-1 and BS. It does a CFB 4114 resynchronization after encrypting those BS+2 octets. 4115 4116 Thus, for an algorithm that has a block size of 8 octets (64 bits), 4117 the IV is 10 octets long and octets 7 and 8 of the IV are the same 4118 as octets 9 and 10. For an algorithm with a block size of 16 octets 4119 (128 bits), the IV is 18 octets long, and octets 17 and 18 replicate 4120 octets 15 and 16. Those extra two octets are an easy check for a 4121 correct key. 4122 4123 Step by step, here is the procedure: 4124 4125 1. The feedback register (FR) is set to the IV, which is all zeros. 4126 4127 2. FR is encrypted to produce FRE (FR Encrypted). This is the 4128 encryption of an all-zero value. 4129 4130 3. FRE is xored with the first BS octets of random data prefixed to 4131 the plaintext to produce C[1] through C[BS], the first BS octets 4132 of ciphertext. 4133 4134 4. FR is loaded with C[1] through C[BS]. 4135 4136 5. FR is encrypted to produce FRE, the encryption of the first BS 4137 octets of ciphertext. 4138 4139 6. The left two octets of FRE get xored with the next two octets of 4140 data that were prefixed to the plaintext. This produces C[BS+1] 4141 and C[BS+2], the next two octets of ciphertext. 4142 4143 4144Callas, et al. Expires Oct 24, 2007 [Page 74] 4145 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 4146 4147 7. (The resynchronization step) FR is loaded with C[3] through 4148 C[BS+2]. 4149 4150 8. FR is encrypted to produce FRE. 4151 4152 9. FRE is xored with the first BS octets of the given plaintext, 4153 now that we have finished encrypting the BS+2 octets of prefixed 4154 data. This produces C[BS+3] through C[BS+(BS+2)], the next BS 4155 octets of ciphertext. 4156 4157 10. FR is loaded with C[BS+3] to C[BS + (BS+2)] (which is C11-C18 4158 for an 8-octet block). 4159 4160 11. FR is encrypted to produce FRE. 4161 4162 12. FRE is xored with the next BS octets of plaintext, to produce 4163 the next BS octets of ciphertext. These are loaded into FR and 4164 the process is repeated until the plaintext is used up. 4165 416613.10. Private or Experimental Parameters 4167 4168 S2K specifiers, Signature subpacket types, user attribute types, 4169 image format types, and algorithms described in Section 9 all 4170 reserve the range 100 to 110 for private and experimental use. 4171 Packet types reserve the range 60 to 63 for private and experimental 4172 use. These are intentionally managed with the PRIVATE USE method, as 4173 described in [RFC2434]. 4174 4175 However, implementations need to be careful with these and promote 4176 them to full IANA-managed parameters when they grow beyond the 4177 original, limited system. 4178 417913.11. Extension of the MDC System 4180 4181 As described in the non-normative explanation in section 5.13, the 4182 MDC system is uniquely unparameterized in OpenPGP, and that this was 4183 an intentional decision to avoid cross-grade attacks. If the MDC 4184 system is extended to a stronger hash function, there must be care 4185 given to avoiding downgrade and cross-grade attacks. 4186 4187 One simple way to do this is to create new packets for a new MDC. 4188 For example, instead of the MDC system using packets 18 and 19, a 4189 new MDC could use 20 and 21. This has obvious drawbacks (it uses two 4190 packet numbers for each new hash function in a space that is limited 4191 to a maximum of 60). 4192 4193 Another simple way to extend the MDC system is to create new 4194 versions of packet 18, and reflect this in packet 19. For example, 4195 suppose that V2 of packet 18 implicitly used SHA-256. This would 4196 require packet 19 to have a length of 32 octets. The change in the 4197 version in packet 18 and the size of packet 19 prevent a downgrade 4198 attack. 4199 4200Callas, et al. Expires Oct 24, 2007 [Page 75] 4201 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 4202 4203 There are two drawbacks to this latter approach. The first is that 4204 using the version number of a packet to carry algorithm information 4205 is not tidy from a protocol-design standpoint. it is possible that 4206 there might be several versions of the MDC system in common use, but 4207 this untidiness would reflect untidiness in cryptographic consensus 4208 about hash function security. The second is that different versions 4209 of packet 19 would have to have unique sizes. If there were two 4210 versions each with 256-bit hashes, they could not both have 32-octet 4211 packet 19s without admitting the chance of a cross-grade attack. 4212 4213 Yet another, complex approach to extend the MDC system would be a 4214 hybrid of the two above -- create a new pair of MDC packets that are 4215 fully parameterized, and yet protected from downgrade and 4216 cross-grade. 4217 4218 Any change to the MDC system MUST be done through the IETF CONSENSUS 4219 method, as described in [RFC2434]. 4220 422113.12. Meta-Considerations for Expansion 4222 4223 If OpenPGP is extended in a way that is not backwards-compatible, 4224 meaning that old implementations will not gracefully handle their 4225 absence of a new feature, the extension proposal can be declared in 4226 the key holder's self-signature as part of the Features signature 4227 subpacket. 4228 4229 We cannot state definitively what extensions will not be 4230 upwards-compatible, but typically new algorithms are 4231 upwards-compatible, but new packets are not. 4232 4233 If an extension proposal does not update the Features system, it 4234 SHOULD include an explanation of why this is unnecessary. If the 4235 proposal contains neither an extension to the Features system nor an 4236 explanation of why such an extension is unnecessary, the proposal 4237 SHOULD be rejected. 4238 423914. Security Considerations 4240 4241 * As with any technology involving cryptography, you should check 4242 the current literature to determine if any algorithms used here 4243 have been found to be vulnerable to attack. 4244 4245 * This specification uses Public Key Cryptography technologies. It 4246 is assumed that the private key portion of a public-private key 4247 pair is controlled and secured by the proper party or parties. 4248 4249 * Certain operations in this specification involve the use of 4250 random numbers. An appropriate entropy source should be used to 4251 generate these numbers. See RFC 4086. 4252 4253 4254 4255 4256Callas, et al. Expires Oct 24, 2007 [Page 76] 4257 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 4258 4259 * The MD5 hash algorithm has been found to have weaknesses, with 4260 collisions found in a number of cases. MD5 is deprecated for use 4261 in OpenPGP. Implementations MUST NOT generate new signatures 4262 using MD5 as a hash function. They MAY continue to consider old 4263 signatures that used MD5 as valid. 4264 4265 * SHA-224 and SHA-384 require the same work as SHA-256 and SHA-512 4266 respectively. In general, there are few reasons to use them 4267 outside of DSS compatibility. You need a situation where one 4268 needs more security than smaller hashes, but does not want to 4269 have the full 256-bit or 512-bit data length. 4270 4271 * Many security protocol designers think that it is a bad idea to 4272 use a single key for both privacy (encryption) and integrity 4273 (signatures). In fact, this was one of the motivating forces 4274 behind the V4 key format with separate signature and encryption 4275 keys. If you as an implementer promote dual-use keys, you should 4276 at least be aware of this controversy. 4277 4278 * The DSA algorithm will work with any hash, but is sensitive to 4279 the quality of the hash algorithm. Verifiers should be aware 4280 that even if the signer used a strong hash, an attacker could 4281 have modified the signature to use a weak one. Only signatures 4282 using acceptably strong hash algorithms should be accepted as 4283 valid. 4284 4285 * As OpenPGP combines many different asymmetric, symmetric, and 4286 hash algorithms, each with different measures of strength, care 4287 should be taken that the weakest element of an OpenPGP message 4288 is still sufficiently strong for the purpose at hand. While 4289 consensus about the the strength of a given algorithm may 4290 evolve, NIST Special Publication 800-57 [SP800-57] recommends 4291 the following list of equivalent strengths: 4292 4293 Asymmetric | Hash | Symmetric 4294 key size | size | key size 4295 ------------+--------+----------- 4296 1024 160 80 4297 2048 224 112 4298 3072 256 128 4299 7680 384 192 4300 15360 512 256 4301 4302 4303 * There is a somewhat-related potential security problem in 4304 signatures. If an attacker can find a message that hashes to the 4305 same hash with a different algorithm, a bogus signature 4306 structure can be constructed that evaluates correctly. 4307 4308 For example, suppose Alice DSA signs message M using hash 4309 algorithm H. Suppose that Mallet finds a message M' that has the 4310 same hash value as M with H'. Mallet can then construct a 4311 4312Callas, et al. Expires Oct 24, 2007 [Page 77] 4313 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 4314 4315 signature block that verifies as Alice's signature of M' with 4316 H'. However, this would also constitute a weakness in either H 4317 or H' or both. Should this ever occur, a revision will have to 4318 be made to this document to revise the allowed hash algorithms. 4319 4320 * If you are building an authentication system, the recipient may 4321 specify a preferred signing algorithm. However, the signer would 4322 be foolish to use a weak algorithm simply because the recipient 4323 requests it. 4324 4325 * Some of the encryption algorithms mentioned in this document 4326 have been analyzed less than others. For example, although CAST5 4327 is presently considered strong, it has been analyzed less than 4328 TripleDES. Other algorithms may have other controversies 4329 surrounding them. 4330 4331 * In late summer 2002, Jallad, Katz, and Schneier published an 4332 interesting attack on the OpenPGP protocol and some of its 4333 implementations [JKS02]. In this attack, the attacker modifies a 4334 message and sends it to a user who then returns the erroneously 4335 decrypted message to the attacker. The attacker is thus using 4336 the user as a random oracle, and can often decrypt the message. 4337 4338 Compressing data can ameliorate this attack. The incorrectly 4339 decrypted data nearly always decompresses in ways that defeats 4340 the attack. However, this is not a rigorous fix, and leaves open 4341 some small vulnerabilities. For example, if an implementation 4342 does not compress a message before encryption (perhaps because 4343 it knows it was already compressed), then that message is 4344 vulnerable. Because of this happenstance -- that modification 4345 attacks can be thwarted by decompression errors, an 4346 implementation SHOULD treat a decompression error as a security 4347 problem, not merely a data problem. 4348 4349 This attack can be defeated by the use of Modification 4350 Detection, provided that the implementation does not let the 4351 user naively return the data to the attacker. An implementation 4352 MUST treat an MDC failure as a security problem, not merely a 4353 data problem. 4354 4355 In either case, the implementation MAY allow the user access to 4356 the erroneous data, but MUST warn the user as to potential 4357 security problems should that data be returned to the sender. 4358 4359 While this attack is somewhat obscure, requiring a special set 4360 of circumstances to create it, it is nonetheless quite serious 4361 as it permits someone to trick a user to decrypt a message. 4362 Consequently, it is important that: 4363 4364 1. Implementers treat MDC errors and decompression failures as 4365 security problems. 4366 4367 4368Callas, et al. Expires Oct 24, 2007 [Page 78] 4369 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 4370 4371 2. Implementers implement Modification Detection with all due 4372 speed and encourage its spread. 4373 4374 3. Users migrate to implementations that support Modification 4375 Detection with all due speed. 4376 4377 * PKCS#1 has been found to be vulnerable to attacks in which a 4378 system that reports errors in padding differently from errors in 4379 decryption becomes a random oracle that can leak the private key 4380 in mere millions of queries. Implementations must be aware of 4381 this attack and prevent it from happening. The simplest solution 4382 is report a single error code for all variants of decryption 4383 errors so as not to leak information to an attacker. 4384 4385 * Some technologies mentioned here may be subject to government 4386 control in some countries. 4387 4388 * In winter 2005, Serge Mister and Robert Zuccherato from Entrust 4389 released a paper describing a way that the "quick check" in 4390 OpenPGP CFB mode can be used with a random oracle to decrypt two 4391 octets of every cipher block [MZ05]. They recommend as 4392 prevention not using the quick check at all. 4393 4394 Many implementers have taken this advice to heart for any data 4395 that is symmetrically encrypted and for which the session key is 4396 public-key encrypted. In this case, the quick check is not 4397 needed as the public key encryption of the session key should 4398 guarantee that it is the right session key. In other cases, the 4399 implementation should use the quick check with care. 4400 4401 On the one hand, there is a danger to using it if there is a 4402 random oracle that can leak information to an attacker. In 4403 plainer language, there is a danger to using the quick check if 4404 timing information about the check can be exposed to an 4405 attacker, particularly via an automated service that allows 4406 rapidly repeated queries. 4407 4408 On the other hand, it is inconvenient to the user to be informed 4409 that they typed in the wrong passphrase only after a petabyte of 4410 data is decrypted. There are many cases in cryptographic 4411 engineering where the implementer must use care and wisdom, and 4412 this is one. 4413 441415. Implementation Nits 4415 4416 This section is a collection of comments to help an implementer, 4417 particularly with an eye to backward compatibility. Previous 4418 implementations of PGP are not OpenPGP-compliant. Often the 4419 differences are small, but small differences are frequently more 4420 vexing than large differences. Thus, this is a non-comprehensive 4421 list of potential problems and gotchas for a developer who is trying 4422 to be backward-compatible. 4423 4424Callas, et al. Expires Oct 24, 2007 [Page 79] 4425 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 4426 4427 * The IDEA algorithm is patented, and yet it is required for PGP 4428 2.x interoperability. It is also the de-facto preferred 4429 algorithm for a V3 key with a V3 self-signature (or no 4430 self-signature). 4431 4432 * When exporting a private key, PGP 2.x generates the header 4433 "BEGIN PGP SECRET KEY BLOCK" instead of "BEGIN PGP PRIVATE KEY 4434 BLOCK". All previous versions ignore the implied data type, and 4435 look directly at the packet data type. 4436 4437 * PGP 2.0 through 2.5 generated V2 Public Key Packets. These are 4438 identical to the deprecated V3 keys except for the version 4439 number. An implementation MUST NOT generate them and may accept 4440 or reject them as it sees fit. Some older PGP versions generated 4441 V2 PKESK packets (Tag 1) as well. An implementation may accept 4442 or reject V2 PKESK packets as it sees fit, and MUST NOT generate 4443 them. 4444 4445 * PGP 2.6.x will not accept key-material packets with versions 4446 greater than 3. 4447 4448 * There are many ways possible for two keys to have the same key 4449 material, but different fingerprints (and thus key IDs). Perhaps 4450 the most interesting is an RSA key that has been "upgraded" to 4451 V4 format, but since a V4 fingerprint is constructed by hashing 4452 the key creation time along with other things, two V4 keys 4453 created at different times, yet with the same key material will 4454 have different fingerprints. 4455 4456 * If an implementation is using zlib to interoperate with PGP 2.x, 4457 then the "windowBits" parameter should be set to -13. 4458 4459 * The 0x19 back signatures were not required for signing subkeys 4460 until relatively recently. Consquently, there may be keys in the 4461 wild that do not have these back signatures. Implementing 4462 software may handle these keys as it sees fit. 4463 446416. Authors' Addresses 4465 4466 The working group can be contacted via the current chair: 4467 4468 Derek Atkins 4469 IHTFP Consulting, Inc. 4470 6 Farragut Ave 4471 Somerville, MA 02144 USA 4472 Email: derek@ihtfp.com 4473 Tel: +1 617 623 3745 4474 4475 The principal authors of this draft are: 4476 4477 4478 4479 4480Callas, et al. Expires Oct 24, 2007 [Page 80] 4481 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 4482 4483 Jon Callas 4484 Email: jon@callas.org 4485 4486 Lutz Donnerhacke 4487 IKS GmbH 4488 Wildenbruchstr. 15 4489 07745 Jena, Germany 4490 4491 EMail: lutz@iks-jena.de 4492 4493 Hal Finney 4494 Email: hal@finney.org 4495 4496 David Shaw 4497 Email: dshaw@jabberwocky.com 4498 4499 Rodney Thayer 4500 Email: rodney@canola-jones.com 4501 4502 This memo also draws on much previous work from a number of other 4503 authors who include: Derek Atkins, Charles Breed, Dave Del Torto, 4504 Marc Dyksterhouse, Gail Haspert, Gene Hoffman, Paul Hoffman, Ben 4505 Laurie, Raph Levien, Colin Plumb, Will Price, David Shaw, William 4506 Stallings, Mark Weaver, and Philip R. Zimmermann. 4507 450817. References (Normative) 4509 4510 4511 [AES] NIST, FIPS PUB 197, "Advanced Encryption Standard 4512 (AES)," November 2001. 4513 4514http://csrc.nist.gov/publications/fips/fips197/ 4515 fips-197.{ps,pdf} 4516 4517 [BLOWFISH] Schneier, B. "Description of a New Variable-Length 4518 Key, 64-Bit Block Cipher (Blowfish)" Fast Software 4519 Encryption, Cambridge Security Workshop Proceedings 4520 (December 1993), Springer-Verlag, 1994, pp191-204 4521 <http://www.counterpane.com/bfsverlag.html> 4522 4523 [BZ2] J. Seward, jseward@acm.org, "The Bzip2 and libbzip2 4524 home page" <http://www.bzip.org/> 4525 4526 [ELGAMAL] T. Elgamal, "A Public-Key Cryptosystem and a 4527 Signature Scheme Based on Discrete Logarithms," 4528 IEEE Transactions on Information Theory, v. IT-31, 4529 n. 4, 1985, pp. 469-472. 4530 4531 [FIPS180] Secure Hash Signature Standard (SHS) (FIPS PUB 4532 180-2). 4533 <http://csrc.nist.gov/publications/fips/ 4534 fips180-2/fips180-2withchangenotice.pdf> 4535 4536Callas, et al. Expires Oct 24, 2007 [Page 81] 4537 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 4538 4539 [FIPS186] Digital Signature Standard (DSS) (FIPS PUB 186-2). 4540 <http://csrc.nist.gov/publications/fips/fips186-2/ 4541 fips186-2-change1.pdf> 4542 FIPS 186-3 describes keys greater than 1024 bits. 4543 The latest draft is at: 4544 <http://csrc.nist.gov/publications/drafts/ 4545 fips_186-3/Draft-FIPS-186-3%20_March2006.pdf> 4546 4547 [HAC] Alfred Menezes, Paul van Oorschot, and Scott 4548 Vanstone, "Handbook of Applied Cryptography," CRC 4549 Press, 1996. 4550 <http://www.cacr.math.uwaterloo.ca/hac/> 4551 4552 [IDEA] Lai, X, "On the design and security of block 4553 ciphers", ETH Series in Information Processing, 4554 J.L. Massey (editor), Vol. 1, Hartung-Gorre Verlag 4555 Knostanz, Technische Hochschule (Zurich), 1992 4556 4557 [ISO10646] ISO/IEC 10646-1:1993. International Standard -- 4558 Information technology -- Universal Multiple-Octet 4559 Coded Character Set (UCS) -- Part 1: Architecture 4560 and Basic Multilingual Plane. 4561 4562 [JFIF] JPEG File Interchange Format (Version 1.02). 4563 Eric Hamilton, C-Cube Microsystems, Milpitas, CA, 4564 September 1, 1992. 4565 4566 [RFC1991] Atkins, D., Stallings, W. and P. Zimmermann, "PGP 4567 Message Exchange Formats", RFC 1991, August 1996. 4568 4569 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4570 Requirement Level", BCP 14, RFC 2119, March 1997. 4571 [RFC2045] Borenstein, N. and N. Freed, "Multipurpose Internet 4572 Mail Extensions (MIME) Part One: Format of Internet 4573 Message Bodies.", RFC 2045, November 1996. 4574 4575 [RFC2144] Adams, C., "The CAST-128 Encryption Algorithm", RFC 4576 2144, May 1997. 4577 4578 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for 4579 Writing an IANA Considerations Section in RFCs", 4580 BCP 26, RFC 2434, October 1998. 4581 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822. 4582 4583 [RFC3156] M. Elkins, D. Del Torto, R. Levien, T. Roessler, 4584 "MIME Security with OpenPGP", RFC 3156, 4585 August 2001. 4586 4587 [RFC3447] B. Kaliski and J. Staddon, "PKCS #1: RSA 4588 Cryptography Specifications Version 2.1", 4589 RFC 3447, February 2003. 4590 4591 4592Callas, et al. Expires Oct 24, 2007 [Page 82] 4593 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 4594 4595 [RFC3629] Yergeau., F., "UTF-8, a transformation format of 4596 Unicode and ISO 10646", RFC 3629, November 2003. 4597 4598 [RFC4086] Eastlake, D., Crocker, S. and J. Schiller, 4599 "Randomness Recommendations for Security", RFC 4600 4086, June 2005. 4601 4602 [SCHNEIER] Schneier, B., "Applied Cryptography Second Edition: 4603 protocols, algorithms, and source code in C", 1996. 4604 4605 [TWOFISH] B. Schneier, J. Kelsey, D. Whiting, D. Wagner, C. 4606 Hall, and N. Ferguson, "The Twofish Encryption 4607 Algorithm", John Wiley & Sons, 1999. 4608 4609 461018. References (Informative) 4611 4612 4613 [BLEICHENBACHER] Bleichenbacher, Daniel, "Generating Elgamal 4614 signatures without knowing the secret key," 4615 Eurocrypt 96. Note that the version in the 4616 proceedings has an error. A revised version is 4617 available at the time of writing from 4618 <ftp://ftp.inf.ethz.ch/pub/publications/papers/ti 4619 /isc/ElGamal.ps> 4620 4621 [JKS02] Kahil Jallad, Jonathan Katz, Bruce Schneier 4622 "Implementation of Chosen-Ciphertext Attacks 4623 against PGP and GnuPG" 4624 http://www.counterpane.com/pgp-attack.html 4625 4626 [MAURER] Ueli Maurer, "Modelling a Public-Key 4627 Infrastructure", Proc. 1996 European Symposium on 4628 Research in Computer Security (ESORICS' 96), 4629 Lecture Notes in Computer Science, Springer-Verlag, 4630 vol. 1146, pp. 325-350, Sep 1996. 4631 4632 [MZ05] Serge Mister, Robert Zuccherato, "An Attack on 4633 CFB Mode Encryption As Used By OpenPGP," IACR 4634 ePrint Archive: Report 2005/033, 8 Feb 2005 4635 http://eprint.iacr.org/2005/033 4636 4637 [RFC1423] Balenson, D., "Privacy Enhancement for Internet 4638 Electronic Mail: Part III: Algorithms, Modes, and 4639 Identifiers", RFC 1423, October 1993. 4640 4641 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format 4642 Specification version 1.3.", RFC 1951, May 1996. 4643 4644 [RFC2440] Callas, J., Donnerhacke, L., Finney, H., and 4645 Thayer, R. "OpenPGP Message Format", RFC 2440, 4646 November, 1998. 4647 4648Callas, et al. Expires Oct 24, 2007 [Page 83] 4649 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 4650 4651 [SP800-57] NIST Special Publication 800-57, Recommendation on 4652 Key Management 4653 <http://csrc.nist.gov/publications/nistpubs/ 4654 800-57/SP800-57-Part1.pdf> 4655 <http://csrc.nist.gov/publications/nistpubs/ 4656 800-57/SP800-57-Part2.pdf> 4657 4658 465919. Full Copyright Statement 4660 4661 Copyright (C) 2007 by The IETF Trust. 4662 4663 This document is subject to the rights, licenses and restrictions 4664 contained in BCP 78, and except as set forth therein, the authors 4665 retain all their rights. 4666 4667 This document and the information contained herein are provided on 4668 an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE 4669 REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE 4670 IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL 4671 WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY 4672 WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE 4673 ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS 4674 FOR A PARTICULAR PURPOSE. 4675 4676 This document and translations of it may be copied and furnished to 4677 others, and derivative works that comment on or otherwise explain it 4678 or assist in its implementation may be prepared, copied, published 4679 and distributed, in whole or in part, without restriction of any 4680 kind, provided that the above copyright notice and this paragraph 4681 are included on all such copies and derivative works. However, this 4682 document itself may not be modified in any way, such as by removing 4683 the copyright notice or references to the Internet Society or other 4684 Internet organizations, except as needed for the purpose of 4685 developing Internet standards in which case the procedures for 4686 copyrights defined in the Internet Standards process must be 4687 followed, or as required to translate it into languages other than 4688 English. 4689 4690 The limited permissions granted above are perpetual and will not be 4691 revoked by the Internet Society or its successors or assigns. 4692 469320. Intellectual Property 4694 4695 The IETF takes no position regarding the validity or scope of any 4696 Intellectual Property Rights or other rights that might be claimed 4697 to pertain to the implementation or use of the technology described 4698 in this document or the extent to which any license under such 4699 rights might or might not be available; nor does it represent that 4700 it has made any independent effort to identify any such rights. 4701 Information on the procedures with respect to rights in RFC 4702 documents can be found in BCP 78 and BCP 79. 4703 4704Callas, et al. Expires Oct 24, 2007 [Page 84] 4705 INTERNET-DRAFT OpenPGP Message Format Apr 24, 2007 4706 4707 Copies of IPR disclosures made to the IETF Secretariat and any 4708 assurances of licenses to be made available, or the result of an 4709 attempt made to obtain a general license or permission for the use 4710 of such proprietary rights by implementers or users of this 4711 specification can be obtained from the IETF on-line IPR repository 4712 at http://www.ietf.org/ipr. 4713 4714 The IETF invites any interested party to bring to its attention any 4715 copyrights, patents or patent applications, or other proprietary 4716 rights that may cover technology that may be required to implement 4717 this standard. Please address the information to the IETF at 4718 ietf-ipr@ietf.org. 4719 4720 4721 4722 4723 4724 4725 4726 4727 4728 4729 4730 4731 4732 4733 4734 4735 4736 4737 4738 4739 4740 4741 4742 4743 4744 4745 4746 4747 4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759 4760Callas, et al. Expires Oct 24, 2007 [Page 85] 4761 4762 4763