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