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