Refresh sample keys
[gnupg.git] / doc / DETAILS
index d37fda4..4e87394 100644 (file)
@@ -1,10 +1,10 @@
-
+                                                              -*- text -*-
 Format of colon listings
 ========================
 First an example:
 
-$ gpg --fixed-list-mode --with-colons --list-keys \
-   --with-fingerprint --with-fingerprint wk@gnupg.org
+$ gpg --with-colons --list-keys \
+      --with-fingerprint --with-fingerprint wk@gnupg.org
 
 pub:f:1024:17:6C7EE1B8621CC013:899817715:1055898235::m:::scESC:
 fpr:::::::::ECAF7590EB3443B5C7CF3ACB6C7EE1B8621CC013:
@@ -16,9 +16,9 @@ sub:r:1536:20:5CE086B5B5A18FF4:899817788:1025961788:::::esc:
 fpr:::::::::AB059359A3B81F410FCFF97F5CE086B5B5A18FF4:
 
 The double --with-fingerprint prints the fingerprint for the subkeys
-too, --fixed-list-mode is themodern listing way printing dates in
+too. --fixed-list-mode is the modern listing way printing dates in
 seconds since Epoch and does not merge the first userID with the pub
-record.
+record; gpg2 does this by default and the option is a dummy.
 
 
  1. Field:  Type of record
@@ -34,71 +34,127 @@ record.
             rev = revocation signature
            fpr = fingerprint: (fingerprint is in field 10)
            pkd = public key data (special field format, see below)
-            grp = reserved for gpgsm
+            grp = keygrip
             rvk = revocation key
+            tru = trust database information
+            spk = signature subpacket
 
- 2. Field:  A letter describing the calculated trust. This is a single
+ 2. Field:  A letter describing the calculated validity. This is a single
            letter, but be prepared that additional information may follow
            in some future versions. (not used for secret keys)
                o = Unknown (this key is new to the system)
                 i = The key is invalid (e.g. due to a missing self-signature)
                d = The key has been disabled
+                   (deprecated - use the 'D' in field 12 instead)
                r = The key has been revoked
                e = The key has expired
-               - = Unknown trust (i.e. no value assigned)
-               q = Undefined trust
+               - = Unknown validity (i.e. no value assigned)
+               q = Undefined validity
                    '-' and 'q' may safely be treated as the same
                    value for most purposes
-               n = Don't trust this key at all
-               m = There is marginal trust in this key
-               f = The key is fully trusted
-               u = The key is ultimately trusted.  This often means
+               n = The key is not valid
+               m = The key is marginal valid.
+               f = The key is fully valid
+               u = The key is ultimately valid.  This often means
                    that the secret key is available, but any key may
-                   be marked as ultimately trusted.
+                   be marked as 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.
+
+            If the validity information is given for a UID or UAT
+            record, it describes the validity calculated based on this
+            user ID.  If given for a key record it describes the best
+            validity taken from the best rated user ID.
+
+            For X.509 certificates a 'u' is used for a trusted root
+            certificate (i.e. for the trust anchor) and an 'f' for all
+            other valid certificates.
+
  3. Field:  length of key in bits.
+
  4. Field:  Algorithm: 1 = RSA
-                      16 = ElGamal (encrypt only)
+                      16 = Elgamal (encrypt only)
                       17 = DSA (sometimes called DH, sign only)
