![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to pgformat.doc CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [PGP] / pgp / doc|
Return to pgformat.doc CVS log | Up to [PGP] / pgp / doc |
1.1.1.5 ! root 1: File Formats Used by PGP 2.x ! 2: ============================ ! 3: ! 4: ***Note: Packets generated with PGP 2.6.3i normally contain a version ! 5: byte of 3. However, by using the +legal_kludge=off option, you ! 6: can force PGP to use a version byte of 2 instead. This will ! 7: make all messages and keys generated with PGP 2.6.3i compatible ! 8: with any PGP 2.x version. ! 9: ! 10: This appendix describes the file formats used externally by Pretty ! 11: Good Privacy (PGP), the RSA public key cryptography application. The ! 12: intended audience includes software engineers trying to port PGP to ! 13: other hardware environments or trying to implement other PGP- ! 14: compatible cryptography products, or anyone else who is curious. ! 15: ! 16: [To be included: a description of ASCII armor. An ASCII armored ! 17: file is just like a binary file described here, but with an extra ! 18: layer of encoding added, framing lines, and a 24-bit CRC at the end.] ! 19: ! 20: ! 21: Byte Order ! 22: ---------- ! 23: ! 24: All integer data used by PGP is externally stored most significant byte ! 25: (MSB) first, regardless of the byte order used internally by the host ! 26: CPU architecture. This is for portability of messages and keys between ! 27: hosts. This covers multiprecision RSA integers, bit count prefix ! 28: fields, byte count prefix fields, checksums, key IDs, and timestamps. ! 29: ! 30: The MSB-first byte order for external packet representation was ! 31: chosen only because many other crypto standards use it. ! 32: ! 33: ! 34: Multiprecision Integers ! 35: ----------------------- ! 36: ! 37: RSA arithmetic involves a lot of multiprecision integers, often ! 38: having hundreds of bits of precision. PGP externally stores a ! 39: multiprecision integer (MPI) with a 16-bit prefix that gives the ! 40: number of significant bits in the integer that follows. The integer ! 41: that follows this bitcount field is stored in the usual byte order, ! 42: with the MSB padded with zero bits if the bitcount is not a multiple ! 43: of 8. The bitcount always specifies the exact number of significant ! 44: bits. For example, the integer value 5 would be stored as these ! 45: three bytes: ! 46: ! 47: 00 03 05 ! 48: ! 49: An MPI with a value of zero is simply stored with the 16-bit bitcount ! 50: prefix field containing a 0, with no value bytes following it. ! 51: ! 52: ! 53: ! 54: Key ID ! 55: ------ ! 56: ! 57: Some packets use a "key ID" field. The key ID is the least ! 58: significant 64 bits of the RSA public modulus that was involved in ! 59: creating the packet. For all practical purposes it unique to each ! 60: RSA public key. ! 61: ! 62: ! 63: User ID ! 64: ------- ! 65: ! 66: Some packets contain a "user ID", which is an ASCII string that ! 67: contains the user's name. Unlike a C string, the user ID has a ! 68: length byte at the beginning that has a byte count of the rest of the ! 69: string. This length byte does not include itself in the count. ! 70: ! 71: ! 72: Timestamp ! 73: --------- ! 74: ! 75: Some packets contain a timestamp, which is a 32-bit unsigned integer ! 76: of the number of seconds elapsed since 1970 Jan 1 00:00:00 GMT. This ! 77: is the standard format used by Unix timestamps. It spans 136 years. ! 78: ! 79: ! 80: ! 81: Cipher Type Byte (CTB) ! 82: ---------------------- ! 83: ! 84: Many of these data structures begin with a Cipher Type Byte (CTB), ! 85: which specifies the type of data structure that follows it. The CTB ! 86: bit fields have the following meaning (bit 0 is the LSB, bit 7 is the ! 87: MSB): ! 88: ! 89: Bit 7: Always 1, which designates this as a CTB ! 90: Bit 6: Reserved. ! 91: Bits 5-2: CTB type field, specifies type of packet that follows ! 92: 0001 - public-key-encrypted packet ! 93: 0010 - secret-key-encrypted (signature) packet ! 94: 0101 - Secret key certificate ! 95: 0110 - Public key certificate ! 96: 1000 - Compressed data packet ! 97: 1001 - Conventional-Key-Encrypted data ! 98: 1011 - Raw literal plaintext data, with filename and mode ! 99: 1100 - Keyring trust packet ! 100: 1101 - User ID packet, associated with public or secret key ! 101: 1110 - Comment packet ! 102: Other CTB packet types are unimplemented. ! 103: Bits 1-0: Length-of-length field: ! 104: 00 - 1 byte packet length field follows CTB ! 105: 01 - 2 byte packet length field follows CTB ! 106: 10 - 4 byte packet length field follows CTB ! 107: 11 - no length field follows CTB, unknown packet length. ! 108: The 8-, 16-, or 32-bit packet length field after the CTB ! 109: gives the length in bytes of the rest of the packet, not ! 110: counting the CTB and the packet length field. ! 111: ! 112: ! 113: ! 114: RSA public-key-encrypted packet ! 115: ------------------------------- ! 116: ! 117: Offset Length Meaning ! 118: 0 1 CTB for RSA public-key-encrypted packet ! 119: 1 2 16-bit (or maybe 8-bit) length of packet ! 120: 3 1 Version byte, may affect rest of fields that follow. ! 121: (=2) for PGP versions <= 2.5 ! 122: (=3) for PGP versions >= 2.6 ! 123: 4 8 64-bit Key ID ! 124: 12 1 Algorithm byte for RSA (=1 for RSA). ! 125: --Algorithm byte affects field definitions that follow. ! 126: 13 ? RSA-encrypted integer, encrypted conventional key ! 127: packet. (MPI with bitcount prefix) ! 128: ! 129: The conventionally-encrypted ciphertext packet begins right after the ! 130: RSA public-key-encrypted packet that contains the conventional key. ! 131: ! 132: ! 133: ! 134: Signature packet ! 135: ---------------- ! 136: ! 137: Offset Length Meaning ! 138: 0 1 CTB for secret-key-encrypted (signed) packet ! 139: 1 2 16-bit (or maybe 8-bit) length of packet ! 140: 3 1 Version byte, may affect rest of fields that follow. ! 141: (=2) for PGP versions <= 2.5 ! 142: (=3) for PGP versions >= 2.6 ! 143: 4 1 Length of following material that is implicitly included ! 144: in MD calculation (=5). ! 145: 5 1 Signature classification field (see below). ! 146: Implicitly append this to message for MD calculation. ! 147: 6 4 32-bit timestamp of when signature was made. ! 148: Implicitly append this to message for MD calculation. ! 149: 10 8 64-bit Key ID ! 150: 18 1 Algorithm byte for public key scheme (RSA=0x01). ! 151: --Algorithm byte affects field definitions that follow. ! 152: 19 1 Algorithm byte for message digest (MD5=0x01). ! 153: 20 2 First 2 bytes of the Message Digest inside the ! 154: RSA-encrypted integer, to help us figure out if we ! 155: used the right RSA key to check the signature. ! 156: 22 ? RSA-encrypted integer, encrypted message digest ! 157: (MPI with bitcount prefix). ! 158: ! 159: If the plaintext that was signed is included in the same file as the ! 160: signature packet, it begins right after the RSA secret-key-signed ! 161: packet that contains the message digest. The plaintext has a ! 162: "literal" CTB prefix. ! 163: ! 164: The original idea had a variable length field following the length ! 165: of following material byte, before the Key ID. In particular, the ! 166: possibility of a 2-byte validity period was defined, although no ! 167: previous version of PGP ever generated those bytes. ! 168: ! 169: Owing to the way the MD5 is computed for the signature, if that field ! 170: is variable length, it is possible to generate two different messages ! 171: with the same MD5 hash. One would be a file of length N, with a 7-byte ! 172: following section consisting of a signature type byte, 4 bytes of ! 173: timestamp, and 2 of validity period, while the other would be a file of ! 174: length N+2, whose last two bytes would be the siganture type byte and ! 175: the first byte of timestamp, and the last three bytes of timestamp and ! 176: the validity period would instead be interpreted as a signature type ! 177: byte and a timestmap. ! 178: ! 179: It should be emphasized that the messages are barely different and ! 180: special circumstances must arise for this to be possible, so it is ! 181: extremely unlilely that this would be exploitable, but it is a ! 182: potential weakness. It has been plugged by allowing only the currently ! 183: implemented 5-byte option. Validity periods will be added later with ! 184: a different format. ! 185: ! 186: The signature classification field describes what kind of ! 187: signature certificate this is. There are various hex values: ! 188: 00 - Signature of a message or document, binary image. ! 189: 01 - Signature of a message or document, canonical text. ! 190: 10 - Key certification, generic. Only version of key ! 191: certification supported by PGP 2.5. ! 192: Material signed is public key pkt and User ID pkt. ! 193: 11 - Key certification, persona. No attempt made at all ! 194: to identify the user with a real name. ! 195: Material signed is public key pkt and User ID pkt. ! 196: 12 - Key certification, casual identification. Some ! 197: casual attempt made to identify user with his name. ! 198: Material signed is public key pkt and User ID pkt. ! 199: 13 - Key certification, positive ID. Heavy-duty ! 200: identification efforts, photo ID, direct contact ! 201: with personal friend, etc. ! 202: Material signed is public key pkt and User ID pkt. ! 203: 20 - Key compromise. User signs his own compromise ! 204: certificate. Independent of user ID associations. ! 205: Material signed is public key pkt ONLY. ! 206: 30 - Key/userid revocation. User can sign his own ! 207: revocation to dissolve an association between a key ! 208: and a user ID, or certifier may revoke his previous ! 209: certification of this key/userid pair. ! 210: Material signed is public key pkt and User ID pkt. ! 211: 40 - Timestamping a signature certificate made by someone ! 212: else. Can be used to apply trusted timestamp, and ! 213: log it in notary's log. Signature of a signature. ! 214: (Planned, not implemented.) ! 215: ! 216: When a signature is made to certify a key/UserID pair, it is computed ! 217: across two packets-- the public key packet, and the separate User ID ! 218: packet. See below. ! 219: ! 220: The packet headers (CTB and length fields) for the public key packet ! 221: and the user ID packet are both omitted from the signature ! 222: calculation for a key certification. ! 223: ! 224: A key compromise certificate may be issued by someone to revoke his ! 225: own key when his secret key is known to be compromised. If that ! 226: happens, a user would sign his own key compromise certificate with ! 227: the very key that is being revoked. A key revoked by its own ! 228: signature means that this key should never be used or trusted again, ! 229: in any form, associated with any user ID. A key compromise ! 230: certificate issued by the keyholder shall take precedence over any ! 231: other key certifications made by anyone else for that key. A key ! 232: compromise signed by someone other than the key holder is invalid. ! 233: ! 234: Note that a key compromise certificate just includes the key packet ! 235: in its signature calculation, because it kills the whole key without ! 236: regard to any userid associations. It isn't tied to any particular ! 237: userid association. It should be inserted after the key packet, ! 238: before the first userid packet. ! 239: ! 240: When a key compromise certificate is submitted to PGP, PGP will place ! 241: it on the public keyring. A key compromise certificate is always ! 242: accompanied in its travels by the public key and userIDs it affects. ! 243: If the affected key is NOT already on the keyring, the compromise ! 244: certificate (and its key and user ID) is merely added to the keyring ! 245: anywhere. If the affected key IS already on the keyring, the ! 246: compromise certificate is inserted after the affected key packet. ! 247: This assumes that the actual key packet is identical to the one ! 248: already on the key ring, so no duplicate key packet is needed. ! 249: If a key has been revoked, PGP will not allow its use to encipher any ! 250: messages, and if an incoming signature uses it, PGP will display a ! 251: stern warning that this key has been revoked. ! 252: ! 253: NOTE: Key/userid revocation certificates ARE NOT SUPPORTED in ! 254: this version of PGP. But if we ever get around to supporting them, ! 255: here are some ideas on how they should work... ! 256: ! 257: A key/userid revocation certificate may be issued by someone to ! 258: dissolve the association between his own key and a user ID. He would ! 259: sign it with the very key that is being revoked. A key/userid ! 260: revocation certificate issued by the keyholder shall take precedence ! 261: over any other key certifications made by anyone else for that ! 262: key/userid pair. Also, a third party certifier may revoke his own ! 263: previous certification of this key/userid pair by issuing a ! 264: key/userid revocation certificate. Such a revocation should not ! 265: affect the certifications by other third parties for this same ! 266: key/userid pair. ! 267: ! 268: When a key/userid revocation certificate is submitted to PGP, PGP ! 269: will place it on the public keyring. A key/userid revocation ! 270: certificate is always accompanied in its travels by the public key it ! 271: affects (the key packet and user ID packet precedes the revocation ! 272: certificate). If the affected key is NOT already on the keyring, the ! 273: revocation certificate (and its key and user ID) is merely added to ! 274: the keyring anywhere. If the affected key IS already on the keyring, ! 275: the revocation certificate is integrated in with the key's other ! 276: certificates as though it were just another key certification. This ! 277: assumes that the actual key packet is identical to the one already on ! 278: the key ring, so no duplicate key packet is needed. ! 279: ! 280: ! 281: ! 282: Message digest "packet" ! 283: ----------------------- ! 284: ! 285: The Message digest has no CTB packet framing. It is stored ! 286: packetless and naked, with padding, encrypted inside the MPI in the ! 287: Signature packet. ! 288: ! 289: PGP versions 2.3 and later use a new format for encoding the message ! 290: digest into the MPI in the signature packet, a format which is ! 291: compatible with RFC1425 (formerly RFC1115). This format is accepted ! 292: but not written by version 2.2. The older format used by versions 2.2 ! 293: is acepted by versions up to 2.4, but the RSAREF code in 2.5 is ! 294: not capable of parsing it. ! 295: ! 296: PGP versions 2.2 and earlier encode the MD into the MPI as follows: ! 297: ! 298: MSB . . . LSB ! 299: ! 300: 0 1 MD(16 bytes) 0 FF(n bytes) 1 ! 301: ! 302: Enough bytes of FF padding are added to make the length of this ! 303: whole string equal to the number of bytes in the modulus. ! 304: ! 305: PGP versions 2.3 and later encode the MD into the MPI as follows: ! 306: ! 307: MSB . . . LSB ! 308: ! 309: 0 1 FF(n bytes) 0 ASN(18 bytes) MD(16 bytes) ! 310: ! 311: See RFC1423 for an explanation of the meaning of the ASN string. ! 312: It is the following 18 byte long hex value: ! 313: ! 314: 3020300c06082a864886f70d020505000410 ! 315: ! 316: Enough bytes of FF padding are added to make the length of this ! 317: whole string equal to the number of bytes in the modulus. ! 318: ! 319: All this mainly affects the rsa_private_encrypt() and rsa_public_decrypt() ! 320: functions in rsaglue.c. ! 321: ! 322: There is no checksum included. The padding serves to verify that the ! 323: correct RSA key was used. ! 324: ! 325: ! 326: Conventional Data Encryption Key (DEK) "packet" ! 327: ----------------------------------------------- ! 328: ! 329: The DEK has no CTB packet framing. The DEK is stored packetless and ! 330: naked, with padding, encrypted inside the MPI in the RSA ! 331: public-key-encrypted packet. ! 332: ! 333: PGP versions 2.3 and later use a new format for encoding the message ! 334: digest into the MPI in the signature packet. (This format is not ! 335: presently based on any RFCs due to the use of the IDEA encryption ! 336: system.) This format is accepted but not written by version 2.2. The ! 337: older format used by versions 2.2 and earlier is also accepted by ! 338: versions up to 2.4, but the RSAREF code in 2.5 is unable to cope ! 339: with it. ! 340: ! 341: PGP versions 2.2 and earlier encode the DEK into the MPI as follows: ! 342: ! 343: MSB . . . LSB ! 344: ! 345: 0 1 DEK(16 bytes) CSUM(2 bytes) 0 RND(n bytes) 2 ! 346: ! 347: CSUM refers to a 16-bit checksum appended to the high end of the DEK. ! 348: RND is a string of NONZERO pseudorandom bytes, enough to make the length ! 349: of this whole string equal to the number of bytes in the modulus. ! 350: ! 351: PGP versions 2.3 and later encode the DEK into the MPI as follows: ! 352: ! 353: MSB . . . LSB ! 354: ! 355: 0 2 RND(n bytes) 0 1 DEK(16 bytes) CSUM(2 bytes) ! 356: ! 357: CSUM refers to a 16-bit checksum appended to the high end of the DEK. ! 358: RND is a string of NONZERO pseudorandom bytes, enough to make the length ! 359: of this whole string equal to the number of bytes in the modulus. ! 360: ! 361: For both versions, the 16-bit checksum is computed on the rest of the ! 362: bytes in the DEK key material, and does not include any other material ! 363: in the calculation. In the above MSB-first representation, the ! 364: checksum is also stored MSB-first. The checksum is there to help us ! 365: determine if we used the right RSA secret key for decryption. ! 366: ! 367: ! 368: All this mainly affects the rsa_public_encrypt() and rsa_private_decrypt() ! 369: functions in rsaglue.c. ! 370: ! 371: ! 372: ! 373: Conventional Key Encrypted data packet ! 374: -------------------------------------- ! 375: ! 376: Offset Length Meaning ! 377: 0 1 CTB for Conventional-Key-Encrypted data packet ! 378: 1 4 32-bit (or maybe 16-bit) length of packet ! 379: 5 ? conventionally-encrypted data. ! 380: plaintext has 64 bits of random data prepended, ! 381: plus 16 bits prepended for "key check" purposes ! 382: ! 383: The decrypted ciphertext may contain a compressed data packet or a ! 384: literal plaintext packet. ! 385: ! 386: After decrypting the conventionally-encrypted data, a special 8-byte ! 387: random prefix and 2 "key check" bytes are revealed. The random prefix ! 388: and key check prefix are inserted before encryption and discarded after ! 389: decryption. This prefix group is visible after decrypting the ! 390: ciphertext in the packet. ! 391: ! 392: The random prefix serves to start off the cipher feedback chaining ! 393: process with 64 bits of random material. It may be discarded after ! 394: decryption. The first 8 bytes is the random prefix material, followed ! 395: by the 2-byte "key-check" prefix. ! 396: ! 397: The key-check prefix is composed of two identical copies of the last ! 398: 2 random bytes in the random prefix, in the same order. During ! 399: decryption, the 9th and 10th bytes of decrypted plaintext are checked ! 400: to see if they match the 7th and 8th bytes, respectively. If these ! 401: key-check bytes meet this criterion, then the conventional key is ! 402: assumed to be correct. ! 403: ! 404: One unusual point about the way encryption is done. Using the IDEA ! 405: cipher in CFB mode, the first 10 bytes are decrypted normally, ! 406: but bytes 10 to 17, the first 8 bytes of the data proper, are ! 407: encrypted using bytes 2 to 9 (the last 8 bytes of the key check ! 408: prefix) as the IV. This is essentially using CFB-16 for one ! 409: part of the encryption, while CFB-64 is used elsewhere. ! 410: ! 411: ! 412: Compressed data packet ! 413: ---------------------- ! 414: ! 415: Offset Length Meaning ! 416: 0 1 CTB for Compressed data packet ! 417: 1 1 Compression algorithm selector byte (1=ZIP) ! 418: 2 ? compressed data ! 419: ! 420: The compressed data begins right after the algorithm selector byte. ! 421: The compressed data may decompress into a raw literal plaintext data ! 422: packet with its own CTB. Currently, compressed data packets ! 423: are always the last ones in their enclosing object, and the decompressor ! 424: knows when to stop, so the length field is omitted. The low two bits ! 425: of the CTB are set to 11. This is the only case in PGP where this ! 426: is currently done. ! 427: ! 428: ! 429: Literal data packet, with filename and mode ! 430: ------------------------------------------- ! 431: ! 432: Offset Length Meaning ! 433: 0 1 CTB for raw literal data packet ! 434: 1 4 32-bit (or maybe 16-bit) length of packet ! 435: 5 1 mode byte, 'b'= binary or 't'= canonical text ! 436: 6 ? filename, with leading string length byte ! 437: ? 4 Timestamp of last-modified date, or 0, or right now ! 438: ? ? raw literal plaintext data ! 439: ! 440: The timestamp may be have to be derived in a system dependent manner. ! 441: ANSI C functions should be used to get it if available, otherwise ! 442: store the current time in it. Or maybe store 0 if it's somehow not ! 443: applicable. ! 444: ! 445: Whne calculating a signature on a literal packet, the signature ! 446: calculation only includes the raw literal plaintext data that begins ! 447: AFTER the header fields in the literal packet-- after the CTB, the ! 448: length, the mode byte, the filename, and the timestamp. The reason ! 449: for this is to guarantee that detached signatures are exactly the ! 450: same as attached signatures prefixed to the message. Detached ! 451: signatures are calculated on a separate file that has no packet ! 452: encapsulation. ! 453: ! 454: ! 455: ! 456: Comment packet ! 457: -------------- ! 458: ! 459: A comment packet is generally just skipped over by PGP, although it ! 460: may be displayed to the user when processed. It can be put in a ! 461: keyring, or anywhere else. ! 462: ! 463: Offset Length Meaning ! 464: 0 1 CTB for Comment packet ! 465: 1 1 8-bit length of packet ! 466: 2 ? ASCII comment, size is as in preceding length byte ! 467: ! 468: Comment packets are currently not generated by PGP. ! 469: ! 470: ! 471: ! 472: Secret key certificate ! 473: ---------------------- ! 474: ! 475: Offset Length Meaning ! 476: 0 1 CTB for secret key certificate ! 477: 1 2 16-bit (or maybe 8-bit) length of packet ! 478: 3 1 Version byte, may affect rest of fields that follow. ! 479: (=2) for PGP versions <= 2.5 ! 480: (=3) for PGP versions >= 2.6 ! 481: 4 4 Timestamp ! 482: 8 2 Validity period, in number of DAYS (0 means forever) ! 483: 10 1 Algorithm byte for RSA (=1 for RSA). ! 484: --Algorithm byte affects field definitions that follow. ! 485: ? ? MPI of RSA public modulus n ! 486: ? ? MPI of RSA public encryption exponent e ! 487: ! 488: ? 1 Algorithm byte for cipher that protects following ! 489: secret components (0=unencrypted, 1=IDEA cipher) ! 490: ? 8 Cipher Feedback IV for cipher that protects secret ! 491: components (not present if unencrypted) ! 492: ? ? MPI of RSA secret decryption exponent d ! 493: ? ? MPI of RSA secret factor p ! 494: ? ? MPI of RSA secret factor q ! 495: ? ? MPI of RSA secret multiplicative inverse u ! 496: (All MPI's have bitcount prefixes) ! 497: ? 2 16-bit checksum of all preceding secret component bytes ! 498: ! 499: All secret fields in the secret key certificate may be password- ! 500: encrypted, including the checksum. The checksum is calculated from ! 501: all of the bytes of the unenciphered secret components. The public ! 502: fields are not encrypted. The encrypted fields are done in CFB mode, ! 503: and the checksum is used to tell if the password was good. The CFB ! 504: IV field is just encrypted random data, assuming the "true" IV was ! 505: zero. ! 506: ! 507: NOTE: The secret key packet does not contain a User ID field. The ! 508: User ID is enclosed in a separate packet that always follows the secret ! 509: key packet on a keyring or in any other context. ! 510: ! 511: ! 512: Public key certificate ! 513: ---------------------- ! 514: ! 515: Offset Length Meaning ! 516: 0 1 CTB for public key certificate ! 517: 1 2 16-bit (or maybe 8-bit) length of packet ! 518: 3 1 Version byte, may affect rest of fields that follow. ! 519: (=2) for PGP versions <= 2.5 ! 520: (=3) for PGP versions >= 2.6 ! 521: 4 4 Timestamp of key creation ! 522: 8 2 Validity period, in number of DAYS (0 means forever) ! 523: 10 1 Algorithm byte for RSA (=1 for RSA). ! 524: --Algorithm byte affects field definitions that follow. ! 525: ? ? MPI of RSA public modulus n ! 526: ? ? MPI of RSA public encryption exponent e ! 527: (All MPI's have bitcount prefixes) ! 528: ! 529: NOTE: The public key packet does not contain a User ID field. The ! 530: User ID is enclosed in a separate packet that always follows ! 531: somewhere after the public key packet on a keyring or in any other ! 532: context. ! 533: ! 534: The validity period is currently always set to 0. ! 535: ! 536: ! 537: ! 538: User ID packet ! 539: -------------- ! 540: ! 541: Offset Length Meaning ! 542: 0 1 CTB for User ID packet ! 543: 1 1 8-bit length of packet ! 544: 2 ? User ID string, size is as in preceding length byte ! 545: ! 546: The User ID packet follows a public key on a public key ring. It ! 547: also follows a secret key on a secret key ring. ! 548: ! 549: When a key is certified by a signature, the signature covers both the ! 550: public key packet and the User ID packet. The signature certificate ! 551: thereby logically "binds" together the user ID with the key. The ! 552: user ID packet is always associated with the most recently occurring ! 553: public key on the key ring, regardless of whether there are other ! 554: packet types appearing between the public key packet and the ! 555: associated user ID packet. ! 556: ! 557: There may be more than one User ID packet after a public key packet. ! 558: They all would be associated with the preceding public key packet. ! 559: ! 560: ! 561: Keyring trust packet ! 562: -------------------- ! 563: ! 564: The three different forms of this packet each come after: a public key ! 565: packet, a user ID packet, or a signature packet on the public key ! 566: ring. They exist only on a public key ring, and are never extracted ! 567: with a key. Don't copy this separate trust byte packet from keyring, ! 568: and do add it in back in when adding to keyring. ! 569: ! 570: The meaning of the keyring trust packet is context sensitive. The ! 571: trust byte has three different definitions depending on whether it ! 572: follows a key packet on the ring, or follows a user ID packet on the ! 573: ring, or follows a signature on the ring. ! 574: ! 575: Offset Length Meaning ! 576: 0 1 CTB for Keyring trust packet ! 577: 1 1 8-bit length of packet (always 1 for now) ! 578: 2 1 Trust flag byte, with context-sensitive bit ! 579: definitions given below. ! 580: ! 581: ! 582: For trust bytes that apply to the preceding key packet, the following ! 583: bit definitions apply: ! 584: ! 585: Bits 0-2 - OWNERTRUST bits - Trust bits for this key owner. Values are: ! 586: 000 - undefined, or uninitialized trust. ! 587: 001 - unknown, we don't know the owner of this key. ! 588: 010 - We usually do not trust this key owner to sign other keys. ! 589: 011 - reserved ! 590: 100 - reserved ! 591: 101 - We usually do trust this key owner to sign other keys. ! 592: 110 - We always trust this key owner to sign other keys. ! 593: 111 - This key is also present in the secret keyring. ! 594: Bits 3-4 - Reserved. ! 595: Bit 5 - DISABLED bit - Means that this key is disabled, and ! 596: should not be used. ! 597: Bit 6 - Reserved ! 598: Bit 7 - BUCKSTOP bit - Means this key also appears in secret key ring. ! 599: Signifies the ultimately-trusted "keyring owner". ! 600: "The buck stops here". This bit computed from looking ! 601: at secret key ring. If this bit is set, then all the ! 602: KEYLEGIT fields are set to maximum for all the user IDs for ! 603: this key, and OWNERTRUST is also set to ultimate trust. ! 604: ! 605: For trust bytes that apply to the preceding user ID packet, the ! 606: following bit definitions apply: ! 607: ! 608: Bit 0-1 - KEYLEGIT bits - Validity bits for this key. ! 609: Set if we believe the preceding key is legitimately owned by ! 610: who it appears to belong to, specified by the preceding user ! 611: ID. Computed from various signature trust packets that ! 612: follow. Also, always fully set if BUCKSTOP is set. ! 613: To define the KEYLEGIT byte does not require that ! 614: OWNERTRUST be nonzero, but OWNERTRUST nonzero does require ! 615: that KEYLEGIT be fully set to maximum trust. ! 616: 00 - unknown, undefined, or uninitialized trust. ! 617: 01 - We do not trust this key's ownership. ! 618: 10 - We have marginal confidence of this key's ownership. ! 619: Totally useless for certifying other keys, but may be useful ! 620: for checking message signatures with an advisory warning ! 621: to the user. ! 622: 11 - We completely trust this key's ownership. ! 623: This requires either: ! 624: - 1 ultimately trusted signature (a signature from ! 625: yourself, SIGTRUST=111) ! 626: - COMPLETES_NEEDED completely trusted signatures ! 627: (SIGTRUST=110) ! 628: - MARGINALS_NEEDED marginally trusted signatures ! 629: (SIGTRUST=101) ! 630: COMPLETES_NEEDED and MARGINALS_NEEDED are configurable ! 631: constants. ! 632: Bit 7 - WARNONLY bit - If the user wants to use a not fully validated ! 633: key for encryption, he is asked if he really wants to use this ! 634: key. If the user answers 'yes', the WARNONLY bit gets set, ! 635: and the next time he uses this key, only a warning will be ! 636: printed. This bit gets cleared during the maintenance pass. ! 637: ! 638: For a trust byte that applies to the preceding signature, the ! 639: following bit definitions apply: ! 640: ! 641: Bits 0-2 - SIGTRUST bits - Trust bits for this signature. Value is ! 642: copied directly from OWNERTRUST bits of signer: ! 643: 000 - undefined, or uninitialized trust. ! 644: 001 - unknown ! 645: 010 - We do not trust this signature. ! 646: 011 - reserved ! 647: 100 - reserved ! 648: 101 - We reasonably trust this signature. ! 649: 110 - We completely trust this signature. ! 650: 111 - ultimately trusted signature (from the owner of the ring) ! 651: Bits 3-6 - Reserved. ! 652: Bit 6 - CHECKED bit - This means that the key checking pass (pgp -kc, ! 653: also invoked automatically whenever keys are added to the ! 654: keyring) has tested this signature and found it good. If ! 655: this bit is not set, the maintenance pass considers this ! 656: signature untrustworthy. ! 657: Bit 7 - CONTIG bit - Means this signature leads up a contiguous trusted ! 658: certification path all the way back to the ultimately- ! 659: trusted keyring owner, where the buck stops. This bit is derived ! 660: from other trust packets. It is currently not used for anything ! 661: in PGP. ! 662: ! 663: The OWNERTRUST bits are set by the user. PGP does not modify them. ! 664: PGP computes the BUCKSTOP bit by checking to see if the key is on the ! 665: secret key ring. If it is, it was created by this user, and thus ! 666: controlled by him. ! 667: ! 668: All other trust is derived from the BUCKSTOP keys in a special ! 669: maintenance pass over the keyring. Any good signature made by a given ! 670: key has its SIGTRUST equal to the key's OWNERTRUST. Based on ! 671: COMPLETES_NEEDED and MARGINALS_NEEDED, if enough trusted signatures are ! 672: on a key/userID pair, the key/userid association is considered ! 673: legitimate. ! 674: ! 675: To be precise, an ultimately trusted key has weight 1, a completely ! 676: trusted key has weight 1/COMPLETES_NEEDED (or 0 if COMPLETES_NEEDED ! 677: is 0), and a marginally trsuted key has weight 1/MARGINALS_NEEDED. ! 678: Other trust values have weight 0. If the total weight of the signatures ! 679: on a key/userid pair is 1 or more, the userid is considered legitimate. ! 680: ! 681: When a key has a legitimate userid, the user is asked to set the ! 682: OWNERTRUST for the corresponding key. Ths idea is that the userid ! 683: identifies someone the user knows, at least by reputation, so once it ! 684: has been established who holds the secret key, that person's ! 685: trustworthiness as an introducer can be established and assigned to the ! 686: key. ! 687: ! 688: Once that is done, the key's signatures then have weight establishing ! 689: other key/userid associations. ! 690: ! 691: There is a limit to the depth to which this can go. Keys on the secret ! 692: keyring are at depth 0. Keys signed by those keys are at depth 1. ! 693: Keys which are fully certified using only signatures from keys at depth ! 694: 1 or less are at depth 2. Keys which are fully certified using only ! 695: signatures from keys at depth 2 or less are at depth 3, and so on. ! 696: ! 697: If you know all of your trusted introducers personally, and have signed ! 698: their keys, then you will never have a key at a depth of greater than 2. ! 699: The maximum depth is limited my MAX_CERT_DPETH. It never gets very large ! 700: in a well-connected "web of trust". ! 701: ! 702: This redundant and decentralized method of determining public key ! 703: legitimacy is one of the principal strengths of PGP's key management ! 704: architecture, as compared with PEM, when used in social structures ! 705: that are not miltiary-style rigid hierarchies. ! 706: ! 707: The trust of a key owner (OWNERTRUST) does not just reflect our ! 708: estimation of their personal integrity, it also reflects how competent ! 709: we think they are at understanding key management and using good ! 710: judgement in signing keys. The OWNERTRUST bits are not computed from ! 711: anything -- it requires asking the user for his opinion. ! 712: ! 713: To define the OWNERTRUST bits for a key owner, ask: ! 714: Would you always trust "Oliver North" ! 715: to certify other public keys? ! 716: (1=Yes, 2=No, 3=Usually, 4=I don't know) ? _ ! 717: ! 718: When a key is added to the key ring the trust bytes are initialized ! 719: to zero (undefined). ! 720: ! 721: ! 722: [--manual setting of SIGTRUST/OWNERTRUST not implemented] ! 723: Normally, we derive the value of the SIGTRUST field by copying it ! 724: directly from the signer key's OWNERTRUST field. Under special ! 725: circumstances, if the user explicitly requests it with a special PGP ! 726: command, we may let the user override the copied value for SIGTRUST ! 727: by displaying an advisory to him and asking him for ratification, ! 728: like so: ! 729: This key is signed by "Oliver North", ! 730: whom you usually trust to sign keys. ! 731: Do you trust "Oliver North" ! 732: to certify the key for "Daniel Ellsberg"? ! 733: (1=Yes, 2=No, 3=Somewhat, 4=I don't know) ? _ <default is yes> ! 734: ! 735: Or: ! 736: This key is signed by "Oliver North", ! 737: whom you usually do not trust to sign keys. ! 738: Do you trust "Oliver North" ! 739: to certify the key for "Daniel Ellsberg"? ! 740: (1=Yes, 2=No, 3=Somewhat, 4=I don't know) ? _ <default is no> ! 741: ! 742: An "I don't know" response to this question would have the same ! 743: effect as a response of "no". ! 744: ! 745: If we had no information about the trustworthiness of the signer (the ! 746: OWNERTRUST field was uninitialized), we would leave the advisory note ! 747: off. ! 748: ! 749: ! 750: Certifying a public key is a serious matter, essentially promising to ! 751: the world that you vouch for this key's ownership. But sometimes I ! 752: just want to make a "working assumption" of trust for someone's ! 753: public key, for my own purposes on my own keyring, without taking the ! 754: serious step of actually certifying it for the rest of the world. In ! 755: that case, we can use a special PGP keyring management command to ! 756: manually set the KEYLEGIT field, without relying on it being computed ! 757: during a maintenance pass. Later, if a maintenance pass discovers a ! 758: KEYLEGIT bit set that would not have been otherwise computed as set ! 759: by the maintenance pass logic, it alerts me and asks me to confirm ! 760: that I really want it set. ! 761: ! 762: [--end of not implemented section] ! 763: ! 764: ! 765: During routine use of the public keyring, we don't actually check the ! 766: associated signatures certifying a public key. Rather, we always ! 767: rely on trust bytes to tell us whether to trust the key in question. ! 768: We depend on a separate checking pass (pgp -kc) to actually check the key ! 769: signature certificates against the associated keys, and to set the ! 770: trust bytes accordingly. This pass checks signatures, and if a ! 771: signature fails to verify, obnoxiously alerts the user and drops it from ! 772: the key ring. Then it tuns a maintenance pass to calculate the ! 773: ring-wide effects of this. ! 774: ! 775: A failed signature should be exceedingly rare, and it may not even ! 776: result in a KEYLEGIT field being downgraded. Having several signatures ! 777: certifying each key should prevent damage from spreading too far from a ! 778: failed certificate. But if dominoes do keep falling from this, it may ! 779: indicate the discovery of an important elaborate attack. ! 780: ! 781: The maintenance pass is run every time the keyring changes, and ! 782: operates in a top-of-pyramid-down manner as follows. ! 783: ! 784: If at any time during any of these steps the KEYLEGIT field goes from ! 785: not fully set to fully set, and the OWNERTRUST bits are still undefined, ! 786: the user is asked a question to define the OWNERTRUST bits. First, for ! 787: all keys with BUCKSTOP set, check if they are really present in the ! 788: secret keyring, if not, the BUCKSTOP bit is cleared. SIGTRUST and ! 789: KEYLEGIT is initialized to zero for non-buckstop keys. ! 790: ! 791: The real maintenance pass is done in a recursive scan: Start with ! 792: BUCKSTOP keys, find all userid/key pairs signed by a key and update ! 793: the trust value of these signatures by copying the OWNERTRUST of the ! 794: signer to the SIGTRUST of the signature. If this makes a key fully ! 795: validated, start looking for signatures made by this key, and update ! 796: the trust value for them. Repeat until everything has settled down. ! 797: ! 798: ! 799: ! 800: ! 801: Public Key Ring Overall Structure ! 802: ================================= ! 803: ! 804: A public key ring is comprised of a series of public key packets, ! 805: keyring trust packets, user ID packets, and signature certificates. ! 806: ! 807: Here is an example of an ordered collection of packets on a ring: ! 808: ! 809: -------------------------------------------------------------------- ! 810: Public key packet ! 811: Keyring trust packet for preceding key ! 812: User ID packet for preceding key ! 813: Keyring trust packet for preceding user ID/key association ! 814: Signature certificate to bind preceding User ID and key pkt ! 815: Keyring trust packet for preceding signature certificate ! 816: Signature certificate to bind preceding User ID and key pkt ! 817: Keyring trust packet for preceding signature certificate ! 818: Signature certificate to bind preceding User ID and key pkt ! 819: Keyring trust packet for preceding signature certificate ! 820: ! 821: Public key packet ! 822: Keyring trust packet for preceding key ! 823: User ID packet for preceding key ! 824: Keyring trust packet for preceding user ID/key association ! 825: Signature certificate to bind preceding User ID and key pkt ! 826: Keyring trust packet for preceding signature certificate ! 827: User ID packet for preceding key ! 828: Keyring trust packet for preceding user ID/key association ! 829: Signature certificate to bind preceding User ID and key pkt ! 830: Keyring trust packet for preceding signature certificate ! 831: Signature certificate to bind preceding User ID and key pkt ! 832: Keyring trust packet for preceding signature certificate ! 833: ! 834: Public key packet ! 835: Keyring trust packet for preceding key ! 836: Compromise certificate for preceding key ! 837: User ID packet for preceding key ! 838: Keyring trust packet for preceding user ID/key association ! 839: Signature certificate to bind preceding User ID and key pkt ! 840: Keyring trust packet for preceding signature certificate ! 841: --------------------------------------------------------------------
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.