gpg: First take on PKT_ENCRYPTED_AEAD.
[gnupg.git] / doc / DETAILS
index a52f51c..a4063b4 100644 (file)
@@ -15,6 +15,7 @@ This is the DETAILS file for GnuPG which specifies some internals and
 parts of the external API for GPG and GPGSM.
 
 * Format of the colon listings
+
   The format is a based on colon separated record, each recods starts
   with a tag string and extends to the end of the line.  Here is an
   example:
@@ -31,11 +32,20 @@ sub:r:1536:20:5CE086B5B5A18FF4:899817788:1025961788:::::esc:
 fpr:::::::::AB059359A3B81F410FCFF97F5CE086B5B5A18FF4:
 #+end_example
 
+Note that new version of GnuPG or the use of certain options may add
+new fields to the output.  Parsers should not assume a limit on the
+number of fields per line.  Some fields are not yet used or only used
+with certain record types; parsers should ignore fields they are not
+aware of.  New versions of GnuPG or the use of certain options may add
+new types of records as well.  Parsers should ignore any record whose
+type they do not recognize for forward-compatibility.
+
 The double =--with-fingerprint= prints the fingerprint for the subkeys
-too.  Old versions of gpg used a slighrly different format and required
+too.  Old versions of gpg used a slightly different format and required
 the use of the option =--fixed-list-mode= to conform to the format
 described here.
 
+
 ** Description of the fields
 *** Field 1 - Type of record
 
@@ -45,7 +55,7 @@ described here.
     - sub :: Subkey (secondary key)
     - sec :: Secret key
     - ssb :: Secret subkey (secondary key)
-    - uid :: User id (only field 10 is used).
+    - uid :: User id
     - uat :: User attribute (same as user id except for field 10).
     - sig :: Signature
     - rev :: Revocation signature
@@ -53,6 +63,7 @@ described here.
     - pkd :: Public key data [*]
     - grp :: Keygrip
     - rvk :: Revocation key
+    - tfs :: TOFU statistics [*]
     - tru :: Trust database information [*]
     - spk :: Signature subpacket [*]
     - cfg :: Configuration data [*]
@@ -83,7 +94,7 @@ described here.
            ultimately valid.
     - w :: The key has a well known private part.
     - s :: The key has special validity.  This means that it might be
-           self-signed and expected to be used in the STEED sytem.
+           self-signed and expected to be used in the STEED system.
 
     If the validity information is given for a UID or UAT record, it
     describes the validity calculated based on this user ID.  If given
@@ -112,7 +123,7 @@ described here.
 
     The creation date of the key is given in UTC.  For UID and UAT
     records, this is used for the self-signature date.  Note that the
-    date is usally printed in seconds since epoch, however, we are
+    date is usually printed in seconds since epoch, however, we are
     migrating to an ISO 8601 format (e.g. "19660205T091500").  This is
     currently only relevant for X.509.  A simple way to detect the new
     format is to scan for the 'T'.  Note that old versions of gpg
@@ -128,7 +139,7 @@ described here.
     Used for serial number in crt records.  For UID and UAT records,
     this is a hash of the user ID contents used to represent that
     exact user ID.  For trust signatures, this is the trust depth
-    seperated by the trust value by a space.
+    separated by the trust value by a space.
 
 *** Field 9 -  Ownertrust
 
@@ -138,6 +149,7 @@ described here.
     the regular expression value, quoted as in field 10.
 
 *** Field 10 - User-ID
+
     The value is quoted like a C string to avoid control characters
     (the colon is quoted =\x3a=).  For a "pub" record this field is
     not used on --fixed-list-mode.  A UAT record puts the attribute
@@ -145,6 +157,7 @@ described here.
     subpacket size.  In gpgsm the issuer name comes here.  A FPR
     record stores the fingerprint here.  The fingerprint of a
     revocation key is stored here.
+
 *** Field 11 - Signature class
 
     Signature class as per RFC-4880.  This is a 2 digit hexnumber
@@ -176,7 +189,7 @@ described here.
     only filled if the issuer certificate is available. The root has
     been reached if this is the same string as the fingerprint. The
     advantage of using this value is that it is guaranteed to have
-    been been build by the same lookup algorithm as gpgsm uses.
+    been built by the same lookup algorithm as gpgsm uses.
 
     For "uid" records this field lists the preferences in the same way
     gpg's --edit-key menu does.
@@ -192,9 +205,10 @@ described here.
 
 *** Field 15 - S/N of a token
 
-    Used in sec/sbb to print the serial number of a token (internal
+    Used in sec/ssb to print the serial number of a token (internal
     protect mode 1002) or a '#' if that key is a simple stub (internal
-    protect mode 1001)
+    protect mode 1001).  If the option --with-secret is used and a
+    secret key is available for the public key, a '+' indicates this.
 
 *** Field 16 - Hash algorithm
 
@@ -203,9 +217,34 @@ described here.
 
 *** Field 17 - Curve name
 
-    For pub, sub, sec, and sbb records this field is used for the ECC
+    For pub, sub, sec, and ssb records this field is used for the ECC
     curve name.
 
+*** Field 18 - Compliance flags
+
+    Space separated list of asserted compliance modes and
+    screening result for this key.
+
+    Valid values are:
+
+    - 8  :: The key is compliant with RFC4880bis
+    - 23 :: The key is compliant with compliance mode "de-vs".
+    - 6001 :: Screening hit on the ROCA vulnerability.
+
+*** Field 19 - Last update
+
+    The timestamp of the last update of a key or user ID.  The update
+    time of a key is defined a lookup of the key via its unique
+    identifier (fingerprint); the field is empty if not known.  The
+    update time of a user ID is defined by a lookup of the key using a
+    trusted mapping from mail address to key.
+
+*** Field 20 - Origin
+
+    The origin of the key or the user ID.  This is an integer
+    optionally followed by a space and an URL.  This goes along with
+    the previous field.  The URL is quoted in C style.
+
 ** Special fields
 
 *** PKD - Public key data