-                      20 = ElGamal (sign and encrypt)
+                      20 = Elgamal (sign and encrypt - don't use them!)
            (for other id's see include/cipher.h)
- 5. Field:  KeyID either of 
- 6. Field:  Creation Date (in UTC)
- 7. Field:  Key expiration date or empty if none.
- 8. Field:  Used for serial number in crt records (used to be the Local-ID)
+
+ 5. Field:  KeyID
+
+ 6. Field:  Creation Date (in UTC).  For UID and UAT records, this is
+            the self-signature date.  Note that the date is usally
+            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'.
+
+ 7. Field:  Key or user ID/user attribute expiration date or empty if none.
+
+ 8. Field:  Used for serial number in crt records (used to be the Local-ID).
+            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.
+
  9. Field:  Ownertrust (primary public keys only)
            This is a single letter, but be prepared that additional
-           information may follow in some future versions.
+           information may follow in some future versions.  For trust
+           signatures with a regular expression, this is the regular
+           expression value, quoted as in field 10.
+
 10. Field:  User-ID.  The value is quoted like a C string to avoid
            control characters (the colon is quoted "\x3a").
-            This is not used with --fixed-list-mode in gpg.
+            For a "pub" record this field is not used on --fixed-list-mode.
             A UAT record puts the attribute subpacket count here, a
            space, and then the total attribute subpacket size.
             In gpgsm the issuer name comes here
             An FPR record stores the fingerprint here.
             The fingerprint of an revocation key is stored here.
-11. Field:  Signature class.  This is a 2 digit hexnumber followed by
-            either the letter 'x' for an exportable signature or the
-            letter 'l' for a local-only signature.
-            The class byte of an revocation key is also given here,
-            'x' and 'l' ist used the same way.
+
+11. Field:  Signature class as per RFC-4880.  This is a 2 digit
+            hexnumber followed by either the letter 'x' for an
+            exportable signature or the letter 'l' for a local-only
+            signature.  The class byte of an revocation key is also
+            given here, 'x' and 'l' is used the same way.  IT is not
+            used for X.509.
+
 12. Field:  Key capabilities:
                 e = encrypt
                 s = sign
                 c = certify
-            A key may have any combination of them.  The primary key has in
-            addition to these letters, uppercase version of the letter to
-            denote the _usable_ capabilities of the entire key.  
-13. Field:  Used in FPR records for S/MIME keys to store the fingerprint of
-            the issuer certificate.  This is useful to build the
-            certificate path based on certificates stored in the local
-            keyDB; it is only filled if the issue certificate is
-            available. The advantage of using this value is that it is
-            guaranteed to have been been build by the same lookup
-            algorithm as gpgsm uses.
-            For "uid" recods this lists the preferences n the sameway the 
-            -edit menu does.
+                a = authentication
+           A key may have any combination of them in any order.  In
+           addition to these letters, the primary key has uppercase
+           versions of the letters to denote the _usable_
+           capabilities of the entire key, and a potential letter 'D'
+           to indicate a disabled key.
+
+13. Field:  Used in FPR records for S/MIME keys to store the
+            fingerprint of the issuer certificate.  This is useful to
+            build the certificate path based on certificates stored in
+            the local keyDB; it is 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.
+            For "uid" records this lists the preferences in the same
+            way the gpg's --edit-key menu does.
+           For "sig" records, this is the fingerprint of the key that
+           issued the signature.  Note that this is only filled in if
+           the signature verified correctly.  Note also that for
+           various technical reasons, this fingerprint is only
+           available if --no-sig-cache is used.
+
 14. Field   Flag field used in the --edit menu output:
 
+15. Field   Used in sec/sbb 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)
+16. Field:  For sig records, this is the used hash algorithm:
+                2 = SHA-1
+                8 = SHA-256
+           (for other id's see include/cipher.h)
 
 All dates are displayed in the format yyyy-mm-dd unless you use the
 option --fixed-list-mode in which case they are displayed as seconds
@@ -113,7 +169,50 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
     !  !------ for information number of bits in the value
     !--------- index (eg. DSA goes from 0 to 3: p,q,g,y)
 
+
+Example for a "tru" trust base record:
+
+   tru:o:0:1166697654:1:3:1:5
+
+ The fields are:
+
+ 2: Reason for staleness of trust.  If this field is empty, then the
+    trustdb is not stale.  This field may have multiple flags in it:
+
+    o: Trustdb is old
+    t: Trustdb was built with a different trust model than the one we
+       are using now.
+
+ 3: Trust model:
+    0: Classic trust model, as used in PGP 2.x.
+    1: PGP trust model, as used in PGP 6 and later.  This is the same
+       as the classic trust model, except for the addition of trust
+       signatures.
+
+    GnuPG before version 1.4 used the classic trust model by default.
+    GnuPG 1.4 and later uses the PGP trust model by default.
+
+ 4: Date trustdb was created in seconds since 1970-01-01.
+ 5: Date trustdb will expire in seconds since 1970-01-01.
+ 6: Number of marginally trusted users to introduce a new key signer
+    (gpg's option --marginals-needed)
+ 7: Number of completely trusted users to introduce a new key signer.
+    (gpg's option --completes-needed)
+ 8: Maximum depth of a certification chain.
+    *gpg's option --max-cert-depth)
+
+The "spk" signature subpacket records have the fields:
+
+ 2: Subpacket number as per RFC-4880 and later.
+ 3: Flags in hex.  Currently the only two bits assigned are 1, to
+    indicate that the subpacket came from the hashed part of the
+    signature, and 2, to indicate the subpacket was marked critical.
+ 4: Length of the subpacket.  Note that this is the length of the
+    subpacket, and not the length of field 5 below.  Due to the need
+    for %-encoding, the length of field 5 may be up to 3x this value.
+ 5: The subpacket data.  Printable ASCII is shown as ASCII, but other
+    values are rendered as %XX where XX is the hex value for the byte.
+
 
 Format of the "--status-fd" output
 ==================================
@@ -123,45 +222,89 @@ type (maybe none); an application should always be prepared to see
 more arguments in future versions.
 
 
-    GOODSIG    <long keyid>  <username>
-       The signature with the keyid is good.  For each signature only
-        one of the three codes GOODSIG, BADSIG or ERRSIG will be
-        emitted and they may be used as a marker for a new signature.
-        The username is the primary one encoded in UTF-8 and %XX
-        escaped.
+    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.
 
-    EXPSIG     <long keyid>  <username>
+    GOODSIG  <long_keyid_or_fpr>  <username>
+       The signature with the keyid is good.  For each signature only
+        one of the codes GOODSIG, BADSIG, EXPSIG, EXPKEYSIG, REVKEYSIG
+        or ERRSIG will be emitted.  In the past they were used as a
+        marker for a new signature; new code should use the NEWSIG
+        status instead.  The username is the primary one encoded in
+        UTF-8 and %XX escaped. The fingerprint may be used instead of
+        the long keyid if it is available.  This is the case with CMS
+        and might eventually also be available for OpenPGP.
+
+    EXPSIG  <long_keyid_or_fpr>  <username>
        The signature with the keyid is good, but the signature is
        expired. The username is the primary one encoded in UTF-8 and
-       %XX escaped.
+       %XX escaped. The fingerprint may be used instead of the long
+       keyid if it is available.  This is the case with CMS and might
+       eventually also be available for OpenPGP.
 
-    EXPKEYSIG  <long keyid>  <username>
-       The signature with the keyid is good, but the signature was
+    EXPKEYSIG  <long_keyid_or_fpr> <username>
+        The signature with the keyid is good, but the signature was
        made by an expired key. The username is the primary one
-       encoded in UTF-8 and %XX escaped.
-
-    BADSIG     <long keyid>  <username>
-       The signature with the keyid has not been verified okay.
-        The username is the primary one encoded in UTF-8 and %XX
-        escaped.
+       encoded in UTF-8 and %XX escaped.  The fingerprint may be used
+       instead of the long keyid if it is available.  This is the
+       case with CMS and might eventually also be available for
+       OpenPGP.
 
-    ERRSIG  <long keyid>  <pubkey_algo> <hash_algo> \
+    REVKEYSIG  <long_keyid_or_fpr>  <username>
+       The signature with the keyid is good, but the signature was
+       made by a revoked key. The username is the primary one encoded
+       in UTF-8 and %XX escaped. The fingerprint may be used instead
+       of the long keyid if it is available.  This is the case with
+       CMS and might eventually also be available for OpenPGP.
+
+    BADSIG  <long_keyid_or_fpr>  <username>
+       The signature with the keyid has not been verified okay.  The
+        username is the primary one encoded in UTF-8 and %XX
+        escaped. The fingerprint may be used instead of the long keyid
+        if it is available.  This is the case with CMS and might
+        eventually also be available for OpenPGP.
+
+    ERRSIG  <long_keyid_or_fpr>  <pubkey_algo> <hash_algo> \
            <sig_class> <timestamp> <rc>
        It was not possible to check the signature.  This may be
-       caused by a missing public key or an unsupported algorithm.
-       A RC of 4 indicates unknown algorithm, a 9 indicates a missing
-       public key. The other fields give more information about
-       this signature.  sig_class is a 2 byte hex-value.
+       caused by a missing public key or an unsupported algorithm.  A
+       RC of 4 indicates unknown algorithm, a 9 indicates a missing
+       public key. The other fields give more information about this
+       signature.  sig_class is a 2 byte hex-value.  The fingerprint
+       may be used instead of the long keyid if it is available.
+       This is the case with CMS and might eventually also be
+       available for OpenPGP.
+
+        Note, that TIMESTAMP may either be a number with seconds since
+        epoch or an ISO 8601 string which can be detected by the
+        presence of the letter 'T' inside.
 
     VALIDSIG   <fingerprint in hex> <sig_creation_date> <sig-timestamp>
-               <expire-timestamp>
-
-       The signature with the keyid is good. This is the same
-       as GOODSIG but has the fingerprint as the argument. Both
-       status lines are emitted for a good signature.
-       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").
+               <expire-timestamp>  <sig-version> <reserved> <pubkey-algo>
+               <hash-algo> <sig-class> [ <primary-key-fpr> ]
+
+       The signature with the keyid 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 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 to the first argument.  This is
+       useful to get back to the primary key without running gpg
+       again for this purpose.
+
+        The primary-key-fpr parameter is used for OpenPGP and not
+        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 with seconds
+        since epoch or an ISO 8601 string which can be detected by the
+        presence of the letter 'T' inside.
 
     SIG_ID  <radix64_string>  <sig_creation_date>  <sig-timestamp>
        This is emitted only for signatures of class 0 or 1 which
@@ -171,39 +314,69 @@ more arguments in future versions.
        unique ids - others may yield duplicated ones when they
        have been created in the same second.
 
-    ENC_TO  <long keyid>  <keytype>  <keylength>
-       The message is encrypted to this keyid.
-       keytype is the numerical value of the public key algorithm,
-       keylength is the length of the key or 0 if it is not known
-       (which is currently always the case).
+        Note, that SIG-TIMESTAMP may either be a number with seconds
+        since epoch or an ISO 8601 string which can be detected by the
+        presence of the letter 'T' inside.
+
+    ENC_TO  <long_keyid>  <keytype>  <keylength>
+       The message is encrypted to this LONG_KEYID.  KEYTYPE is the
+       numerical value of the public key algorithm or 0 if it is not
+       known, KEYLENGTH is the length of the key or 0 if it is not
+       known (which is currently always the case).  Gpg prints this
+       line always; Gpgsm only if it knows the certificate.
 
     NODATA  <what>
        No data has been found. Codes for what are:
            1 - No armored data.
            2 - Expected a packet but did not found one.
-           3 - Invalid packet found, this may indicate a non OpenPGP message.
+           3 - Invalid packet found, this may indicate a non OpenPGP
+                message.
+            4 - signature expected but not found
        You may see more than one of these status lines.
 
     UNEXPECTED <what>
         Unexpected data has been encountered
-            0 - not further specified               1       
-  
+            0 - not further specified
+
 
     TRUST_UNDEFINED <error token>
-    TRUST_NEVER  <error token>
-    TRUST_MARGINAL
-    TRUST_FULLY
-    TRUST_ULTIMATE
-       For good signatures one of these status lines are emitted
-       to indicate how trustworthy the signature is.  The error token
-        values are currently only emiited by gpgsm.
-
-    SIGEXPIRED
-       This is deprecated in favor of KEYEXPIRED.
+    TRUST_NEVER     <error token>
+    TRUST_MARGINAL  [0  [<validation_model>]]
+    TRUST_FULLY     [0  [<validation_model>]]
+    TRUST_ULTIMATE  [0  [<validation_model>]]
+       For good signatures one of these status lines are emitted to
+       indicate the validity of the key used to create the signature.
+       The error token values are currently only emitted by gpgsm.
+       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 defined values are
+
+           "pgp"   for the standard PGP WoT.
+          "shell" for the standard X.509 model.
+          "chain" for the chain model.
+           "steed" for the STEED model.
+
+        Note that we use the term "TRUST_" in the status names for
+        historic reasons; we now speak of validity.
+
+    PKA_TRUST_GOOD <mailbox>
+    PKA_TRUST_BAD  <mailbox>
+        Depending on the outcome of the PKA check one of the above
+        status codes is emitted in addition to a TRUST_* status.
+        Without PKA info available or
 
     KEYEXPIRED <expire-timestamp>
        The key has expired.  expire-timestamp is the expiration time
-       in seconds after the epoch.
+       in seconds since Epoch.  This status line is not very useful
+       because it will also be emitted for expired subkeys even if
+       this subkey is not used.  To check whether a key used to sign
+       a message has expired, the EXPKEYSIG status line is to be
+       used.
+
+        Note, that TIMESTAMP may either be a number with seconds since
+        epoch or an ISO 8601 string which can be detected by the
+        presence of the letter 'T' inside.
 
     KEYREVOKED
        The used key has been revoked by its owner.  No arguments yet.
@@ -212,11 +385,9 @@ more arguments in future versions.
        The ASCII armor is corrupted.  No arguments yet.
 
     RSA_OR_IDEA
-       The IDEA algorithms has been used in the data.  A
-       program might want to fallback to another program to handle
-       the data if GnuPG failed.  This status message used to be emitted
-        also for RSA but this has been dropped after the RSA patent expired.
-        However we can't change the name of the message.
+       Obsolete.  This status message used to be emitted for requests
+        to use the IDEA or RSA algorithms.  It has been dropped from
+        GnuPG 2.1 after the respective patents expired.
 
     SHM_INFO
     SHM_GET
@@ -237,6 +408,9 @@ more arguments in future versions.
     NEED_PASSPHRASE_SYM <cipher_algo> <s2k_mode> <s2k_hash>
        Issued whenever a passphrase for symmetric encryption is needed.
 
+    NEED_PASSPHRASE_PIN <card_type> <chvno> [<serialno>]
+        Issued whenever a PIN is requested to unlock a card.
+
     MISSING_PASSPHRASE
        No passphrase was supplied.  An application which encounters this
        message may want to stop parsing immediately because the next message
@@ -253,21 +427,14 @@ more arguments in future versions.
        The supplied passphrase was good and the secret key material
        is therefore usable.
 
-    DECRYPTION_FAILED
-       The symmetric decryption failed - one reason could be a wrong
-       passphrase for a symmetrical encrypted message.
-
-    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 return an errorcode because it may not be possible to
-       verify a signature for some reasons.
-
     NO_PUBKEY  <long keyid>
     NO_SECKEY  <long keyid>
        The key is not available
 
+    IMPORT_CHECK <long keyid> <fingerprint> <user ID>
+        This status is emitted in interactive mode right before
+        the "import.okay" prompt.
+
     IMPORTED   <long keyid>  <username>
        The keyid and name of the signature just imported
 
@@ -278,7 +445,7 @@ more arguments in future versions.
           1 := Entirely new key.
           2 := New user IDs
           4 := New signatures
-          8 := New subkeys 
+          8 := New subkeys
          16 := Contains private key.
         The flags may be ORed.
 
@@ -291,7 +458,8 @@ more arguments in future versions.
           4 := "Error storing certificate".
 
     IMPORT_RES <count> <no_user_id> <imported> <imported_rsa> <unchanged>
-       <n_uids> <n_subk> <n_sigs> <n_revoc> <sec_read> <sec_imported> <sec_dups> <not_imported>
+       <n_uids> <n_subk> <n_sigs> <n_revoc> <sec_read> <sec_imported>
+        <sec_dups> <skipped_new_keys> <not_imported>
        Final statistics on import process (this is one long line)
 
     FILE_START <what> <filename>
@@ -299,7 +467,7 @@ more arguments in future versions.
        operation:
            1 - verify
             2 - encrypt
-            3 - decrypt        
+            3 - decrypt
 
     FILE_DONE
        Marks the end of a file processing which has been started
@@ -310,10 +478,31 @@ more arguments in future versions.
        Mark the start and end of the actual decryption process.  These
        are also emitted when in --list-only mode.
 
+    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.
+
+    DECRYPTION_FAILED
+       The symmetric decryption failed - one reason could be a wrong
+       passphrase for a symmetrical encrypted message.
+
+    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 return an errorcode because it may not be possible to
+       verify a signature for some reasons.
+
     BEGIN_ENCRYPTION  <mdc_method> <sym_algo>
     END_ENCRYPTION
        Mark the start and end of the actual encryption process.
 
+    BEGIN_SIGNING
+       Mark the start of the actual signing process. This may be used
+       as an indication that all requested secret keys are ready for
+       use.
+
     DELETE_PROBLEM reason_code
        Deleting a key failed.  Reason codes are:
            1 - No such key
@@ -325,8 +514,25 @@ more arguments in future versions.
        "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.  100/100 may be used to detect the
-       end of operation.
+       the total amount is not known.  The condition
+           TOATL && CUR == TOTAL
+        may be used to detect the end of an operation.
+        Well known values for WHAT:
+             "pk_dsa"   - DSA key generation
+             "pk_elg"   - Elgamal key generation
+             "primegen" - Prime generation
+             "need_entropy" - Waiting for new entropy in the RNG
+             "file:XXX" - processing file XXX
+                          (note that current gpg versions leave out the
+                           "file:" prefix).
+             "tick"     - generic tick without any special meaning - useful
+                          for letting clients know that the server is
+                          still working.
+             "starting_agent" - A gpg-agent was started because it is not
+                          running as a daemon.
+             "learncard"  Send by the agent and gpgsm while learing
+                         the data of a smartcard.
+             "card_busy"  A smartcard is still working
 
     SIG_CREATED <type> <pubkey algo> <hash algo> <class> <timestamp> <key fpr>
        A signature has been created using these parameters.
@@ -335,28 +541,38 @@ more arguments in future versions.
                   'S' = standard
                   (only the first character should be checked)
            class: 2 hex digits with the signature class
-        
-    KEY_CREATED <type> <fingerprint>
+
+        Note, that TIMESTAMP may either be a number with seconds since
+        epoch or an ISO 8601 string which can be detected by the
+        presence of the letter 'T' inside.
+
+    KEY_CREATED <type> <fingerprint> [<handle>]
         A key has been created
             type: 'B' = primary and subkey
                   'P' = primary
                   'S' = subkey
         The fingerprint is one of the primary key for type B and P and
-        the one of the subkey for S.
+        the one of the subkey for S.  Handle is an arbitrary
+        non-whitespace string used to match key parameters from batch
+        key creation run.
+
+    KEY_NOT_CREATED [<handle>]
+        The key from batch run has not been created due to errors.
+
 
     SESSION_KEY  <algo>:<hexdigits>
        The session key used to decrypt the message.  This message will
-       only be emmited when the special option --show-session-key
+       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
 
-    NOTATION_NAME <name> 
+    NOTATION_NAME <name>
     NOTATION_DATA <string>
-        name and string are %XX escaped; the data may be splitted
-        among several notation_data lines.
+        name and string are %XX escaped; the data may be split
+        among several NOTATION_DATA lines.
 
     USERID_HINT <long main keyid> <string>
-        Give a hint about the user ID for a certain keyID. 
+        Give a hint about the user ID for a certain keyID.
 
     POLICY_URL <string>
         string is %XX escaped
@@ -366,7 +582,8 @@ more arguments in future versions.
         Issued by pipemode.
 
     INV_RECP <reason> <requested_recipient>
-        Issued for each unusable recipient. The reasons codes
+    INV_SGNR <reason> <requested_sender>
+        Issued for each unusable recipient/sender. The reasons codes
         currently in use are:
           0 := "No specific reason given".
           1 := "Not Found"
@@ -379,12 +596,21 @@ more arguments in future versions.
           8 := "Policy mismatch"
           9 := "Not a secret key"
         10 := "Key not trusted"
+         11 := "Missing certificate"
+         12 := "Missing issuer certificate"
+
+        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.  Newer GnuPG versions are using INV_SGNR;
+        applications should ignore the INV_RECP during the sender's
+        command processing once they have seen an INV_SGNR.  We use
+        different code so that we can distinguish them while doing an
+        encrypt+sign.
 
-        Note that this status is also used for gpgsm's SIGNER command
-        where it relates to signer's of course.
 
     NO_RECP <reserved>
-        Issued when no recipients are usable.
+    NO_SGNR <reserved>
+        Issued when no recipients/senders are usable.
 
     ALREADY_SIGNED <long-keyid>
         Warning: This is experimental and might be removed at any time.
@@ -393,10 +619,20 @@ more arguments in future versions.
         The output was truncated to MAXNO items.  This status code is issued
         for certain external requests
 
-    ERROR <error location> <error code> 
+    ERROR <error location> <error code> [<more>]
+
         This is a generic error status message, it might be followed
-        by error location specific data. <error token> and
-        <error_location> should not contain a space.
+        by error location specific data. <error code> and
+        <error_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.
+
 
     ATTRIBUTE <fpr> <octets> <type> <index> <count>
              <timestamp> <expiredate> <flags>
@@ -414,152 +650,154 @@ more arguments in future versions.
                0x02 = this attribute packet is revoked
                0x04 = this attribute packet is expired
 
+    CARDCTRL <what> [<serialno>]
+        This is used to control smartcard operations.
+        Defined values for WHAT are:
+           1 = Request insertion of a card.  Serialnumber may be given
+               to request a specific card.  Used by gpg 1.4 w/o scdaemon.
+           2 = Request removal of a card.  Used by gpg 1.4 w/o scdaemon.
+           3 = Card with serialnumber detected
+           4 = No card available.
+           5 = No card reader available
+           6 = No card support available
+
+    PLAINTEXT <format> <timestamp> <filename>
+        This indicates the format of the plaintext that is about to be
+        written.  The format is a 1 byte hex code that shows the
+        format of the plaintext: 62 ('b') is binary data, 74 ('t') is
+        text data with no character set specified, and 75 ('u') is
+        text data encoded in the UTF-8 character set.  The timestamp
+        is in seconds since the epoch.  If a filename is available it
+        gets printed as the third argument, percent-escaped as usual.
+
+    PLAINTEXT_LENGTH <length>
+        This indicates the length of the plaintext that is about to be
+        written.  Note that if the plaintext packet has partial length
+        encoding it is not possible to know the length ahead of time.
+        In that case, this status tag does not appear.
+
+    SIG_SUBPACKET <type> <flags> <len> <data>
+        This indicates that a signature subpacket was seen.  The
+        format is the same as the "spk" record above.
+
+    SC_OP_FAILURE [<code>]
+        An operation on a smartcard definitely failed.  Currently
+        there is no indication of the actual error code, but
+        application should be prepared to later accept more arguments.
+        Defined values for CODE are:
+           0 - unspecified error (identically to a missing CODE)
+           1 - canceled
+           2 - bad PIN
+
+    SC_OP_SUCCESS
+        A smart card operaion succeeded.  This status is only printed
+        for certain operation and is mostly useful to check whether a
+        PIN change really worked.
+
+    BACKUP_KEY_CREATED fingerprint fname
+        A backup key named FNAME has been created for the key with
+        KEYID.
+
+    MOUNTPOINT <name>
+        NAME is a percent-plus escaped filename describing the
+        mountpoint for the current operation (e.g. g13 --mount).  This
+        may either be the specified mountpoint or one randomly choosen
+        by g13.
+
+
+Status lines which are not anymore used:
+
+    SIGEXPIRED removed on 2011-02-04.
+       This is deprecated in favor of KEYEXPIRED.
+
+
+
+
+Format of the "--attribute-fd" output
+=====================================
+
+When --attribute-fd is set, during key listings (--list-keys,
+--list-secret-keys) GnuPG dumps each attribute packet to the file
+descriptor specified.  --attribute-fd is intended for use with
+--status-fd as part of the required information is carried on the
+ATTRIBUTE status tag (see above).
+
+The contents of the attribute data is specified by RFC 4880.  For
+convenience, here is the Photo ID format, as it is currently the only
+attribute defined:
+
+   Byte 0-1:  The length of the image header.  Due to a historical
+              accident (i.e. oops!) back in the NAI PGP days, this is
+              a little-endian number.  Currently 16 (0x10 0x00).
+
+   Byte 2:    The image header version.  Currently 0x01.
+
+   Byte 3:    Encoding format.  0x01 == JPEG.
+
+   Byte 4-15: Reserved, and currently unused.
+
+   All other data after this header is raw image (JPEG) data.
+
+
+Format of the "--list-config" output
+====================================
+
+--list-config outputs information about the GnuPG configuration for
+the benefit of frontends or other programs that call GnuPG.  There are
+several list-config items, all colon delimited like the rest of the
+--with-colons output.  The first field is always "cfg" to indicate
+configuration information.  The second field is one of (with
+examples):
+
+version: the third field contains the version of GnuPG.
+
+   cfg:version:1.3.5
+
+pubkey: the third field contains the public key algorithmdcaiphers
+       this version of GnuPG supports, separated by 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.
+
+   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.
+
+   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.
+
+   cfg:digest:1;2;3;8;9;10
+
+compress: the third field contains the compression algorithms this
+         version of GnuPG supports, separated by semicolons.  The
+         algorithm numbers are as specified in RFC-4880.
+
+   cfg:compress:0;1;2;3
+
+group: the third field contains the name of the group, and the fourth
+       field contains the values that the group expands to, separated
+       by semicolons.
+
+For example, a group of:
+   group mynames = paige 0x12345678 joe patti
+
+would result in:
+   cfg:group:mynames:patti;joe;0x12345678;paige
+
 
 Key generation
 ==============
-    Key generation shows progress by printing different characters to
-    stderr:
-            "."  Last 10 Miller-Rabin tests failed
-            "+"  Miller-Rabin test succeeded
-            "!"  Reloading the pool with fresh prime numbers
-            "^"  Checking a new value for the generator
-            "<"  Size of one factor decreased
-            ">"  Size of one factor increased
-
-    The prime number for ElGamal is generated this way:
-
-    1) Make a prime number q of 160, 200, 240 bits (depending on the keysize)
-    2) Select the length of the other prime factors to be at least the size
-       of q and calculate the number of prime factors needed
-    3) Make a pool of prime numbers, each of the length determined in step 2
-    4) Get a new permutation out of the pool or continue with step 3
-       if we have tested all permutations.
-    5) Calculate a candidate prime p = 2 * q * p[1] * ... * p[n] + 1
-    6) Check that this prime has the correct length (this may change q if
-       it seems not to be possible to make a prime of the desired length)
-    7) Check whether this is a prime using trial divisions and the
-       Miller-Rabin test.
-    8) Continue with step 4 if we did not find a prime in step 7.
-    9) Find a generator for that prime.
-
-    This algorithm is based on Lim and Lee's suggestion from the
-    Crypto '97 proceedings p. 260.
+See the Libcrypt manual.
 
 
 Unattended key generation
 =========================
