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