* DETAILS: Details for --list-config.
[gnupg.git] / doc / DETAILS
index 8734cc5..2a11722 100644 (file)
@@ -36,6 +36,7 @@ record.
            pkd = public key data (special field format, see below)
             grp = reserved for gpgsm
             rvk = revocation key
+            tru = trust database information
 
  2. Field:  A letter describing the calculated trust. This is a single
            letter, but be prepared that additional information may follow
@@ -43,27 +44,43 @@ record.
                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
-               q = Undefined (no value assigned)
+               - = Unknown trust (i.e. no value assigned)
+               q = Undefined trust
+                   '-' 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 full trusted.
-               u = The key is ultimately trusted; this is only used for
-                   keys for which the secret key is also available.
+               f = The key is fully trusted
+               u = The key is ultimately trusted.  This often means
+                   that the secret key is available, but any key may
+                   be marked as ultimately trusted.
  3. Field:  length of key in bits.
  4. Field:  Algorithm: 1 = RSA
                       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 dae 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 format
+            is be scannning 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.
@@ -81,9 +98,12 @@ record.
                 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.  
+                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
@@ -93,8 +113,17 @@ record.
             algorithm as gpgsm uses.
             For "uid" recods this lists the preferences n the sameway the 
             -edit 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)
 
 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
@@ -109,6 +138,21 @@ 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)
 
+
+The "tru" trust database records have the fields:
+
+ 1: 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.
+
+ 2: Trust model.  This is always zero (i.e. "Classic") in this version
+    of GnuPG.
+ 3: Date trustdb was created in seconds since 1/1/1970.
+ 4: Date trustdb will expire in seconds since 1/1/1970.
+
  
 
 Format of the "--status-fd" output
@@ -136,6 +180,11 @@ more arguments in future versions.
        made by an expired key. The username is the primary one
        encoded in UTF-8 and %XX escaped.
 
+    REVKEYSIG  <long keyid>  <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.
+
     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
@@ -149,15 +198,30 @@ more arguments in future versions.
        public key. The other fields give more information about
        this signature.  sig_class is a 2 byte hex-value.
 
-    VALIDSIG   <fingerprint in hex> <sig_creation_date> <sig-timestamp>
-               <expire-timestamp>
+        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.
 
-       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").
+    VALIDSIG   <fingerprint in hex> <sig_creation_date> <sig-timestamp>
+               <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.
+
+        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
@@ -167,6 +231,11 @@ more arguments in future versions.
        unique ids - others may yield duplicated ones when they
        have been created in the same second.
 
+        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 keyid.
        keytype is the numerical value of the public key algorithm,
@@ -201,6 +270,10 @@ more arguments in future versions.
        The key has expired.  expire-timestamp is the expiration time
        in seconds after the epoch.
 
+        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.
 
@@ -267,8 +340,27 @@ more arguments in future versions.
     IMPORTED   <long keyid>  <username>
        The keyid and name of the signature just imported
 
+    IMPORT_OK  <reason> [<fingerprint>]
+        The key with the primary key's FINGERPRINT has been imported.
+        Reason flags:
+          0 := Not actually changed
+          1 := Entirely new key.
+          2 := New user IDs
+          4 := New signatures
+          8 := New subkeys 
+         16 := Contains private key.
+        The flags may be ORed.
+
+    IMPORT_PROBLEM <reason> [<fingerprint>]
+        Issued for each import failure.  Reason codes are:
+          0 := "No specific reason given".
+          1 := "Invalid Certificate".
+          2 := "Issuer Certificate missing".
+          3 := "Certificate Chain too long".
+          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>
+       <n_uids> <n_subk> <n_sigs> <n_revoc> <sec_read> <sec_imported> <sec_dups> <not_imported>
        Final statistics on import process (this is one long line)
 
     FILE_START <what> <filename>
@@ -312,12 +404,18 @@ more arguments in future versions.
                   'S' = standard
                   (only the first character should be checked)
            class: 2 hex digits with the signature class
+
+        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>
+    KEY_CREATED <type> <fingerprint>
         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.
 
     SESSION_KEY  <algo>:<hexdigits>
        The session key used to decrypt the message.  This message will
@@ -346,6 +444,17 @@ more arguments in future versions.
           0 := "No specific reason given".
           1 := "Not Found"
           2 := "Ambigious specification"
+          3 := "Wrong key usage"
+          4 := "Key revoked"
+          5 := "Key expired"
+          6 := "No CRL known"
+          7 := "CRL too old"
+          8 := "Policy mismatch"
+          9 := "Not a secret key"
+        10 := "Key not trusted"
+
+        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.
@@ -378,6 +487,89 @@ more arguments in future versions.
                0x02 = this attribute packet is revoked
                0x04 = this attribute packet is expired
 
+    STATUSCTRL <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.
+           2 = Request removal of a card.
+           3 = Card with serialnumber detected
+
+
+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 2440bis, but 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-2440.
+
+   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-2440.
+
+   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-2440.
+
+   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-2440.
+
+   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
 ==============
@@ -515,10 +707,10 @@ $ cat >foo <<EOF
      %commit
      %echo done
 EOF
-$ gpg --batch --gen-key -a foo
+$ gpg --batch --gen-key foo
  [...]
-$ gpg --no-default-keyring --secret-keyring foo.sec \
-                                 --keyring foo.pub --list-secret-keys
+$ 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>
@@ -551,17 +743,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
@@ -797,33 +989,13 @@ 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?)
-
+  1002 - a stub to access smartcards (not used in 1.2.x)
 
 
 Pipemode
 ========
+NOTE:  This is deprecated and will be removed in future versions.
+
 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