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