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