gpg: Do not use honor-keyserver-url sub-option by default.
[gnupg.git] / doc / DETAILS
index a52979f..fd72b88 100644 (file)
@@ -32,8 +32,8 @@ fpr:::::::::AB059359A3B81F410FCFF97F5CE086B5B5A18FF4:
 #+end_example
 
 The double =--with-fingerprint= prints the fingerprint for the subkeys
-too.  Old versions of gpg used a lighly different format and required
-the use of the option =--fixed-list-mode= to conform to format
+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
@@ -161,6 +161,7 @@ described here.
     - s :: Sign
     - c :: Certify
     - a :: Authentication
+    - ? :: Unknown capability
 
     A key may have any combination of them in any order.  In addition
     to these letters, the primary key has uppercase versions of the
@@ -191,15 +192,21 @@ 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
 
     For sig records, this is the used hash algorithm.  For example:
     2 = SHA-1, 8 = SHA-256.
 
+*** Field 17 - Curve name
+
+    For pub, sub, sec, and ssb records this field is used for the ECC
+    curve name.
+
 ** Special fields
 
 *** PKD - Public key data
@@ -280,19 +287,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
 
@@ -312,6 +322,12 @@ 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
 
@@ -322,9 +338,9 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
 
 ** 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.
+    Is issued right before a signature verification starts.  This is
+    useful to define a context for parsing ERROR status messages.  No
+    arguments are currently defined.
 
 *** GOODSIG  <long_keyid_or_fpr>  <username>
     The signature with the keyid is good.  For each signature only one
@@ -374,8 +390,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>
 
@@ -453,9 +469,10 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
 
 *** 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>
     Mark the start of the actual encryption process.
@@ -575,6 +592,8 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
        - 10 :: Key not trusted
        - 11 :: Missing certificate
        - 12 :: Missing issuer certificate
+       - 13 :: Key disabled
+       - 14 :: Syntax error in specification
 
     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.
@@ -729,7 +748,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>
@@ -740,6 +759,7 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     - <sec_dups>
     - <skipped_new_keys>
     - <not_imported>
+    - <skipped_v3_keys>
 
 ** Smartcard related
 *** CARDCTRL <what> [<serialno>]
@@ -754,6 +774,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
@@ -785,6 +806,7 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
 *** UNEXPECTED <what>
     Unexpected data has been encountered.  Codes for WHAT are:
     - 0 :: Not further specified
+    - 1 :: Corrupted message structure
 
 *** TRUNCATED <maxno>
     The output was truncated to MAXNO items.  This status code is
@@ -810,6 +832,7 @@ 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
@@ -1111,12 +1134,26 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
 
 * 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.
+
 
 * Keyserver helper message format
 
@@ -1222,3 +1259,33 @@ Status codes are:
    This can be implemented using Hurd's translator mechanism.
    However, I think the whole key server 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 comination of "a" (for authentication), "s"
+   (for signing), or "c" (for certification).