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