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