-This feature allows unattended generation of keys controlled by a
-parameter file.  To use this feature, you use --gen-key together with
---batch and feed the parameters either from stdin or from a file given
-on the commandline.
-
-The format of this file is as follows:
-  o Text only, line length is limited to about 1000 chars.
-  o You must use UTF-8 encoding to specify non-ascii characters.
-  o Empty lines are ignored.
-  o Leading and trailing spaces are ignored.
-  o A hash sign as the first non white space character indicates a comment line.
-  o Control statements are indicated by a leading percent sign, the
-    arguments are separated by white space from the keyword.
-  o Parameters are specified by a keyword, followed by a colon.  Arguments
-    are separated by white space.
-  o The first parameter must be "Key-Type", control statements
-    may be placed anywhere.
-  o Key generation takes place when either the end of the parameter file
-    is reached, the next "Key-Type" parameter is encountered or at the
-    control statement "%commit"
-  o Control statements:
-    %echo <text>
-       Print <text>.
-    %dry-run
-       Suppress actual key generation (useful for syntax checking).
-    %commit
-       Perform the key generation.  An implicit commit is done
-       at the next "Key-Type" parameter.
-    %pubring <filename>
-    %secring <filename>
-       Do not write the key to the default or commandline given
-       keyring but to <filename>.  This must be given before the first
-       commit to take place, duplicate specification of the same filename
-       is ignored, the last filename before a commit is used.
-       The filename is used until a new filename is used (at commit points)
-       and all keys are written to that file.  If a new filename is given,
-       this file is created (and overwrites an existing one).
-       Both control statements must be given.
-   o The order of the parameters does not matter except for "Key-Type"
-     which must be the first parameter.  The parameters are only for the
-     generated keyblock and parameters from previous key generations are not
-     used. Some syntactically checks may be performed.
-     The currently defined parameters are:
-     Key-Type: <algo-number>|<algo-string>
-       Starts a new parameter block by giving the type of the
-       primary key. The algorithm must be capable of signing.
-       This is a required parameter.
-     Key-Length: <length-in-bits>
-       Length of the key in bits.  Default is 1024.
-     Key-Usage: <usage-list>
-        Space or comma delimited list of key usage, allowed values are
-        "encrypt" and "sign".  This is used to generate the key flags.
-        Please make sure that the algorithm is capable of this usage.
-     Subkey-Type: <algo-number>|<algo-string>
-       This generates a secondary key.  Currently only one subkey
-       can be handled.
-     Subkey-Length: <length-in-bits>
-       Length of the subkey in bits.  Default is 1024.
-     Subkey-Usage: <usage-list>
-        Similar to Key-Usage.
-     Passphrase: <string>
-       If you want to specify a passphrase for the secret key,
-       enter it here.  Default is not to use any passphrase.
-     Name-Real: <string>
-     Name-Comment: <string>
-     Name-Email: <string>
-       The 3 parts of a key. Remember to use UTF-8 here.
-       If you don't give any of them, no user ID is created.
-     Expire-Date: <iso-date>|(<number>[d|w|m|y])
-       Set the expiration date for the key (and the subkey).  It
-       may either be entered in ISO date format (2000-08-15) or as
-       number of days, weeks, month or years. Without a letter days
-       are assumed.
-     Preferences: <string>
-        Set the cipher, hash, and compression preference values for
-       this key.  This expects the same type of string as "setpref"
-       in the --edit menu.
-     Revoker: <algo>:<fpr> [sensitive]
-        Add a designated revoker to the generated key.  Algo is the
-       public key algorithm of the designated revoker (i.e. RSA=1,
-       DSA=17, etc.)  Fpr is the fingerprint of the designated
-       revoker.  The optional "sensitive" flag marks the designated
-       revoker as sensitive information.  Only v4 keys may be
-       designated revokers.
-
-Here is an example:
-$ cat >foo <<EOF
-     %echo Generating a standard key
-     Key-Type: DSA
-     Key-Length: 1024
-     Subkey-Type: ELG-E
-     Subkey-Length: 1024
-     Name-Real: Joe Tester
-     Name-Comment: with stupid passphrase
-     Name-Email: joe@foo.bar
-     Expire-Date: 0
-     Passphrase: abc
-     %pubring foo.pub
-     %secring foo.sec
-     # Do a commit here, so that we can later print "done" :-)
-     %commit
-     %echo done
-EOF
-$ gpg --batch --gen-key foo
- [...]
-$ gpg --no-default-keyring --secret-keyring ./foo.sec \
-                                 --keyring ./foo.pub --list-secret-keys
-/home/wk/work/gnupg-stable/scratch/foo.sec
-------------------------------------------
-sec  1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@foo.bar>
-ssb  1024g/8F70E2C0 2000-03-09
-
+The the manual for a description.
 
 
 Layout of the TrustDB
