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