* gpg.c (main): Properly handle UTF8 usernames with --sign-key and --lsign-key.
[gnupg.git] / doc / DETAILS
1                                                               -*- text -*-
2
3 NOTE: The definitive reference is the file from the SVN trunk.
4
5 Format of colon listings
6 ========================
7 First an example:
8
9 $ gpg --fixed-list-mode --with-colons --list-keys \
10    --with-fingerprint --with-fingerprint wk@gnupg.org
11
12 pub:f:1024:17:6C7EE1B8621CC013:899817715:1055898235::m:::scESC:
13 fpr:::::::::ECAF7590EB3443B5C7CF3ACB6C7EE1B8621CC013:
14 uid:f::::::::Werner Koch <wk@g10code.com>:
15 uid:f::::::::Werner Koch <wk@gnupg.org>:
16 sub:f:1536:16:06AD222CADF6A6E1:919537416:1036177416:::::e:
17 fpr:::::::::CF8BCC4B18DE08FCD8A1615906AD222CADF6A6E1:
18 sub:r:1536:20:5CE086B5B5A18FF4:899817788:1025961788:::::esc:
19 fpr:::::::::AB059359A3B81F410FCFF97F5CE086B5B5A18FF4:
20
21 The double --with-fingerprint prints the fingerprint for the subkeys
22 too, --fixed-list-mode is themodern listing way printing dates in
23 seconds since Epoch and does not merge the first userID with the pub
24 record.
25
26
27  1. Field:  Type of record
28             pub = public key
29             crt = X.509 certificate
30             crs = X.509 certificate and private key available
31             sub = subkey (secondary key)
32             sec = secret key
33             ssb = secret subkey (secondary key)
34             uid = user id (only field 10 is used).
35             uat = user attribute (same as user id except for field 10).
36             sig = signature
37             rev = revocation signature
38             fpr = fingerprint: (fingerprint is in field 10)
39             pkd = public key data (special field format, see below)
40             grp = reserved for gpgsm
41             rvk = revocation key
42             tru = trust database information
43             spk = signature subpacket
44
45  2. Field:  A letter describing the calculated trust. This is a single
46             letter, but be prepared that additional information may follow
47             in some future versions. (not used for secret keys)
48                 o = Unknown (this key is new to the system)
49                 i = The key is invalid (e.g. due to a missing self-signature)
50                 d = The key has been disabled
51                     (deprecated - use the 'D' in field 12 instead)
52                 r = The key has been revoked
53                 e = The key has expired
54                 - = Unknown trust (i.e. no value assigned)
55                 q = Undefined trust
56                     '-' and 'q' may safely be treated as the same
57                     value for most purposes
58                 n = Don't trust this key at all
59                 m = There is marginal trust in this key
60                 f = The key is fully trusted
61                 u = The key is ultimately trusted.  This often means
62                     that the secret key is available, but any key may
63                     be marked as ultimately trusted.
64  3. Field:  length of key in bits.
65  4. Field:  Algorithm:  1 = RSA
66                        16 = Elgamal (encrypt only)
67                        17 = DSA (sometimes called DH, sign only)
68                        20 = Elgamal (sign and encrypt - don't use them!)
69             (for other id's see include/cipher.h)
70  5. Field:  KeyID
71  6. Field:  Creation Date (in UTC).  For UID and UAT records, this is the
72             self-signature date.  Note that the dae is usally printed
73             in seconds since epoch, however, we are migrating to an ISO
74             8601 format (e.g. "19660205T091500").  This is currently
75             only relevant for X.509, A simple way to detect the format
76             is be scannning for the 'T'.
77  7. Field:  Key or user ID/user attribute expiration date or empty if none.
78  8. Field:  Used for serial number in crt records (used to be the Local-ID).
79             For UID and UAT records, this is a hash of the user ID contents
80             used to represent that exact user ID.  For trust signatures,
81             this is the trust depth seperated by the trust value by a
82             space.
83  9. Field:  Ownertrust (primary public keys only)
84             This is a single letter, but be prepared that additional
85             information may follow in some future versions.  For trust
86             signatures with a regular expression, this is the regular
87             expression value, quoted as in field 10.
88 10. Field:  User-ID.  The value is quoted like a C string to avoid
89             control characters (the colon is quoted "\x3a").
90             This is not used with --fixed-list-mode in gpg.
91             A UAT record puts the attribute subpacket count here, a
92             space, and then the total attribute subpacket size.
93             In gpgsm the issuer name comes here
94             An FPR record stores the fingerprint here.
95             The fingerprint of an revocation key is stored here.
96 11. Field:  Signature class.  This is a 2 digit hexnumber followed by
97             either the letter 'x' for an exportable signature or the
98             letter 'l' for a local-only signature.
99             The class byte of an revocation key is also given here,
100             'x' and 'l' ist used the same way.
101 12. Field:  Key capabilities:
102                 e = encrypt
103                 s = sign
104                 c = certify
105                 a = authentication
106             A key may have any combination of them in any order.  In
107             addition to these letters, the primary key has uppercase
108             versions of the letters to denote the _usable_
109             capabilities of the entire key, and a potential letter 'D'
110             to indicate a disabled key.
111 13. Field:  Used in FPR records for S/MIME keys to store the fingerprint of
112             the issuer certificate.  This is useful to build the
113             certificate path based on certificates stored in the local
114             keyDB; it is only filled if the issue certificate is
115             available. The advantage of using this value is that it is
116             guaranteed to have been been build by the same lookup
117             algorithm as gpgsm uses.
118             For "uid" recods this lists the preferences n the sameway the 
119             -edit menu does.
120             For "sig" records, this is the fingerprint of the key that
121             issued the signature.  Note that this is only filled in if
122             the signature verified correctly.  Note also that for
123             various technical reasons, this fingerprint is only
124             available if --no-sig-cache is used.
125
126 14. Field   Flag field used in the --edit menu output:
127
128 15. Field   Used in sec/sbb to print the serial number of a token
129             (internal protect mode 1002) or a '#' if that key is a
130             simple stub (internal protect mode 1001)
131
132 All dates are displayed in the format yyyy-mm-dd unless you use the
133 option --fixed-list-mode in which case they are displayed as seconds
134 since Epoch.  More fields may be added later, so parsers should be
135 prepared for this. When parsing a number the parser should stop at the
136 first non-number character so that additional information can later be
137 added.
138
139 If field 1 has the tag "pkd", a listing looks like this:
140 pkd:0:1024:B665B1435F4C2 .... FF26ABB:
141     !  !   !-- the value
142     !  !------ for information number of bits in the value
143     !--------- index (eg. DSA goes from 0 to 3: p,q,g,y)
144
145
146 The "tru" trust database records have the fields:
147
148  2: Reason for staleness of trust.  If this field is empty, then the
149     trustdb is not stale.  This field may have multiple flags in it:
150
151     o: Trustdb is old
152     t: Trustdb was built with a different trust model than the one we
153        are using now.
154
155  3: Trust model:
156     0: Classic trust model, as used in PGP 2.x.
157     1: PGP trust model, as used in PGP 6 and later.  This is the same
158        as the classic trust model, except for the addition of trust
159        signatures.
160
161     GnuPG before version 1.4 used the classic trust model by default.
162     GnuPG 1.4 and later uses the PGP trust model by default.
163
164  4: Date trustdb was created in seconds since 1/1/1970.
165  5: Date trustdb will expire in seconds since 1/1/1970.
166
167 The "spk" signature subpacket records have the fields:
168
169  2: Subpacket number as per RFC-2440 and later.
170  3: Flags in hex.  Currently the only two bits assigned are 1, to
171     indicate that the subpacket came from the hashed part of the
172     signature, and 2, to indicate the subpacket was marked critical.
173  4: Length of the subpacket.  Note that this is the length of the
174     subpacket, and not the length of field 5 below.  Due to the need
175     for %-encoding, the length of field 5 may be up to 3x this value.
176  5: The subpacket data.  Printable ASCII is shown as ASCII, but other
177     values are rendered as %XX where XX is the hex value for the byte.
178
179
180 Format of the "--status-fd" output
181 ==================================
182 Every line is prefixed with "[GNUPG:] ", followed by a keyword with
183 the type of the status line and a some arguments depending on the
184 type (maybe none); an application should always be prepared to see
185 more arguments in future versions.
186
187
188     NEWSIG
189         May be issued right before a signature verification starts.  This
190         is useful to define a context for parsing ERROR status
191         messages.  No arguments are currently defined.
192
193     GOODSIG     <long keyid>  <username>
194         The signature with the keyid is good.  For each signature only
195         one of the three codes GOODSIG, BADSIG or ERRSIG will be
196         emitted and they may be used as a marker for a new signature.
197         The username is the primary one encoded in UTF-8 and %XX
198         escaped.
199
200     EXPSIG      <long keyid>  <username>
201         The signature with the keyid is good, but the signature is
202         expired. The username is the primary one encoded in UTF-8 and
203         %XX escaped.
204
205     EXPKEYSIG   <long keyid>  <username>
206         The signature with the keyid is good, but the signature was
207         made by an expired key. The username is the primary one
208         encoded in UTF-8 and %XX escaped.
209
210     REVKEYSIG   <long keyid>  <username>
211         The signature with the keyid is good, but the signature was
212         made by a revoked key. The username is the primary one
213         encoded in UTF-8 and %XX escaped.
214
215     BADSIG      <long keyid>  <username>
216         The signature with the keyid has not been verified okay.
217         The username is the primary one encoded in UTF-8 and %XX
218         escaped.
219
220     ERRSIG  <long keyid>  <pubkey_algo> <hash_algo> \
221             <sig_class> <timestamp> <rc>
222         It was not possible to check the signature.  This may be
223         caused by a missing public key or an unsupported algorithm.
224         A RC of 4 indicates unknown algorithm, a 9 indicates a missing
225         public key. The other fields give more information about
226         this signature.  sig_class is a 2 byte hex-value.
227
228         Note, that TIMESTAMP may either be a number with seconds since
229         epoch or an ISO 8601 string which can be detected by the
230         presence of the letter 'T' inside.
231
232     VALIDSIG    <fingerprint in hex> <sig_creation_date> <sig-timestamp>
233                 <expire-timestamp> <sig-version> <reserved> <pubkey-algo>
234                 <hash-algo> <sig-class> <primary-key-fpr>
235
236         The signature with the keyid is good. This is the same as
237         GOODSIG but has the fingerprint as the argument. Both status
238         lines are emitted for a good signature.  All arguments here
239         are on one long line.  sig-timestamp is the signature creation
240         time in seconds after the epoch. expire-timestamp is the
241         signature expiration time in seconds after the epoch (zero
242         means "does not expire"). sig-version, pubkey-algo, hash-algo,
243         and sig-class (a 2-byte hex value) are all straight from the
244         signature packet.  PRIMARY-KEY-FPR is the fingerprint of the
245         primary key or identical to the first argument.  This is
246         useful to get back to the primary key without running gpg
247         again for this purpose.
248
249         Note, that *-TIMESTAMP may either be a number with seconds
250         since epoch or an ISO 8601 string which can be detected by the
251         presence of the letter 'T' inside.
252
253     SIG_ID  <radix64_string>  <sig_creation_date>  <sig-timestamp>
254         This is emitted only for signatures of class 0 or 1 which
255         have been verified okay.  The string is a signature id
256         and may be used in applications to detect replay attacks
257         of signed messages.  Note that only DLP algorithms give
258         unique ids - others may yield duplicated ones when they
259         have been created in the same second.
260
261         Note, that SIG-TIMESTAMP may either be a number with seconds
262         since epoch or an ISO 8601 string which can be detected by the
263         presence of the letter 'T' inside.
264
265
266     ENC_TO  <long keyid>  <keytype>  <keylength>
267         The message is encrypted to this keyid.
268         keytype is the numerical value of the public key algorithm,
269         keylength is the length of the key or 0 if it is not known
270         (which is currently always the case).
271
272     NODATA  <what>
273         No data has been found. Codes for what are:
274             1 - No armored data.
275             2 - Expected a packet but did not found one.
276             3 - Invalid packet found, this may indicate a non OpenPGP
277                 message.
278             4 - signature expected but not found
279         You may see more than one of these status lines.
280
281     UNEXPECTED <what>
282         Unexpected data has been encountered
283             0 - not further specified               1       
284   
285
286     TRUST_UNDEFINED <error token>
287     TRUST_NEVER  <error token>
288     TRUST_MARGINAL
289     TRUST_FULLY
290     TRUST_ULTIMATE
291         For good signatures one of these status lines are emitted
292         to indicate how trustworthy the signature is.  The error token
293         values are currently only emiited by gpgsm.
294
295     PKA_TRUST_GOOD <mailbox>
296     PKA_TRUST_BAD  <mailbox>
297         Depending on the outcome of the PKA check one of the above
298         status codes is emitted in addition to a TRUST_* status.
299         Without PKA info available or 
300
301     SIGEXPIRED
302         This is deprecated in favor of KEYEXPIRED.
303
304     KEYEXPIRED <expire-timestamp>
305         The key has expired.  expire-timestamp is the expiration time
306         in seconds after the epoch.
307
308         Note, that TIMESTAMP may either be a number with seconds since
309         epoch or an ISO 8601 string which can be detected by the
310         presence of the letter 'T' inside.
311
312     KEYREVOKED
313         The used key has been revoked by its owner.  No arguments yet.
314
315     BADARMOR
316         The ASCII armor is corrupted.  No arguments yet.
317
318     RSA_OR_IDEA
319         The IDEA algorithms has been used in the data.  A
320         program might want to fallback to another program to handle
321         the data if GnuPG failed.  This status message used to be emitted
322         also for RSA but this has been dropped after the RSA patent expired.
323         However we can't change the name of the message.
324
325     SHM_INFO
326     SHM_GET
327     SHM_GET_BOOL
328     SHM_GET_HIDDEN
329
330     GET_BOOL
331     GET_LINE
332     GET_HIDDEN
333     GOT_IT
334
335     NEED_PASSPHRASE <long main keyid> <long keyid> <keytype> <keylength>
336         Issued whenever a passphrase is needed.
337         keytype is the numerical value of the public key algorithm
338         or 0 if this is not applicable, keylength is the length
339         of the key or 0 if it is not known (this is currently always the case).
340
341     NEED_PASSPHRASE_SYM <cipher_algo> <s2k_mode> <s2k_hash>
342         Issued whenever a passphrase for symmetric encryption is needed.
343
344     NEED_PASSPHRASE_PIN <card_type> <chvno> [<serialno>]
345         Issued whenever a PIN is requested to unlock a card.
346
347     MISSING_PASSPHRASE
348         No passphrase was supplied.  An application which encounters this
349         message may want to stop parsing immediately because the next message
350         will probably be a BAD_PASSPHRASE.  However, if the application
351         is a wrapper around the key edit menu functionality it might not
352         make sense to stop parsing but simply ignoring the following
353         BAD_PASSPHRASE.
354
355     BAD_PASSPHRASE <long keyid>
356         The supplied passphrase was wrong or not given.  In the latter case
357         you may have seen a MISSING_PASSPHRASE.
358
359     GOOD_PASSPHRASE
360         The supplied passphrase was good and the secret key material
361         is therefore usable.
362
363     DECRYPTION_FAILED
364         The symmetric decryption failed - one reason could be a wrong
365         passphrase for a symmetrical encrypted message.
366
367     DECRYPTION_OKAY
368         The decryption process succeeded.  This means, that either the
369         correct secret key has been used or the correct passphrase
370         for a conventional encrypted message was given.  The program
371         itself may return an errorcode because it may not be possible to
372         verify a signature for some reasons.
373
374     NO_PUBKEY  <long keyid>
375     NO_SECKEY  <long keyid>
376         The key is not available
377
378     IMPORT_CHECK <long keyid> <fingerprint> <user ID>
379         This status is emitted in interactive mode right before
380         the "import.okay" prompt.
381
382     IMPORTED   <long keyid>  <username>
383         The keyid and name of the signature just imported
384
385     IMPORT_OK  <reason> [<fingerprint>]
386         The key with the primary key's FINGERPRINT has been imported.
387         Reason flags:
388           0 := Not actually changed
389           1 := Entirely new key.
390           2 := New user IDs
391           4 := New signatures
392           8 := New subkeys 
393          16 := Contains private key.
394         The flags may be ORed.
395
396     IMPORT_PROBLEM <reason> [<fingerprint>]
397         Issued for each import failure.  Reason codes are:
398           0 := "No specific reason given".
399           1 := "Invalid Certificate".
400           2 := "Issuer Certificate missing".
401           3 := "Certificate Chain too long".
402           4 := "Error storing certificate".
403
404     IMPORT_RES <count> <no_user_id> <imported> <imported_rsa> <unchanged>
405         <n_uids> <n_subk> <n_sigs> <n_revoc> <sec_read> <sec_imported> <sec_dups> <not_imported>
406         Final statistics on import process (this is one long line)
407
408     FILE_START <what> <filename>
409         Start processing a file <filename>.  <what> indicates the performed
410         operation:
411             1 - verify
412             2 - encrypt
413             3 - decrypt        
414
415     FILE_DONE
416         Marks the end of a file processing which has been started
417         by FILE_START.
418
419     BEGIN_DECRYPTION
420     END_DECRYPTION
421         Mark the start and end of the actual decryption process.  These
422         are also emitted when in --list-only mode.
423
424     BEGIN_ENCRYPTION  <mdc_method> <sym_algo>
425     END_ENCRYPTION
426         Mark the start and end of the actual encryption process.
427
428     BEGIN_SIGNING
429        Mark the start of the actual signing process. This may be used
430        as an indication that all requested secret keys are ready for
431        use.
432
433     DELETE_PROBLEM reason_code
434         Deleting a key failed.  Reason codes are:
435             1 - No such key
436             2 - Must delete secret key first
437             3 - Ambigious specification
438
439     PROGRESS what char cur total
440         Used by the primegen and Public key functions to indicate progress.
441         "char" is the character displayed with no --status-fd enabled, with
442         the linefeed replaced by an 'X'.  "cur" is the current amount
443         done and "total" is amount to be done; a "total" of 0 indicates that
444         the total amount is not known.  100/100 may be used to detect the
445         end of operation.
446         Well known values for WHAT:
447              "pk_dsa"   - DSA key generation
448              "pk_elg"   - Elgamal key generation
449              "primegen" - Prime generation
450              "need_entropy" - Waiting for new entropy in the RNG
451              "file:XXX" - processing file XXX
452                           (note that current gpg versions leave out the
453                            "file:" prefix).
454              "tick"     - generic tick without any special meaning - useful
455                           for letting clients know that the server is
456                           still working.
457              "starting_agent" - A gpg-agent was started because it is not
458                           running as a daemon.
459
460         
461     SIG_CREATED <type> <pubkey algo> <hash algo> <class> <timestamp> <key fpr>
462         A signature has been created using these parameters.
463             type:  'D' = detached
464                    'C' = cleartext
465                    'S' = standard
466                    (only the first character should be checked)
467             class: 2 hex digits with the signature class
468
469         Note, that TIMESTAMP may either be a number with seconds since
470         epoch or an ISO 8601 string which can be detected by the
471         presence of the letter 'T' inside.
472         
473     KEY_CREATED <type> <fingerprint> [<handle>]
474         A key has been created
475             type: 'B' = primary and subkey
476                   'P' = primary
477                   'S' = subkey
478         The fingerprint is one of the primary key for type B and P and
479         the one of the subkey for S.  Handle is an arbitrary
480         non-whitespace string used to match key parameters from batch
481         key creation run.
482
483     KEY_NOT_CREATED [<handle>]
484         The key from batch run has not been created due to errors.
485
486
487     SESSION_KEY  <algo>:<hexdigits>
488         The session key used to decrypt the message.  This message will
489         only be emitted when the special option --show-session-key
490         is used.  The format is suitable to be passed to the option
491         --override-session-key
492
493     NOTATION_NAME <name> 
494     NOTATION_DATA <string>
495         name and string are %XX escaped; the data may be splitted
496         among several notation_data lines.
497
498     USERID_HINT <long main keyid> <string>
499         Give a hint about the user ID for a certain keyID. 
500
501     POLICY_URL <string>
502         string is %XX escaped
503
504     BEGIN_STREAM
505     END_STREAM
506         Issued by pipemode.
507
508     INV_RECP <reason> <requested_recipient>
509         Issued for each unusable recipient. The reasons codes
510         currently in use are:
511           0 := "No specific reason given".
512           1 := "Not Found"
513           2 := "Ambigious specification"
514           3 := "Wrong key usage"
515           4 := "Key revoked"
516           5 := "Key expired"
517           6 := "No CRL known"
518           7 := "CRL too old"
519           8 := "Policy mismatch"
520           9 := "Not a secret key"
521          10 := "Key not trusted"
522
523         Note that this status is also used for gpgsm's SIGNER command
524         where it relates to signer's of course.
525
526     NO_RECP <reserved>
527         Issued when no recipients are usable.
528
529     ALREADY_SIGNED <long-keyid>
530         Warning: This is experimental and might be removed at any time.
531
532     TRUNCATED <maxno>
533         The output was truncated to MAXNO items.  This status code is issued
534         for certain external requests
535
536     ERROR <error location> <error code> 
537
538         This is a generic error status message, it might be followed
539         by error location specific data. <error token> and
540         <error_location> should not contain a space.  The error code
541         is a either a string commencing with a letter or such string
542         prefix with a numerical error code and an underscore; e.g.:
543         "151011327_EOF"
544
545     ATTRIBUTE <fpr> <octets> <type> <index> <count>
546               <timestamp> <expiredate> <flags>
547         This is one long line issued for each attribute subpacket when
548         an attribute packet is seen during key listing.  <fpr> is the
549         fingerprint of the key. <octets> is the length of the
550         attribute subpacket. <type> is the attribute type
551         (1==image). <index>/<count> indicates that this is the Nth
552         indexed subpacket of count total subpackets in this attribute
553         packet.  <timestamp> and <expiredate> are from the
554         self-signature on the attribute packet.  If the attribute
555         packet does not have a valid self-signature, then the
556         timestamp is 0.  <flags> are a bitwise OR of:
557                 0x01 = this attribute packet is a primary uid
558                 0x02 = this attribute packet is revoked
559                 0x04 = this attribute packet is expired
560
561     CARDCTRL <what> [<serialno>]
562         This is used to control smartcard operations.
563         Defined values for WHAT are:
564            1 = Request insertion of a card.  Serialnumber may be given
565                to request a specific card.
566            2 = Request removal of a card.
567            3 = Card with serialnumber detected
568            4 = No card available.
569            5 = No card reader available
570
571
572     PLAINTEXT <format> <timestamp> <filename>
573         This indicates the format of the plaintext that is about to be
574         written.  The format is a 1 byte hex code that shows the
575         format of the plaintext: 62 ('b') is binary data, 74 ('t') is
576         text data with no character set specified, and 75 ('u') is
577         text data encoded in the UTF-8 character set.  The timestamp
578         is in seconds since the epoch.  If a filename is available it
579         gets printed as the third argument, percent-escaped as usual.
580
581     PLAINTEXT_LENGTH <length>
582         This indicates the length of the plaintext that is about to be
583         written.  Note that if the plaintext packet has partial length
584         encoding it is not possible to know the length ahead of time.
585         In that case, this status tag does not appear.
586
587     SIG_SUBPACKET <type> <flags> <len> <data>
588         This indicates that a signature subpacket was seen.  The
589         format is the same as the "spk" record above.
590
591     SC_OP_FAILURE [<code>]
592         An operation on a smartcard definitely failed.  Currently
593         there is no indication of the actual error code, but
594         application should be prepared to later accept more arguments.
595         Defined values for CODE are:
596            0 - unspecified error (identically to a missing CODE)
597            1 - canceled
598            2 - bad PIN
599
600     SC_OP_SUCCESS
601         A smart card operaion succeeded.  This status is only printed
602         for certain operation and is mostly useful to check whether a
603         PIN change really worked.
604
605     BACKUP_KEY_CREATED fingerprint fname
606         A backup key named FNAME has been created for the key with
607         KEYID.
608
609
610 Format of the "--attribute-fd" output
611 =====================================
612
613 When --attribute-fd is set, during key listings (--list-keys,
614 --list-secret-keys) GnuPG dumps each attribute packet to the file
615 descriptor specified.  --attribute-fd is intended for use with
616 --status-fd as part of the required information is carried on the
617 ATTRIBUTE status tag (see above).
618
619 The contents of the attribute data is specified by 2440bis, but for
620 convenience, here is the Photo ID format, as it is currently the only
621 attribute defined:
622
623    Byte 0-1:  The length of the image header.  Due to a historical
624               accident (i.e. oops!) back in the NAI PGP days, this is
625               a little-endian number.  Currently 16 (0x10 0x00).
626
627    Byte 2:    The image header version.  Currently 0x01.
628
629    Byte 3:    Encoding format.  0x01 == JPEG.
630
631    Byte 4-15: Reserved, and currently unused.
632
633    All other data after this header is raw image (JPEG) data.
634
635
636 Format of the "--list-config" output
637 ====================================
638
639 --list-config outputs information about the GnuPG configuration for
640 the benefit of frontends or other programs that call GnuPG.  There are
641 several list-config items, all colon delimited like the rest of the
642 --with-colons output.  The first field is always "cfg" to indicate
643 configuration information.  The second field is one of (with
644 examples):
645
646 version: the third field contains the version of GnuPG.
647
648    cfg:version:1.3.5
649
650 pubkey: the third field contains the public key algorithmdcaiphers
651         this version of GnuPG supports, separated by semicolons.  The
652         algorithm numbers are as specified in RFC-2440.
653
654    cfg:pubkey:1;2;3;16;17
655
656 cipher: the third field contains the symmetric ciphers this version of
657         GnuPG supports, separated by semicolons.  The cipher numbers
658         are as specified in RFC-2440.
659
660    cfg:cipher:2;3;4;7;8;9;10
661
662 digest: the third field contains the digest (hash) algorithms this
663         version of GnuPG supports, separated by semicolons.  The
664         digest numbers are as specified in RFC-2440.
665
666    cfg:digest:1;2;3;8;9;10
667
668 compress: the third field contains the compression algorithms this
669           version of GnuPG supports, separated by semicolons.  The
670           algorithm numbers are as specified in RFC-2440.
671
672    cfg:compress:0;1;2;3
673
674 group: the third field contains the name of the group, and the fourth
675        field contains the values that the group expands to, separated
676        by semicolons.
677
678 For example, a group of:
679    group mynames = paige 0x12345678 joe patti
680
681 would result in:
682    cfg:group:mynames:patti;joe;0x12345678;paige
683
684
685 Key generation
686 ==============
687     Key generation shows progress by printing different characters to
688     stderr:
689              "."  Last 10 Miller-Rabin tests failed
690              "+"  Miller-Rabin test succeeded
691              "!"  Reloading the pool with fresh prime numbers
692              "^"  Checking a new value for the generator
693              "<"  Size of one factor decreased
694              ">"  Size of one factor increased
695
696     The prime number for Elgamal is generated this way:
697
698     1) Make a prime number q of 160, 200, 240 bits (depending on the keysize)
699     2) Select the length of the other prime factors to be at least the size
700        of q and calculate the number of prime factors needed
701     3) Make a pool of prime numbers, each of the length determined in step 2
702     4) Get a new permutation out of the pool or continue with step 3
703        if we have tested all permutations.
704     5) Calculate a candidate prime p = 2 * q * p[1] * ... * p[n] + 1
705     6) Check that this prime has the correct length (this may change q if
706        it seems not to be possible to make a prime of the desired length)
707     7) Check whether this is a prime using trial divisions and the
708        Miller-Rabin test.
709     8) Continue with step 4 if we did not find a prime in step 7.
710     9) Find a generator for that prime.
711
712     This algorithm is based on Lim and Lee's suggestion from the
713     Crypto '97 proceedings p. 260.
714
715
716 Unattended key generation
717 =========================
718 This feature allows unattended generation of keys controlled by a
719 parameter file.  To use this feature, you use --gen-key together with
720 --batch and feed the parameters either from stdin or from a file given
721 on the commandline.
722
723 The format of this file is as follows:
724   o Text only, line length is limited to about 1000 chars.
725   o You must use UTF-8 encoding to specify non-ascii characters.
726   o Empty lines are ignored.
727   o Leading and trailing spaces are ignored.
728   o A hash sign as the first non white space character indicates a comment line.
729   o Control statements are indicated by a leading percent sign, the
730     arguments are separated by white space from the keyword.
731   o Parameters are specified by a keyword, followed by a colon.  Arguments
732     are separated by white space.
733   o The first parameter must be "Key-Type", control statements
734     may be placed anywhere.
735   o Key generation takes place when either the end of the parameter file
736     is reached, the next "Key-Type" parameter is encountered or at the
737     control statement "%commit"
738   o Control statements:
739     %echo <text>
740         Print <text>.
741     %dry-run
742         Suppress actual key generation (useful for syntax checking).
743     %commit
744         Perform the key generation.  An implicit commit is done
745         at the next "Key-Type" parameter.
746     %pubring <filename>
747     %secring <filename>
748         Do not write the key to the default or commandline given
749         keyring but to <filename>.  This must be given before the first
750         commit to take place, duplicate specification of the same filename
751         is ignored, the last filename before a commit is used.
752         The filename is used until a new filename is used (at commit points)
753         and all keys are written to that file.  If a new filename is given,
754         this file is created (and overwrites an existing one).
755         Both control statements must be given.
756    o The order of the parameters does not matter except for "Key-Type"
757      which must be the first parameter.  The parameters are only for the
758      generated keyblock and parameters from previous key generations are not
759      used. Some syntactically checks may be performed.
760      The currently defined parameters are:
761      Key-Type: <algo-number>|<algo-string>
762         Starts a new parameter block by giving the type of the
763         primary key. The algorithm must be capable of signing.
764         This is a required parameter.
765      Key-Length: <length-in-bits>
766         Length of the key in bits.  Default is 1024.
767      Key-Usage: <usage-list>
768         Space or comma delimited list of key usage, allowed values are
769         "encrypt", "sign", and "auth".  This is used to generate the
770         key flags.  Please make sure that the algorithm is capable of
771         this usage.  Note that OpenPGP requires that all primary keys
772         are capable of certification, so no matter what usage is given
773         here, the "cert" flag will be on.  If no Key-Usage is
774         specified, all the allowed usages for that particular
775         algorithm are used.
776      Subkey-Type: <algo-number>|<algo-string>
777         This generates a secondary key.  Currently only one subkey
778         can be handled.
779      Subkey-Length: <length-in-bits>
780         Length of the subkey in bits.  Default is 1024.
781      Subkey-Usage: <usage-list>
782         Similar to Key-Usage.
783      Passphrase: <string>
784         If you want to specify a passphrase for the secret key,
785         enter it here.  Default is not to use any passphrase.
786      Name-Real: <string>
787      Name-Comment: <string>
788      Name-Email: <string>
789         The 3 parts of a key. Remember to use UTF-8 here.
790         If you don't give any of them, no user ID is created.
791      Expire-Date: <iso-date>|(<number>[d|w|m|y])
792         Set the expiration date for the key (and the subkey).  It
793         may either be entered in ISO date format (2000-08-15) or as
794         number of days, weeks, month or years. Without a letter days
795         are assumed.
796      Preferences: <string>
797         Set the cipher, hash, and compression preference values for
798         this key.  This expects the same type of string as "setpref"
799         in the --edit menu.
800      Revoker: <algo>:<fpr> [sensitive]
801         Add a designated revoker to the generated key.  Algo is the
802         public key algorithm of the designated revoker (i.e. RSA=1,
803         DSA=17, etc.)  Fpr is the fingerprint of the designated
804         revoker.  The optional "sensitive" flag marks the designated
805         revoker as sensitive information.  Only v4 keys may be
806         designated revokers.
807      Handle: <string>
808         This is an optional parameter only used with the status lines
809         KEY_CREATED and KEY_NOT_CREATED.  STRING may be up to 100
810         characters and should not contain spaces.  It is useful for
811         batch key generation to associate a key parameter block with a
812         status line.
813      Keyserver: <string>
814         This is an optional parameter that specifies the preferred
815         keyserver URL for the key.
816
817
818 Here is an example:
819 $ cat >foo <<EOF
820      %echo Generating a standard key
821      Key-Type: DSA
822      Key-Length: 1024
823      Subkey-Type: ELG-E
824      Subkey-Length: 1024
825      Name-Real: Joe Tester
826      Name-Comment: with stupid passphrase
827      Name-Email: joe@foo.bar
828      Expire-Date: 0
829      Passphrase: abc
830      %pubring foo.pub
831      %secring foo.sec
832      # Do a commit here, so that we can later print "done" :-)
833      %commit
834      %echo done
835 EOF
836 $ gpg --batch --gen-key foo
837  [...]
838 $ gpg --no-default-keyring --secret-keyring ./foo.sec \
839                                   --keyring ./foo.pub --list-secret-keys
840 /home/wk/work/gnupg-stable/scratch/foo.sec
841 ------------------------------------------
842 sec  1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@foo.bar>
843 ssb  1024g/8F70E2C0 2000-03-09
844
845
846
847 Layout of the TrustDB
848 =====================
849 The TrustDB is built from fixed length records, where the first byte
850 describes the record type.  All numeric values are stored in network
851 byte order. The length of each record is 40 bytes. The first record of
852 the DB is always of type 1 and this is the only record of this type.
853
854 FIXME:  The layout changed, document it here.
855
856   Record type 0:
857   --------------
858     Unused record, can be reused for any purpose.
859
860   Record type 1:
861   --------------
862     Version information for this TrustDB.  This is always the first
863     record of the DB and the only one with type 1.
864      1 byte value 1
865      3 bytes 'gpg'  magic value
866      1 byte Version of the TrustDB (2)
867      1 byte marginals needed
868      1 byte completes needed
869      1 byte max_cert_depth
870             The three items are used to check whether the cached
871             validity value from the dir record can be used.
872      1 u32  locked flags [not used]
873      1 u32  timestamp of trustdb creation
874      1 u32  timestamp of last modification which may affect the validity
875             of keys in the trustdb.  This value is checked against the
876             validity timestamp in the dir records.
877      1 u32  timestamp of last validation [currently not used]
878             (Used to keep track of the time, when this TrustDB was checked
879              against the pubring)
880      1 u32  record number of keyhashtable [currently not used]
881      1 u32  first free record
882      1 u32  record number of shadow directory hash table [currently not used]
883             It does not make sense to combine this table with the key table
884             because the keyid is not in every case a part of the fingerprint.
885      1 u32  record number of the trusthashtbale
886
887
888   Record type 2: (directory record)
889   --------------
890     Informations about a public key certificate.
891     These are static values which are never changed without user interaction.
892
893      1 byte value 2
894      1 byte  reserved
895      1 u32   LID     .  (This is simply the record number of this record.)
896      1 u32   List of key-records (the first one is the primary key)
897      1 u32   List of uid-records
898      1 u32   cache record
899      1 byte  ownertrust
900      1 byte  dirflag
901      1 byte  maximum validity of all the user ids
902      1 u32   time of last validity check.
903      1 u32   Must check when this time has been reached.
904              (0 = no check required)
905
906
907   Record type 3:  (key record)
908   --------------
909     Informations about a primary public key.
910     (This is mainly used to lookup a trust record)
911
912      1 byte value 3
913      1 byte  reserved
914      1 u32   LID
915      1 u32   next   - next key record
916      7 bytes reserved
917      1 byte  keyflags
918      1 byte  pubkey algorithm
919      1 byte  length of the fingerprint (in bytes)
920      20 bytes fingerprint of the public key
921               (This is the value we use to identify a key)
922
923   Record type 4: (uid record)
924   --------------
925     Informations about a userid
926     We do not store the userid but the hash value of the userid because that
927     is sufficient.
928
929      1 byte value 4
930      1 byte reserved
931      1 u32  LID  points to the directory record.
932      1 u32  next   next userid
933      1 u32  pointer to preference record
934      1 u32  siglist  list of valid signatures
935      1 byte uidflags
936      1 byte validity of the key calculated over this user id
937      20 bytes ripemd160 hash of the username.
938
939
940   Record type 5: (pref record)
941   --------------
942     This record type is not anymore used.
943
944      1 byte value 5
945      1 byte   reserved
946      1 u32  LID; points to the directory record (and not to the uid record!).
947             (or 0 for standard preference record)
948      1 u32  next
949      30 byte preference data
950
951   Record type 6  (sigrec)
952   -------------
953     Used to keep track of key signatures. Self-signatures are not
954     stored.  If a public key is not in the DB, the signature points to
955     a shadow dir record, which in turn has a list of records which
956     might be interested in this key (and the signature record here
957     is one).
958
959      1 byte   value 6
960      1 byte   reserved
961      1 u32    LID           points back to the dir record
962      1 u32    next   next sigrec of this uid or 0 to indicate the
963                      last sigrec.
964      6 times
965         1 u32  Local_id of signatures dir or shadow dir record
966         1 byte Flag: Bit 0 = checked: Bit 1 is valid (we have a real
967                              directory record for this)
968                          1 = valid is set (but may be revoked)
969
970
971
972   Record type 8: (shadow directory record)
973   --------------
974     This record is used to reserve a LID for a public key.  We
975     need this to create the sig records of other keys, even if we
976     do not yet have the public key of the signature.
977     This record (the record number to be more precise) will be reused
978     as the dir record when we import the real public key.
979
980      1 byte value 8
981      1 byte  reserved
982      1 u32   LID      (This is simply the record number of this record.)
983      2 u32   keyid
984      1 byte  pubkey algorithm
985      3 byte reserved
986      1 u32   hintlist   A list of records which have references to
987                         this key.  This is used for fast access to
988                         signature records which are not yet checked.
989                         Note, that this is only a hint and the actual records
990                         may not anymore hold signature records for that key
991                         but that the code cares about this.
992     18 byte reserved
993
994
995
996   Record Type 10 (hash table)
997   --------------
998     Due to the fact that we use fingerprints to lookup keys, we can
999     implement quick access by some simple hash methods, and avoid
1000     the overhead of gdbm.  A property of fingerprints is that they can be
1001     used directly as hash values.  (They can be considered as strong
1002     random numbers.)
1003       What we use is a dynamic multilevel architecture, which combines
1004     hashtables, record lists, and linked lists.
1005
1006     This record is a hashtable of 256 entries; a special property
1007     is that all these records are stored consecutively to make one
1008     big table. The hash value is simple the 1st, 2nd, ... byte of
1009     the fingerprint (depending on the indirection level).
1010
1011     When used to hash shadow directory records, a different table is used
1012     and indexed by the keyid.
1013
1014      1 byte value 10
1015      1 byte reserved
1016      n u32  recnum; n depends on the record length:
1017             n = (reclen-2)/4  which yields 9 for the current record length
1018             of 40 bytes.
1019
1020     the total number of such record which makes up the table is:
1021          m = (256+n-1) / n
1022     which is 29 for a record length of 40.
1023
1024     To look up a key we use the first byte of the fingerprint to get
1025     the recnum from this hashtable and look up the addressed record:
1026        - If this record is another hashtable, we use 2nd byte
1027          to index this hash table and so on.
1028        - if this record is a hashlist, we walk all entries
1029          until we found one a matching one.
1030        - if this record is a key record, we compare the
1031          fingerprint and to decide whether it is the requested key;
1032
1033
1034   Record type 11 (hash list)
1035   --------------
1036     see hash table for an explanation.
1037     This is also used for other purposes.
1038
1039     1 byte value 11
1040     1 byte reserved
1041     1 u32  next          next hash list record
1042     n times              n = (reclen-5)/5
1043         1 u32  recnum
1044
1045     For the current record length of 40, n is 7
1046
1047
1048
1049   Record type 254 (free record)
1050   ---------------
1051     All these records form a linked list of unused records.
1052      1 byte  value 254
1053      1 byte  reserved (0)
1054      1 u32   next_free
1055
1056
1057
1058 Packet Headers
1059 ===============
1060
1061 GNUPG uses PGP 2 packet headers and also understands OpenPGP packet header.
1062 There is one enhancement used with the old style packet headers:
1063
1064    CTB bits 10, the "packet-length length bits", have values listed in
1065    the following table:
1066
1067       00 - 1-byte packet-length field
1068       01 - 2-byte packet-length field
1069       10 - 4-byte packet-length field
1070       11 - no packet length supplied, unknown packet length
1071
1072    As indicated in this table, depending on the packet-length length
1073    bits, the remaining 1, 2, 4, or 0 bytes of the packet structure field
1074    are a "packet-length field".  The packet-length field is a whole
1075    number field.  The value of the packet-length field is defined to be
1076    the value of the whole number field.
1077
1078    A value of 11 is currently used in one place: on compressed data.
1079    That is, a compressed data block currently looks like <A3 01 . .  .>,
1080    where <A3>, binary 10 1000 11, is an indefinite-length packet. The
1081    proper interpretation is "until the end of the enclosing structure",
1082    although it should never appear outermost (where the enclosing
1083    structure is a file).
1084
1085 +  This will be changed with another version, where the new meaning of
1086 +  the value 11 (see below) will also take place.
1087 +
1088 +  A value of 11 for other packets enables a special length encoding,
1089 +  which is used in case, where the length of the following packet can
1090 +  not be determined prior to writing the packet; especially this will
1091 +  be used if large amounts of data are processed in filter mode.
1092 +
1093 +  It works like this: After the CTB (with a length field of 11) a
1094 +  marker field is used, which gives the length of the following datablock.
1095 +  This is a simple 2 byte field (MSB first) containing the amount of data
1096 +  following this field, not including this length field. After this datablock
1097 +  another length field follows, which gives the size of the next datablock.
1098 +  A value of 0 indicates the end of the packet. The maximum size of a
1099 +  data block is limited to 65534, thereby reserving a value of 0xffff for
1100 +  future extensions. These length markers must be inserted into the data
1101 +  stream just before writing the data out.
1102 +
1103 +  This 2 byte field is large enough, because the application must buffer
1104 +  this amount of data to prepend the length marker before writing it out.
1105 +  Data block sizes larger than about 32k doesn't make any sense. Note
1106 +  that this may also be used for compressed data streams, but we must use
1107 +  another packet version to tell the application that it can not assume,
1108 +  that this is the last packet.
1109
1110
1111 GNU extensions to the S2K algorithm
1112 ===================================
1113 S2K mode 101 is used to identify these extensions.
1114 After the hash algorithm the 3 bytes "GNU" are used to make
1115 clear that these are extensions for GNU, the next bytes gives the
1116 GNU protection mode - 1000.  Defined modes are:
1117   1001 - do not store the secret part at all
1118   1002 - a stub to access smartcards (not used in 1.2.x)
1119
1120
1121 Pipemode
1122 ========
1123 NOTE:  This is deprecated and will be removed in future versions.
1124
1125 This mode can be used to perform multiple operations with one call to
1126 gpg. It comes handy in cases where you have to verify a lot of
1127 signatures. Currently we support only detached signatures.  This mode
1128 is a kludge to avoid running gpg n daemon mode and using Unix Domain
1129 Sockets to pass the data to it.  There is no easy portable way to do
1130 this under Windows, so we use plain old pipes which do work well under
1131 Windows.  Because there is no way to signal multiple EOFs in a pipe we
1132 have to embed control commands in the data stream: We distinguish
1133 between a data state and a control state.  Initially the system is in
1134 data state but it won't accept any data.  Instead it waits for
1135 transition to control state which is done by sending a single '@'
1136 character.  While in control state the control command os expected and
1137 this command is just a single byte after which the system falls back
1138 to data state (but does not necesary accept data now).  The simplest
1139 control command is a '@' which just inserts this character into the
1140 data stream.
1141
1142 Here is the format we use for detached signatures:
1143 "@<"  - Begin of new stream
1144 "@B"  - Detached signature follows.
1145         This emits a control packet (1,'B')
1146 <detached_signature>
1147 "@t"  - Signed text follows. 
1148         This emits the control packet (2, 'B')
1149 <signed_text>
1150 "@."  - End of operation. The final control packet forces signature
1151         verification
1152 "@>"  - End of stream   
1153
1154
1155
1156
1157
1158
1159 Other Notes
1160 ===========
1161     * For packet version 3 we calculate the keyids this way:
1162         RSA     := low 64 bits of n
1163         ELGAMAL := build a v3 pubkey packet (with CTB 0x99) and calculate
1164                    a rmd160 hash value from it. This is used as the
1165                    fingerprint and the low 64 bits are the keyid.
1166
1167     * Revocation certificates consist only of the signature packet;
1168       "import" knows how to handle this.  The rationale behind it is
1169       to keep them small.
1170
1171
1172
1173
1174
1175
1176
1177 Keyserver Message Format
1178 =========================
1179
1180 The keyserver may be contacted by a Unix Domain socket or via TCP.
1181
1182 The format of a request is:
1183
1184 ====
1185 command-tag
1186 "Content-length:" digits
1187 CRLF
1188 =======
1189
1190 Where command-tag is
1191
1192 NOOP
1193 GET <user-name>
1194 PUT
1195 DELETE <user-name>
1196
1197
1198 The format of a response is:
1199
1200 ======
1201 "GNUPG/1.0" status-code status-text
1202 "Content-length:" digits
1203 CRLF
1204 ============
1205 followed by <digits> bytes of data
1206
1207
1208 Status codes are:
1209
1210      o  1xx: Informational - Request received, continuing process
1211
1212      o  2xx: Success - The action was successfully received, understood,
1213         and accepted
1214
1215      o  4xx: Client Error - The request contains bad syntax or cannot be
1216         fulfilled
1217
1218      o  5xx: Server Error - The server failed to fulfill an apparently
1219         valid request
1220
1221
1222
1223 Documentation on HKP (the http keyserver protocol):
1224
1225 A minimalistic HTTP server on port 11371 recognizes a GET for /pks/lookup.
1226 The standard http URL encoded query parameters are this (always key=value):
1227
1228 - op=index (like pgp -kv), op=vindex (like pgp -kvv) and op=get (like
1229   pgp -kxa)
1230
1231 - search=<stringlist>. This is a list of words that must occur in the key.
1232   The words are delimited with space, points, @ and so on. The delimiters
1233   are not searched for and the order of the words doesn't matter (but see
1234   next option).
1235
1236 - exact=on. This switch tells the hkp server to only report exact matching
1237   keys back. In this case the order and the "delimiters" are important.
1238
1239 - fingerprint=on. Also reports the fingerprints when used with 'index' or
1240   'vindex'
1241
1242 The keyserver also recognizes http-POSTs to /pks/add. Use this to upload
1243 keys.
1244
1245
1246 A better way to do this would be a request like:
1247
1248    /pks/lookup/<gnupg_formatierte_user_id>?op=<operation>
1249
1250 This can be implemented using Hurd's translator mechanism.
1251 However, I think the whole key server stuff has to be re-thought;
1252 I have some ideas and probably create a white paper.
1253