@@ -587,17 +825,17 @@ FIXME:  The layout changed, document it here.
      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
+     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
+     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
+     1 u32  record number of keyhashtable [currently not used]
      1 u32  first free record
-     1 u32  record number of shadow directory hash table
+     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
@@ -773,59 +1011,6 @@ FIXME:  The layout changed, document it here.
 
 
 
-Packet Headers
-===============
-
-GNUPG uses PGP 2 packet headers and also understands OpenPGP packet header.
-There is one enhancement used with the old style packet headers:
-
-   CTB bits 10, the "packet-length length bits", have values listed in
-   the following table:
-
-      00 - 1-byte packet-length field
-      01 - 2-byte packet-length field
-      10 - 4-byte packet-length field
-      11 - no packet length supplied, unknown packet length
-
-   As indicated in this table, depending on the packet-length length
-   bits, the remaining 1, 2, 4, or 0 bytes of the packet structure field
-   are a "packet-length field".  The packet-length field is a whole
-   number field.  The value of the packet-length field is defined to be
-   the value of the whole number field.
-
-   A value of 11 is currently used in one place: on compressed data.
-   That is, a compressed data block currently looks like <A3 01 . .  .>,
-   where <A3>, binary 10 1000 11, is an indefinite-length packet. The
-   proper interpretation is "until the end of the enclosing structure",
-   although it should never appear outermost (where the enclosing
-   structure is a file).
-
-+  This will be changed with another version, where the new meaning of
-+  the value 11 (see below) will also take place.
-+
-+  A value of 11 for other packets enables a special length encoding,
-+  which is used in case, where the length of the following packet can
-+  not be determined prior to writing the packet; especially this will
-+  be used if large amounts of data are processed in filter mode.
-+
-+  It works like this: After the CTB (with a length field of 11) a
-+  marker field is used, which gives the length of the following datablock.
-+  This is a simple 2 byte field (MSB first) containing the amount of data
-+  following this field, not including this length field. After this datablock
-+  another length field follows, which gives the size of the next datablock.
-+  A value of 0 indicates the end of the packet. The maximum size of a
-+  data block is limited to 65534, thereby reserving a value of 0xffff for
-+  future extensions. These length markers must be inserted into the data
-+  stream just before writing the data out.
-+
-+  This 2 byte field is large enough, because the application must buffer
-+  this amount of data to prepend the length marker before writing it out.
-+  Data block sizes larger than about 32k doesn't make any sense. Note
-+  that this may also be used for compressed data streams, but we must use
-+  another packet version to tell the application that it can not assume,
-+  that this is the last packet.
-
-
 GNU extensions to the S2K algorithm
 ===================================
 S2K mode 101 is used to identify these extensions.
