gpg: Emit FAILURE stati now in almost all cases.
[gnupg.git] / doc / DETAILS
index ab70960..e54e8a0 100644 (file)
@@ -149,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
@@ -156,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
@@ -187,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.
@@ -218,6 +220,29 @@ described here.
     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 for this key.
+
+    Valid values are:
+
+    - 8  :: The key is compliant with RFC4880bis
+    - 23 :: The key is compliant with compliance mode "de-vs".
+
+*** 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
@@ -369,9 +394,8 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
 *** NEWSIG [<signers_uid>]
     Is issued right before a signature verification starts.  This is
     useful to define a context for parsing ERROR status messages.
-    arguments are currently defined.  If SIGNERS_UID is given and is
-    not "-" this is the percent escape value of the OpenPGP Signer's
-    User ID signature sub-packet.
+    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
@@ -486,6 +510,12 @@ 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_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>
     Print information about the symmetric encryption algorithm and the
     MDC method.  This will be emitted even if the decryption fails.
@@ -606,6 +636,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:
@@ -702,7 +749,7 @@ 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.
@@ -722,10 +769,18 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     userid encoded in UTF-8 and percent escaped.  The fingerprint is
     identical for all TOFU_USER lines up to a NEWSIG line.
 
-*** TOFU_STATS <summary> <sign-count> <encryption-count> [<policy> [<tm1> <tm2> <tm3> <tm4> [<validity> [<sign-days> <encrypt-days>]]]]
+*** 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
@@ -753,6 +808,19 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     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.
@@ -775,7 +843,7 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     recent message was verified 4 seconds ago.'
 
 *** PKA_TRUST_
-    This is is one:
+    This is one of:
 
     - PKA_TRUST_GOOD <addr-spec>
     - PKA_TRUST_BAD  <addr-spec>
@@ -972,15 +1040,16 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     - 4 :: Key is stored on a smartcard.
 
 *** PROGRESS <what> <char> <cur> <total> [<units>]
-    Used by the primegen and Public key functions to indicate
+    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
@@ -995,7 +1064,9 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
                           the data of a smartcard.
            - card_busy :: A smartcard is still working
 
-    <units> is sometines used to describe the units for <current> and
+    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>
@@ -1008,7 +1079,7 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     This may either be the specified mountpoint or one randomly
     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
@@ -1258,6 +1329,44 @@ CREATE TABLE signatures (
   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*
@@ -1320,6 +1429,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
@@ -1393,5 +1539,5 @@ Status codes are:
    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 comination of "a" (for authentication), "s"
+   directly followed by a combination of "a" (for authentication), "s"
    (for signing), or "c" (for certification).