@@ -218,6 +257,22 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     !--------- index (eg. DSA goes from 0 to 3: p,q,g,y)
 #+end_example
 
+*** TFS - TOFU statistics
+
+    This field may follows a UID record to convey information about
+    the TOFU database.  The information is similar to a TOFU_STATS
+    status line.
+
+    - Field 2 :: tfs record version (must be 1)
+    - Field 3 :: validity -  A number with validity code.
+    - Field 4 :: signcount - The number of signatures seen.
+    - Field 5 :: encrcount - The number of encryptions done.
+    - Field 6 :: policy - A string with the policy
+    - Field 7 :: signture-first-seen - a timestamp or 0 if not known.
+    - Field 8 :: signature-most-recent-seen - a timestamp or 0 if not known.
+    - Field 9 :: encryption-first-done - a timestamp or 0 if not known.
+    - Field 10 :: encryption-most-recent-done - a timestamp or 0 if not known.
+
 *** TRU - Trust database information
     Example for a "tru" trust base record:
 #+begin_example
@@ -286,19 +341,22 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
                 semicolons.  The algorithm numbers are as specified in
                 RFC-4880.  Note that in contrast to the --status-fd
                 interface these are _not_ the Libgcrypt identifiers.
+                Using =pubkeyname= prints names instead of numbers.
 
                  : cfg:pubkey:1;2;3;16;17
 
     - cipher :: The third field contains the symmetric ciphers this
                 version of GnuPG supports, separated by semicolons.
                 The cipher numbers are as specified in RFC-4880.
+                Using =ciphername= prints names instead of numbers.
 
                  : cfg:cipher:2;3;4;7;8;9;10
 
     - digest :: The third field contains the digest (hash) algorithms
                 this version of GnuPG supports, separated by
                 semicolons.  The digest numbers are as specified in
-                RFC-4880.
+                RFC-4880.  Using =digestname= prints names instead of
+                numbers.
 
                  : cfg:digest:1;2;3;8;9;10
 
@@ -318,19 +376,28 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
                would result in:
                  : cfg:group:mynames:patti;joe;0x12345678;paige
 
+    - curve :: The third field contains the curve names this version
+               of GnuPG supports, separated by semicolons. Using
+               =curveoid= prints OIDs instead of numbers.
+
+                 : cfg:curve:ed25519;nistp256;nistp384;nistp521
+
 
 * Format of the --status-fd output
 
   Every line is prefixed with "[GNUPG:] ", followed by a keyword with
   the type of the status line and some arguments depending on the type
-  (maybe none); an application should always be prepared to see more
-  arguments in future versions.
+  (maybe none); an application should always be willing to ignore
+  unknown keywords that may be emitted by future versions of GnuPG.
+  Also, new versions of GnuPG may add arguments to existing keywords.
+  Any additional arguments should be ignored for forward-compatibility.
 
 ** General status codes
-*** NEWSIG
-    May be issued right before a signature verification starts.  This
-    is useful to define a context for parsing ERROR status messages.
-    No arguments are currently defined.
+*** NEWSIG [<signers_uid>]
+    Is issued right before a signature verification starts.  This is
+    useful to define a context for parsing ERROR status messages.
+    If SIGNERS_UID is given and is not "-" this is the percent-escaped
+    value of the OpenPGP Signer's User ID signature sub-packet.
 
 *** GOODSIG  <long_keyid_or_fpr>  <username>
     The signature with the keyid is good.  For each signature only one
@@ -380,8 +447,8 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     gpgsm and might eventually also be available for OpenPGP.
 
     Note, that TIME may either be the number of seconds since Epoch or
-    the letter 'T'.
     an ISO 8601 string.  The latter can be detected by the presence of
+    the letter 'T'.
 
 *** VALIDSIG <args>
 
@@ -398,12 +465,15 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     - <sig-class>
     - [ <primary-key-fpr> ]
 