@@ -833,64 +1018,7 @@ 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
-
-
-Usage of gdbm files for keyrings
-================================
-    The key to store the keyblock is its fingerprint, other records
-    are used for secondary keys.  Fingerprints are always 20 bytes
-    where 16 bit fingerprints are appended with zero.
-    The first byte of the key gives some information on the type of the
-    key.
-      1 = key is a 20 bit fingerprint (16 bytes fpr are padded with zeroes)
-         data is the keyblock
-      2 = key is the complete 8 byte keyid
-         data is a list of 20 byte fingerprints
-      3 = key is the short 4 byte keyid
-         data is a list of 20 byte fingerprints
-      4 = key is the email address
-         data is a list of 20 byte fingerprints
-
-    Data is prepended with a type byte:
-      1 = keyblock
-      2 = list of 20 byte padded fingerprints
-      3 = list of list fingerprints (but how to we key them?)
-
-
-
-Pipemode
-========
-This mode can be used to perform multiple operations with one call to
-gpg. It comes handy in cases where you have to verify a lot of
-signatures. Currently we support only detached signatures.  This mode
-is a kludge to avoid running gpg n daemon mode and using Unix Domain
-Sockets to pass the data to it.  There is no easy portable way to do
-this under Windows, so we use plain old pipes which do work well under
-Windows.  Because there is no way to signal multiple EOFs in a pipe we
-have to embed control commands in the data stream: We distinguish
-between a data state and a control state.  Initially the system is in
-data state but it won't accept any data.  Instead it waits for
-transition to control state which is done by sending a single '@'
-character.  While in control state the control command os expected and
-this command is just a single byte after which the system falls back
-to data state (but does not necesary accept data now).  The simplest
-control command is a '@' which just inserts this character into the
-data stream.
-
-Here is the format we use for detached signatures:
-"@<"  - Begin of new stream
-"@B"  - Detached signature follows.
-        This emits a control packet (1,'B')
-<detached_signature>
-"@t"  - Signed text follows. 
-        This emits the control packet (2, 'B')
-<signed_text>
-"@."  - End of operation. The final control packet forces signature
-        verification
-"@>"  - End of stream   
-
-
-
+  1002 - a stub to access smartcards (not used in 1.2.x)
 
 
 
@@ -907,8 +1035,16 @@ Other Notes
       to keep them small.
 
 
+OIDs below the GnuPG arc:
+=========================
 
-
+ 1.3.6.1.4.1.11591.2          GnuPG
+ 1.3.6.1.4.1.11591.2.1          notation
+ 1.3.6.1.4.1.11591.2.1.1          pkaAddress
+ 1.3.6.1.4.1.11591.2.2          X.509 extensions
+ 1.3.6.1.4.1.11591.2.2.1          standaloneCertificate
+ 1.3.6.1.4.1.11591.2.2.2          wellKnownPrivateKey
+ 1.3.6.1.4.1.11591.2.12242973   invalid encoded OID
 
 
 
@@ -988,4 +1124,3 @@ A better way to do this would be a request like:
 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.
-