gpg: First take on PKT_ENCRYPTED_AEAD.
[gnupg.git] / doc / DETAILS
index b5431d0..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:
@@ -35,7 +36,9 @@ 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.
+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 slightly different format and required
@@ -91,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
@@ -120,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
@@ -136,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
 
@@ -146,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
@@ -153,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
@@ -184,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.
@@ -215,6 +220,31 @@ 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 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
@@ -357,16 +387,17 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
 
   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 new
-  keyworkds or 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 [<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
@@ -481,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
@@ -503,8 +541,10 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     --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.
@@ -601,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:
@@ -697,7 +754,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.
@@ -715,16 +772,24 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     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
-    indentical for all TOFU_USER lines up to a NEWSIG line.
+    identical for all TOFU_USER lines up to a NEWSIG line.
 
-*** TOFU_STATS <validity> <sign-count> 0 [<policy> [<tm1> <tm2> <tm3> <tm4>]]
+*** TOFU_STATS <MANY_ARGS>
 
     Statistics for the current user id.
 
-    Values for VALIDITY are:
-    - 0 :: conflict
-    - 1 :: key without history
-    - 2 :: key with too little history
+    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
 
@@ -734,14 +799,41 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     - good    :: Policy is "good"
     - bad     :: Policy is "bad"
     - ask     :: Policy is "ask"
-    - unknown :: Policy is not known.
+    - unknown :: Policy is "unknown" (TOFU information does not
+                 contribute to the key's validity)
 
-    TM1 ist the time the first message was verified.  TM2 is the time
+    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.
@@ -756,7 +848,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>
@@ -930,7 +1022,7 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     commencing with a letter or such a string prefixed with a
     numerical error code and an underscore; e.g.: "151011327_EOF".
 *** SUCCESS [<location>]
-    Postive confirmation that an operation succeeded.  It is used
+    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.
 
@@ -953,15 +1045,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
@@ -976,7 +1069,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>
@@ -987,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
@@ -1239,6 +1334,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*
@@ -1301,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
@@ -1374,5 +1544,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).