-    This status indicates that the signature is good. This is the same
-    as GOODSIG but has the fingerprint as the argument. Both status
-    lines are emitted for a good signature.  All arguments here are on
-    one long line.  sig-timestamp is the signature creation time in
-    seconds after the epoch. expire-timestamp is the signature
-    expiration time in seconds after the epoch (zero means "does not
+    This status indicates that the signature is cryptographically
+    valid. This is similar to GOODSIG, EXPSIG, EXPKEYSIG, or REVKEYSIG
+    (depending on the date and the state of the signature and signing
+    key) but has the fingerprint as the argument. Multiple status
+    lines (VALIDSIG and the other appropriate *SIG status) are emitted
+    for a valid signature.  All arguments here are on one long line.
+    sig-timestamp is the signature creation time in seconds after the
+    epoch. expire-timestamp is the signature expiration time in
+    seconds after the epoch (zero means "does not
     expire"). sig-version, pubkey-algo, hash-algo, and sig-class (a
     2-byte hex value) are all straight from the signature packet.
     PRIMARY-KEY-FPR is the fingerprint of the primary key or identical
@@ -411,8 +481,8 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     key without running gpg again for this purpose.
 
     The primary-key-fpr parameter is used for OpenPGP and not
-    class is not defined for CMS and currently set to 0 and 00.
     available for CMS signatures.  The sig-version as well as the sig
+    class is not defined for CMS and currently set to 0 and 00.
 
     Note, that *-TIMESTAMP may either be a number of seconds since
     Epoch or an ISO 8601 string which can be detected by the presence
@@ -442,9 +512,16 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
 *** END_DECRYPTION
     Mark the end of the actual decryption process.  This are also
     emitted when in --list-only mode.
-*** DECRYPTION_INFO <mdc_method> <sym_algo>
+*** DECRYPTION_KEY <fpr> <fpr2> <otrust>
+    This line is emitted when a public key decryption succeeded in
+    providing a session key.  <fpr> is the hexified fingerprint of the
+    actual key used for descryption.  <fpr2> is the fingerprint of the
+    primary key.  <otrust> is the letter with the ownertrust; this is
+    in general a 'u' which stands for ultimately trusted.
+*** DECRYPTION_INFO <mdc_method> <sym_algo> [<aead_algo>]
     Print information about the symmetric encryption algorithm and the
     MDC method.  This will be emitted even if the decryption fails.
+    For an AEAD algorithm AEAD_ALGO is not 0.
 
 *** DECRYPTION_FAILED
     The symmetric decryption failed - one reason could be a wrong
@@ -453,18 +530,21 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
 *** DECRYPTION_OKAY
     The decryption process succeeded.  This means, that either the
     correct secret key has been used or the correct passphrase for a
-    conventional encrypted message was given.  The program itself may
+    symmetric encrypted message was given.  The program itself may
     return an errorcode because it may not be possible to verify a
     signature for some reasons.
 
 *** SESSION_KEY <algo>:<hexdigits>
     The session key used to decrypt the message.  This message will
-    only be emitted when the special option --show-session-key is
-    used.  The format is suitable to be passed to the option
-    --override-session-key
+    only be emitted if the option --show-session-key is used.  The
+    format is suitable to be passed as value for the option
+    --override-session-key.  It is not an indication that the
+    decryption will or has succeeded.
 
-*** BEGIN_ENCRYPTION  <mdc_method> <sym_algo>
+*** BEGIN_ENCRYPTION  <mdc_method> <sym_algo> [<aead_algo>]
     Mark the start of the actual encryption process.
+    MDC_METHOD shall be 0 if an AEAD_ALGO is not 0.  Users should
+    however ignore MDC_METHOD if AEAD_ALGO is not 0.
 
 *** END_ENCRYPTION
     Mark the end of the actual encryption process.
@@ -502,14 +582,17 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     letter 'T'.
 
 *** NOTATION_
-    There are actually two related status codes to convey notation
+    There are actually three related status codes to convey notation
     data:
 
     - NOTATION_NAME <name>
+    - NOTATION_FLAGS <critical> <human_readable>
     - NOTATION_DATA <string>
 
-    <name> and <string> are %XX escaped; the data may be split among
-    several NOTATION_DATA lines.
+    <name> and <string> are %XX escaped.  The data may be split among
+    several NOTATION_DATA lines.  NOTATION_FLAGS is emitted after
+    NOTATION_NAME and gives the critical and human readable flags;
+    the flag values are either 0 or 1.
 
 *** POLICY_URL <string>
     Note that URL in <string> is %XX escaped.
@@ -530,7 +613,7 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     that case, this status tag does not appear.
 
 *** ATTRIBUTE <arguments>
-    The list or argemnts are:
+    The list or arguments are:
     - <fpr>
     - <octets>
     - <type>
@@ -558,6 +641,23 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     This indicates that a signature subpacket was seen.  The format is
     the same as the "spk" record above.
 
+*** ENCRYPTION_COMPLIANCE_MODE <flags>
+    Indicates that the current encryption operation was in compliance
+    with the given set of modes for all recipients.  "flags" is a
+    space separated list of numerical flags, see "Field 18 -
+    Compliance flags" above.
+
+*** DECRYPTION_COMPLIANCE_MODE <flags>
+    Indicates that the current decryption operation is in compliance
+    with the given set of modes.  "flags" is a space separated list of
+    numerical flags, see "Field 18 - Compliance flags" above.
+
+*** VERIFICATION_COMPLIANCE_MODE <flags>
+    Indicates that the current signature verification operation is in
+    compliance with the given set of modes.  "flags" is a space
+    separated list of numerical flags, see "Field 18 - Compliance
+    flags" above.
+
 ** Key related
 *** INV_RECP, INV_SGNR
     The two similar status codes:
@@ -581,6 +681,11 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
        - 10 :: Key not trusted
        - 11 :: Missing certificate
        - 12 :: Missing issuer certificate
+       - 13 :: Key disabled
+       - 14 :: Syntax error in specification
+
+    If no specific reason was given a previously emitted status code
+    KEY_CONSIDERED may be used to analyzed the problem.
 
     Note that for historical reasons the INV_RECP status is also used
     for gpgsm's SIGNER command where it relates to signer's of course.
@@ -588,12 +693,20 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     ignore the INV_RECP during the sender's command processing once
     they have seen an INV_SGNR.  Different codes are used so that they
     can be distinguish while doing an encrypt+sign operation.
+
 *** NO_RECP <reserved>
     Issued if no recipients are usable.
 
 *** NO_SGNR <reserved>
     Issued if no senders are usable.
 
+*** KEY_CONSIDERED <fpr> <flags>
+    Issued to explian the lookup of a key.  FPR is the hexified
+    fingerprint of the primary key.  The bit values for FLAGS are:
+
+    - 1 :: The key has not been selected.
+    - 2 :: All subkeys of the key are expired or have been revoked.
+
 *** KEYEXPIRED <expire-timestamp>
     The key has expired.  expire-timestamp is the expiration time in
     seconds since Epoch.  This status line is not very useful because
@@ -641,22 +754,104 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
 
     VALIDATION_MODEL describes the algorithm used to check the
     validity of the key.  The defaults are the standard Web of Trust
-    model for gpg and the the standard X.509 model for gpgsm.  The
+    model for gpg and the standard X.509 model for gpgsm.  The
     defined values are
 
        - pgp   :: The standard PGP WoT.
        - shell :: The standard X.509 model.
        - chain :: The chain model.
        - steed :: The STEED model.
+       - tofu  :: The TOFU model
 
     Note that the term =TRUST_= in the status names is used for
     historic reasons; we now speak of validity.
 
+*** TOFU_USER <fingerprint_in_hex> <mbox>
+
+    This status identifies the key and the userid for all following
+    Tofu information.  The fingerprint is the fingerprint of the
+    primary key and the mbox is in general the addr-spec part of the
+    userid encoded in UTF-8 and percent escaped.  The fingerprint is
+    identical for all TOFU_USER lines up to a NEWSIG line.
+
+*** TOFU_STATS <MANY_ARGS>
+
+    Statistics for the current user id.
+
+    The <MANY_ARGS> are the usual space delimited arguments.  Here we
+    have too many of them to fit on one printed line and thus they are
+    given on 3 printed lines:
+
+    : <summary> <sign-count> <encryption-count>
+    : [<policy> [<tm1> <tm2> <tm3> <tm4>
+    : [<validity> [<sign-days> <encrypt-days>]]]]
+
+    Values for SUMMARY are:
+    - 0 :: attention, an interaction with the user is required (conflict)
+    - 1 :: key with no verification/encryption history
+    - 2 :: key with little history
+    - 3 :: key with enough history for basic trust
+    - 4 :: key with a lot of history
+
+    Values for POLICY are:
+    - none    :: No Policy set
+    - auto    :: Policy is "auto"
+    - good    :: Policy is "good"
+    - bad     :: Policy is "bad"
+    - ask     :: Policy is "ask"
+    - unknown :: Policy is "unknown" (TOFU information does not
+                 contribute to the key's validity)
+
+    TM1 is the time the first message was verified.  TM2 is the time
+    the most recent message was verified.  TM3 is the time the first
+    message was encrypted.  TM4 is the most recent encryption. All may
+    either be seconds since Epoch or an ISO time string
+    (yyyymmddThhmmss).
+
+    VALIDITY is the same as SUMMARY with the exception that VALIDITY
+    doesn't reflect whether the key needs attention.  That is it never
+    takes on value 0.  Instead, if there is a conflict, VALIDITY still
+    reflects the key's validity (values: 1-4).
+
+    SUMMARY values use the euclidean distance (m = sqrt(a² + b²)) rather
+    then the sum of the magnitudes (m = a + b) to ensure a balance between
+    verified signatures and encrypted messages.
+
+    Values are calculated based on the number of days where a key was used
+    for verifying a signature or to encrypt to it.
+    The ranges for the values are:
+
+    - 1 :: signature_days + encryption_days == 0
+    - 2 :: 1 <= sqrt(signature_days² + encryption_days²) < 8
+    - 3 :: 8 <= sqrt(signature_days² + encryption_days²) < 42
+    - 4 :: sqrt(signature_days² + encryption_days²) >= 42
+
+    SIGN-COUNT and ENCRYPTION-COUNT are the number of messages that we
+    have seen that have been signed by this key / encryption to this
+    key.
+
+    SIGN-DAYS and ENCRYPTION-DAYS are similar, but the number of days
+    (in UTC) on which we have seen messages signed by this key /
+    encrypted to this key.
+
+*** TOFU_STATS_SHORT <long_string>
+
+    Information about the TOFU binding for the signature.
+    Example: "15 signatures verified. 10 messages encrypted"
+
+*** TOFU_STATS_LONG <long_string>
+
+    Information about the TOFU binding for the signature in verbose
+    format.  The LONG_STRING is percent escaped.
+    Example: 'Verified 9 messages signed by "Werner Koch
+    (dist sig)" in the past 3 minutes, 40 seconds.  The most
+    recent message was verified 4 seconds ago.'
+
 *** PKA_TRUST_
-    This is is one:
+    This is one of:
 
-    - PKA_TRUST_GOOD <mailbox>
-    - PKA_TRUST_BAD  <mailbox>
+    - PKA_TRUST_GOOD <addr-spec>
+    - PKA_TRUST_BAD  <addr-spec>
 
     Depending on the outcome of the PKA check one of the above status
     codes is emitted in addition to a =TRUST_*= status.
@@ -735,7 +930,7 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     - <count>
     - <no_user_id>
     - <imported>
-    - <imported_rsa>
+    - always 0 (formerly used for the number of RSA keys)
     - <unchanged>
     - <n_uids>
     - <n_subk>
@@ -746,6 +941,22 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     - <sec_dups>
     - <skipped_new_keys>
     - <not_imported>
+    - <skipped_v3_keys>
+
+*** EXPORTED  <fingerprint>
+    The key with <fingerprint> has been exported.  The fingerprint is
+    the fingerprint of the primary key even if the primary key has
+    been replaced by a stub key during secret key export.
+
+*** EXPORT_RES <args>
+
+    Final statistics on export process (this is one long line). The
+    args are a list of unsigned numbers separated by white space:
+
+    - <count>
+    - <secret_count>
+    - <exported>
+
 
 ** Smartcard related
 *** CARDCTRL <what> [<serialno>]
@@ -760,6 +971,7 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
       - 4 :: No card available
       - 5 :: No card reader available
       - 6 :: No card support available
+      - 7 :: Card is in termination state
 
 *** SC_OP_FAILURE [<code>]
     An operation on a smartcard definitely failed.  Currently there is
@@ -803,11 +1015,24 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     should not contain spaces.  The error code is a either a string
     commencing with a letter or such a string prefixed with a
     numerical error code and an underscore; e.g.: "151011327_EOF".
-
+*** WARNING <location> <error code> [<text>]
+    This is a generic warning status message, it might be followed by
+    error location specific data. <error code> and <location>
+    should not contain spaces.  The error code is a either a string
+    commencing with a letter or such a string prefixed with a
+    numerical error code and an underscore; e.g.: "151011327_EOF".
 *** SUCCESS [<location>]
-    Postive confirimation that an operation succeeded.  <location> is
-    optional but if given should not contain spaces.  Used only with a
-    few commands.
+    Positive confirmation that an operation succeeded.  It is used
+    similar to ISO-C's EXIT_SUCCESS.  <location> is optional but if
+    given should not contain spaces.  Used only with a few commands.
+
+*** FAILURE <location> <error_code>
+    This is the counterpart to SUCCESS and used to indicate a program
+    failure.  It is used similar to ISO-C's EXIT_FAILURE but allows
+    conveying more information, in particular a gpg-error error code.
+    That numerical error code may optionally have a suffix made of an
+    underscore and a string with an error symbol like "151011327_EOF".
+    A dash may be used instead of <location>.
 
 *** BADARMOR
     The ASCII armor is corrupted.  No arguments yet.
@@ -817,17 +1042,19 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     - 1 :: No such key
     - 2 :: Must delete secret key first
     - 3 :: Ambigious specification
+    - 4 :: Key is stored on a smartcard.
 
-*** PROGRESS <what> <char> <cur> <total>
-    Used by the primegen and Public key functions to indicate
+*** PROGRESS <what> <char> <cur> <total> [<units>]
+    Used by the primegen and public key functions to indicate
     progress.  <char> is the character displayed with no --status-fd
     enabled, with the linefeed replaced by an 'X'.  <cur> is the
     current amount done and <total> is amount to be done; a <total> of
-    0 indicates that the total amount is not known. The condition
+    0 indicates that the total amount is not known. Both are
+    non-negative integers.  The condition
       :       TOTAL && CUR == TOTAL
     may be used to detect the end of an operation.
 
-    Well known values for WHAT are:
+    Well known values for <what> are:
 
            - pk_dsa   :: DSA key generation
            - pk_elg   :: Elgamal key generation
@@ -842,6 +1069,11 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
                           the data of a smartcard.
            - card_busy :: A smartcard is still working
 
+    When <what> refers to a file path, it may be truncated.
+
+    <units> is sometimes used to describe the units for <current> and
+    <total>.  For example "B", "KiB", or "MiB".
+
 *** BACKUP_KEY_CREATED <fingerprint> <fname>
     A backup of a key identified by <fingerprint> has been writte to
     the file <fname>; <fname> is percent-escaped.
@@ -850,9 +1082,9 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     <name> is a percent-plus escaped filename describing the
     mountpoint for the current operation (e.g. used by "g13 --mount").
     This may either be the specified mountpoint or one randomly
-    choosen by g13.
+    chosen by g13.
 
-*** PINENTRY_LAUNCHED <pid>
+*** PINENTRY_LAUNCHED <pid>[:<extra>]
     This status line is emitted by gpg to notify a client that a
     Pinentry has been launched.  <pid> is the PID of the Pinentry.  It
     may be used to display a hint to the user but can't be used to
@@ -899,234 +1131,252 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
   All other data after this header is raw image (JPEG) data.
 
 
-* Unattended key generation
-
-   Please see the GnuPG manual for a description.
-
-
 * Layout of the TrustDB
 
   The TrustDB is built from fixed length records, where the first byte
   describes the record type.  All numeric values are stored in network
-  byte order. The length of each record is 40 bytes. The first record
-  of the DB is always of type 1 and this is the only record of this
-  type.
-
-  FIXME:  The layout changed, document it here.
-#+begin_example
-  Record type 0:
-  --------------
-    Unused record, can be reused for any purpose.
-
-  Record type 1:
-  --------------
-    Version information for this TrustDB.  This is always the first
-    record of the DB and the only one with type 1.
-     1 byte value 1
-     3 bytes 'gpg'  magic value
-     1 byte Version of the TrustDB (2)
-     1 byte marginals needed
-     1 byte completes needed
-     1 byte max_cert_depth
-           The three items are used to check whether the cached
-           validity value from the dir record can be used.
-     1 u32  locked flags [not used]
-     1 u32  timestamp of trustdb creation
-     1 u32  timestamp of last modification which may affect the validity
-           of keys in the trustdb.  This value is checked against the
-           validity timestamp in the dir records.
-     1 u32  timestamp of last validation [currently not used]
-           (Used to keep track of the time, when this TrustDB was checked
-            against the pubring)
-     1 u32  record number of keyhashtable [currently not used]
-     1 u32  first free record
-     1 u32  record number of shadow directory hash table [currently not used]
-           It does not make sense to combine this table with the key table
-           because the keyid is not in every case a part of the fingerprint.
-     1 u32  record number of the trusthashtbale
-
-
-  Record type 2: (directory record)
-  --------------
-    Informations about a public key certificate.
-    These are static values which are never changed without user interaction.
-
-     1 byte value 2
-     1 byte  reserved
-     1 u32   LID     . (This is simply the record number of this record.)
-     1 u32   List of key-records (the first one is the primary key)
-     1 u32   List of uid-records
-     1 u32   cache record
-     1 byte  ownertrust
-     1 byte  dirflag
-     1 byte  maximum validity of all the user ids
-     1 u32   time of last validity check.
-     1 u32   Must check when this time has been reached.
-            (0 = no check required)
-
-
-  Record type 3:  (key record)
-  --------------
-    Informations about a primary public key.
-    (This is mainly used to lookup a trust record)
-
-     1 byte value 3
-     1 byte  reserved
-     1 u32   LID
-     1 u32   next   - next key record
-     7 bytes reserved
-     1 byte  keyflags
-     1 byte  pubkey algorithm
-     1 byte  length of the fingerprint (in bytes)
-     20 bytes fingerprint of the public key
-             (This is the value we use to identify a key)
-
-  Record type 4: (uid record)
-  --------------
-    Informations about a userid
-    We do not store the userid but the hash value of the userid because that
-    is sufficient.
-
-     1 byte value 4
-     1 byte reserved
-     1 u32  LID  points to the directory record.
-     1 u32  next   next userid
-     1 u32  pointer to preference record
-     1 u32  siglist  list of valid signatures
-     1 byte uidflags
-     1 byte validity of the key calculated over this user id
-     20 bytes ripemd160 hash of the username.
-
-
-  Record type 5: (pref record)
-  --------------
-    This record type is not anymore used.
-
-     1 byte value 5
-     1 byte   reserved
-     1 u32  LID; points to the directory record (and not to the uid record!).
-           (or 0 for standard preference record)
-     1 u32  next
-     30 byte preference data
-
-  Record type 6  (sigrec)
-  -------------
-    Used to keep track of key signatures. Self-signatures are not
-    stored.  If a public key is not in the DB, the signature points to
-    a shadow dir record, which in turn has a list of records which
-    might be interested in this key (and the signature record here
-    is one).
-
-     1 byte   value 6
-     1 byte   reserved
-     1 u32    LID          points back to the dir record
-     1 u32    next   next sigrec of this uid or 0 to indicate the
-                    last sigrec.
-     6 times
-       1 u32  Local_id of signatures dir or shadow dir record
-       1 byte Flag: Bit 0 = checked: Bit 1 is valid (we have a real
-                            directory record for this)
-                        1 = valid is set (but may be revoked)
-
-
-
-  Record type 8: (shadow directory record)
-  --------------
-    This record is used to reserve a LID for a public key.  We
-    need this to create the sig records of other keys, even if we
-    do not yet have the public key of the signature.
-    This record (the record number to be more precise) will be reused
-    as the dir record when we import the real public key.
-
-     1 byte value 8
-     1 byte  reserved
-     1 u32   LID      (This is simply the record number of this record.)
-     2 u32   keyid
-     1 byte  pubkey algorithm
-     3 byte reserved
-     1 u32   hintlist  A list of records which have references to
-                       this key.  This is used for fast access to
-                       signature records which are not yet checked.
-                       Note, that this is only a hint and the actual records
-                       may not anymore hold signature records for that key
-                       but that the code cares about this.
-    18 byte reserved
-
-
-
-  Record Type 10 (hash table)
-  --------------
-    Due to the fact that we use fingerprints to lookup keys, we can
-    implement quick access by some simple hash methods, and avoid
-    the overhead of gdbm.  A property of fingerprints is that they can be
-    used directly as hash values.  (They can be considered as strong
-    random numbers.)
-      What we use is a dynamic multilevel architecture, which combines
-    hashtables, record lists, and linked lists.
-
-    This record is a hashtable of 256 entries; a special property
-    is that all these records are stored consecutively to make one
-    big table. The hash value is simple the 1st, 2nd, ... byte of
-    the fingerprint (depending on the indirection level).
-
-    When used to hash shadow directory records, a different table is used
-    and indexed by the keyid.
-
-     1 byte value 10
-     1 byte reserved
-     n u32  recnum; n depends on the record length:
-           n = (reclen-2)/4  which yields 9 for the current record length
-           of 40 bytes.
-
-    the total number of such record which makes up the table is:
-        m = (256+n-1) / n
-    which is 29 for a record length of 40.
-
-    To look up a key we use the first byte of the fingerprint to get
-    the recnum from this hashtable and look up the addressed record:
-       - If this record is another hashtable, we use 2nd byte
-        to index this hash table and so on.
-       - if this record is a hashlist, we walk all entries
-        until we found one a matching one.
-       - if this record is a key record, we compare the
-        fingerprint and to decide whether it is the requested key;
-
-
-  Record type 11 (hash list)
-  --------------
-    see hash table for an explanation.
-    This is also used for other purposes.
-
-    1 byte value 11
-    1 byte reserved
-    1 u32  next         next hash list record
-    n times             n = (reclen-5)/5
-       1 u32  recnum
-
-    For the current record length of 40, n is 7
-
-
-
-  Record type 254 (free record)
-  ---------------
-    All these records form a linked list of unused records.
-     1 byte  value 254
-     1 byte  reserved (0)
-     1 u32   next_free
-#+end_example
+  byte order.  The length of each record is 40 bytes.  The first
+  record of the DB is always of type 1 and this is the only record of
+  this type.
+
+  The record types: directory(2), key(3), uid(4), pref(5), sigrec(6),
+  and shadow directory(8) are not anymore used by version 2 of the
+  TrustDB.
+
+** Record type 0
+
+   Unused record or deleted, can be reused for any purpose.  Such
+   records should in general not exist because deleted records are of
+   type 254 and kept in a linked list.
+
+** Version info (RECTYPE_VER, 1)
+
+   Version information for this TrustDB.  This is always the first
+   record of the DB and the only one of this type.
+
+   - 1 u8 :: Record type (value: 1).
+   - 3 byte :: Magic value ("gpg")
+   - 1 u8 :: TrustDB version (value: 2).
+   - 1 u8 :: =marginals=. How many marginal trusted keys are required.
+   - 1 u8 :: =completes=. How many completely trusted keys are
+             required.
+   - 1 u8 :: =max_cert_depth=.  How deep is the WoT evaluated.  Along
+             with =marginals= and =completes=, this value is used to
+             check whether the cached validity value from a [FIXME
+             dir] record can be used.
+   - 1 u8 :: =trust_model=
+   - 1 u8 :: =min_cert_level=
+   - 2 byte :: Not used
+   - 1 u32 :: =created=. Timestamp of trustdb creation.
+   - 1 u32 :: =nextcheck=. Timestamp of last modification which may
+              affect the validity of keys in the trustdb.  This value
+              is checked against the validity timestamp in the dir
+              records.
+   - 1 u32 :: =reserved=.  Not used.
+   - 1 u32 :: =reserved2=. Not used.
+   - 1 u32 :: =firstfree=. Number of the record with the head record
+              of the RECTYPE_FREE linked list.
+   - 1 u32 :: =reserved3=. Not used.
+   - 1 u32 :: =trusthashtbl=. Record number of the trusthashtable.
+
+
+** Hash table (RECTYPE_HTBL, 10)
+
+   Due to the fact that we use fingerprints to lookup keys, we can
+   implement quick access by some simple hash methods, and avoid the
+   overhead of gdbm.  A property of fingerprints is that they can be
+   used directly as hash values.  What we use is a dynamic multilevel
+   architecture, which combines hash tables, record lists, and linked
+   lists.
+
+   This record is a hash table of 256 entries with the property that
+   all these records are stored consecutively to make one big
+   table. The hash value is simple the 1st, 2nd, ... byte of the
+   fingerprint (depending on the indirection level).
+
+   - 1 u8 :: Record type (value: 10).
+   - 1 u8 :: Reserved
+   - n u32 :: =recnum=.  A table with the hash table items fitting into
+              this record.  =n= depends on the record length:
+              $n=(reclen-2)/4$ which yields 9 for oure current record
+              length of 40 bytes.
+
+   The total number of hash table records to form the table is:
+   $m=(256+n-1)/n$.  This is 29 for our record length of 40.
+
+   To look up a key we use the first byte of the fingerprint to get
+   the recnum from this hash table and then look up the addressed
+   record:
+
+   - If that record is another hash table, we use 2nd byte to index
+     that hash table and so on;
+   - if that record is a hash list, we walk all entries until we find
+     a matching one; or
+   - if that record is a key record, we compare the fingerprint to
+     decide whether it is the requested key;
+
+
+** Hash list (RECTYPE_HLST, 11)
+
+   See hash table above on how it is used.  It may also be used for
+   other purposes.
+
+   - 1 u8 :: Record type (value: 11).
+   - 1 u8 :: Reserved.
+   - 1 u32 :: =next=.  Record number of the next hash list record or 0
+              if none.
+   - n u32 :: =rnum=.  Array with record numbers to values.  With
+              $n=(reclen-5)/5$ and our record length of 40, n is 7.
+
+** Trust record (RECTYPE_TRUST, 12)
+
+   - 1 u8 :: Record type (value: 12).
+   - 1 u8 :: Reserved.
+   - 20 byte :: =fingerprint=.
+   - 1 u8 :: =ownertrust=.
+   - 1 u8 :: =depth=.
+   - 1 u8 :: =min_ownertrust=.
+   - 1 byte :: Not used.
+   - 1 u32 :: =validlist=.
+   - 10 byte :: Not used.
+
+** Validity record (RECTYPE_VALID, 13)
+
+   - 1 u8 :: Record type (value: 13).
+   - 1 u8 :: Reserved.
+   - 20 byte :: =namehash=.
+   - 1 u8 :: =validity=
+   - 1 u32 :: =next=.
+   - 1 u8 :: =full_count=.
+   - 1 u8 :: =marginal_count=.
+   - 11 byte :: Not used.
+
+** Free record (RECTYPE_FREE, 254)
+
+   All these records form a linked list of unused records in the TrustDB.
+
+   - 1 u8 :: Record type (value: 254)
+   - 1 u8 :: Reserved.
+   - 1 u32 :: =next=.  Record number of the next rcord of this type.
+              The record number to the head of this linked list is
+              stored in the version info record.
+
+
+* Database scheme for the TOFU info
+
+#+begin_src sql
+--
+-- The VERSION table holds the version of our TOFU data structures.
+--
+CREATE TABLE version (
+  version integer -- As of now this is always 1
+);
+
+--
+-- The BINDINGS table associates mail addresses with keys.
+--
+CREATE TABLE bindings (
+  oid integer primary key autoincrement,
+  fingerprint text, -- The key's fingerprint in hex
+  email text,       -- The normalized mail address destilled from user_id
+  user_id text,     -- The unmodified user id
+  time integer,     -- The time this binding was first observed.
+  policy boolean check
+       (policy in (1, 2, 3, 4, 5)), -- The trust policy with the values:
+                                    --   1 := Auto
+                                    --   2 := Good
+                                    --   3 := Unknown
+                                    --   4 := Bad
+                                    --   5 := Ask
+  conflict string,  -- NULL or a hex formatted fingerprint.
+  unique (fingerprint, email)
+);
+
+CREATE INDEX bindings_fingerprint_email on bindings (fingerprint, email);
+CREATE INDEX bindings_email on bindings (email);
+
+--
+-- The SIGNATURES table records all data signatures we verified
+--
+CREATE TABLE signatures (
+  binding integer not null, -- Link to bindings table,
+                            -- references bindings.oid.
+  sig_digest text,          -- The digest of the signed message.
+  origin text,              -- String describing who initially fed
+                            -- the signature to gpg (e.g. "email:claws").
+  sig_time integer,         -- Timestamp from the signature.
+  time integer,             -- Time this record was created.
+  primary key (binding, sig_digest, origin)
+);
+#+end_src
 
 
 * GNU extensions to the S2K algorithm
 
-  S2K mode 101 is used to identify these extensions.
-  After the hash algorithm the 3 bytes "GNU" are used to make
-  clear that these are extensions for GNU, the next bytes gives the
-  GNU protection mode - 1000.  Defined modes are:
-  - 1001 :: Do not store the secret part at all.
-  - 1002 :: A stub to access smartcards (not used in 1.2.x)
+  1 octet  - S2K Usage: either 254 or 255.
+  1 octet  - S2K Cipher Algo: 0
+  1 octet  - S2K Specifier: 101
+  3 octets - "GNU"
+  1 octet  - GNU S2K Extension Number.
+
+  If such a GNU extension is used neither an IV nor any kind of
+  checksum is used.  The defined GNU S2K Extension Numbers are:
+
+  - 1 :: Do not store the secret part at all.  No specific data
+         follows.
+
+  - 2 :: A stub to access smartcards.  This data follows:
+         - One octet with the length of the following serial number.
+         - The serial number. Regardless of what the length octet
+           indicates no more than 16 octets are stored.
+
+  Note that gpg stores the GNU S2K Extension Number internally as an
+  S2K Specifier with an offset of 1000.
+
+
+* Format of the OpenPGP TRUST packet
+
+  According to RFC4880 (5.10), the trust packet (aka ring trust) is
+  only used within keyrings and contains data that records the user's
+  specifications of which key holds trusted introducers.  The RFC also
+  states that the format of this packet is implementation defined and
+  SHOULD NOT be emitted to output streams or should be ignored on
+  import.  GnuPG uses this packet in several additional ways:
+
+  - 1 octet :: Trust-Value (only used by Subtype SIG)
+  - 1 octet :: Signature-Cache (only used by Subtype SIG; value must
+               be less than 128)
+  - 3 octets :: Fixed value: "gpg"
+  - 1 octet  :: Subtype
+               - 0 :: Signature cache (SIG)
+               - 1 :: Key source on the primary key (KEY)
+               - 2 :: Key source on a user id (UID)
+  - 1 octet :: Key Source; i.e. the origin of the key:
+               - 0 :: Unknown source.
+               - 1 :: Public keyserver.
+               - 2 :: Preferred keyserver.
+               - 3 :: OpenPGP DANE.
+               - 4 :: Web Key Directory.
+               - 5 :: Import from a trusted URL.
+               - 6 :: Import from a trusted file.
+               - 7 :: Self generated.
+  - 4 octets :: Time of last update.  This is a a four-octet scalar
+                with the seconds since Epoch.
+  - 1 octet  :: Scalar with the length of the following field.
+  - N octets :: String with the URL of the source.  This may be a
+                zero-length string.
+
+  If the packets contains only two octets a Subtype of 0 is assumed;
+  this is the only format recognized by GnuPG versions < 2.1.18.
+  Trust-Value and Signature-Cache must be zero for all subtypes other
+  than SIG.
+
 
 * Keyserver helper message format
 
+  *This information is obsolete*
+  (Keyserver helpers have been replaced by dirmngr)
+
   The keyserver may be contacted by a Unix Domain socket or via TCP.
 
   The format of a request is:
@@ -1184,6 +1434,43 @@ Status codes are:
 
 
 
+* Debug flags
+
+This tables gives the flag values for the --debug option along with
+the alternative names used by the components.
+
+|       | gpg     | gpgsm   | agent   | scd     | dirmngr | g13     | wks     |
+|-------+---------+---------+---------+---------+---------+---------+---------|
+|     1 | packet  | x509    |         |         | x509    | mount   | mime    |
+|     2 | mpi     | mpi     | mpi     | mpi     |         |         | parser  |
+|     4 | crypto  | crypto  | crypto  | crypto  | crypto  | crypto  | crypto  |
+|     8 | filter  |         |         |         |         |         |         |
+|    16 | iobuf   |         |         |         | dns     |         |         |
+|    32 | memory  | memory  | memory  | memory  | memory  | memory  | memory  |
+|    64 | cache   | cache   | cache   | cache   | cache   |         |         |
+|   128 | memstat | memstat | memstat | memstat | memstat | memstat | memstat |
+|   256 | trust   |         |         |         |         |         |         |
+|   512 | hashing | hashing | hashing | hashing | hashing |         |         |
+|  1024 | ipc     | ipc     | ipc     | ipc     | ipc     | ipc     | ipc     |
+|  2048 |         |         |         | cardio  | network |         |         |
+|  4096 | clock   |         |         | reader  |         |         |         |
+|  8192 | lookup  |         |         |         | lookup  |         |         |
+| 16384 | extprog |         |         |         |         |         | extprog |
+
+Description of some debug flags:
+
+  - cardio :: Used by scdaemon to trace the APDUs exchange with the
+              card.
+  - clock  :: Show execution times of certain functions.
+  - crypto :: Trace crypto operations.
+  - hashing :: Create files with the hashed data.
+  - ipc :: Trace the Assuan commands.
+  - mpi :: Show the values of the MPIs.
+  - reader :: Used by scdaemon to trace card reader related code.  For
+              example: Open and close reader.
+
+
+
 * Miscellaneous notes
 
 ** v3 fingerprints
@@ -1227,5 +1514,35 @@ Status codes are:
       /pks/lookup/<gnupg_formatierte_user_id>?op=<operation>
 
    This can be implemented using Hurd's translator mechanism.
-   However, I think the whole key server stuff has to be re-thought;
+   However, I think the whole keyserver stuff has to be re-thought;
    I have some ideas and probably create a white paper.
+** Algorithm names for the "keygen.algo" prompt
+
+  When using a --command-fd controlled key generation or "addkey"
+  there is way to know the number to enter on the "keygen.algo"
+  prompt.  The displayed numbers are for human reception and may
+  change with releases.  To provide a stable way to enter a desired
+  algorithm choice the prompt also accepts predefined names for the
+  algorithms, which will not change.
+
+   | Name    | No | Description                     |
+   |---------+----+---------------------------------|
+   | rsa+rsa |  1 | RSA and RSA (default)           |
+   | dsa+elg |  2 | DSA and Elgamal                 |
+   | dsa     |  3 | DSA (sign only)                 |
+   | rsa/s   |  4 | RSA (sign only)                 |
+   | elg     |  5 | Elgamal (encrypt only)          |
+   | rsa/e   |  6 | RSA (encrypt only)              |
+   | dsa/*   |  7 | DSA (set your own capabilities) |
+   | rsa/*   |  8 | RSA (set your own capabilities) |
+   | ecc+ecc |  9 | ECC and ECC                     |
+   | ecc/s   | 10 | ECC (sign only)                 |
+   | ecc/*   | 11 | ECC (set your own capabilities) |
+   | ecc/e   | 12 | ECC (encrypt only)              |
+   | keygrip | 13 | Existing key                    |
+
+   If one of the "foo/*" names are used a "keygen.flags" prompt needs
+   to be answered as well.  Instead of toggling the predefined flags,
+   it is also possible to set them direct: Use a "=" character
+   directly followed by a combination of "a" (for authentication), "s"
+   (for signing), or "c" (for certification).