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