* DETAILS: Document PLAINTEXT and PLAINTEXT_LENGTH.
authorDavid Shaw <dshaw@jabberwocky.com>
Tue, 29 Jun 2004 01:48:01 +0000 (01:48 +0000)
committerDavid Shaw <dshaw@jabberwocky.com>
Tue, 29 Jun 2004 01:48:01 +0000 (01:48 +0000)
* gpg.sgml: Clarify that --min-cert-level disregards level 1 certs by
default.  Clarify include-revoked a bit to note that keyservers might not
be accurate.  Note that --charset is --display-charset. Some language
tweaks for --simple-sk-checksum (Debian 251795). Note the PGP silliness
with preferred keyserver subpackets causing PGP/MIME.

doc/ChangeLog
doc/DETAILS
doc/gpg.sgml

index f527df5..db7ec45 100644 (file)
@@ -1,3 +1,14 @@
+2004-06-28  David Shaw  <dshaw@jabberwocky.com>
+
+       * DETAILS: Document PLAINTEXT and PLAINTEXT_LENGTH.
+
+       * gpg.sgml: Clarify that --min-cert-level disregards level 1 certs
+       by default.  Clarify include-revoked a bit to note that keyservers
+       might not be accurate.  Note that --charset is --display-charset.
+       Some language tweaks for --simple-sk-checksum (Debian 251795).
+       Note the PGP silliness with preferred keyserver subpackets causing
+       PGP/MIME.
+
 2004-05-21  David Shaw  <dshaw@jabberwocky.com>
 
        * gpg.sgml: Document --edit-key "keyserver" command,
index c87eae3..6236808 100644 (file)
@@ -518,6 +518,20 @@ more arguments in future versions.
            2 = Request removal of a card.
            3 = Card with serialnumber detected
 
+    PLAINTEXT <format> <timestamp>
+        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.
+
+    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.
+
 
 Format of the "--attribute-fd" output
 =====================================
index ce181ca..c2d3048 100644 (file)
@@ -502,7 +502,9 @@ will not be used by GnuPG.
     <listitem><para>
 Set a preferred keyserver for the specified user ID(s).  This allows
 other users to know where you prefer they get your key from.  See
---keyserver-option honor-keyserver-url.
+--keyserver-option honor-keyserver-url.  Note that some versions of
+PGP interpret the presence of a keyserver URL as an instruction to
+enable PGP/MIME mail encoding.
 </para></listitem></varlistentry>
     <varlistentry>
     <term>toggle</term>
@@ -1052,8 +1054,8 @@ this option.  This option defaults to yes.
 <term>--min-cert-level</term>
 <listitem><para>
 When building the trust database, disregard any signatures with a
-certification level below this.  Defaults to 1, which accepts all
-signatures.
+certification level below this.  Defaults to 2, which disregards level
+signatures.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1178,9 +1180,12 @@ keyserver types, some common options are:
 <term>include-revoked</term>
 <listitem><para>
 When searching for a key with --search-keys, include keys that are
-marked on the keyserver as revoked.  Note that this option is always
-set when using the NAI HKP keyserver, as this keyserver does not
-differentiate between revoked and unrevoked keys.
+marked on the keyserver as revoked.  Note that not all keyservers
+differentiate between revoked and unrevoked keys, and for such
+keyservers this option is meaningless.  Note also that most keyservers
+do not have cryptographic verification of key revocations, and so
+turning this option off may result in skipping keys that are
+incorrectly marked as revoked.  Defaults to on.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1570,13 +1575,13 @@ $GNUPGHOME.
 
 
 <varlistentry>
-<term>--charset &ParmName;</term>
+<term>--display-charset &ParmName;</term>
 <listitem><para>
 Set the name of the native character set.  This is used to convert
 some informational strings like user IDs to the proper UTF-8
 encoding. If this option is not used, the default character set is
 determined from the current locale.  A verbosity level of 3 shows the
-used one.  Valid values for &ParmName; are:</para>
+chosen set.  Valid values for &ParmName; are:</para>
 <variablelist>
 <varlistentry>
 <term>iso-8859-1</term><listitem><para>This is the Latin 1 set.</para></listitem>
@@ -1603,11 +1608,11 @@ that the OS uses native UTF-8 encoding.</para></listitem>
 <term>--utf8-strings</term>
 <term>--no-utf8-strings</term>
 <listitem><para>
-Assume that the arguments are already given as UTF8 strings.  The default
-(--no-utf8-strings)
-is to assume that arguments are encoded in the character set as specified
-by --charset. These options affect all following arguments.  Both options may
-be used multiple times.
+Assume that command line arguments are given as UTF8 strings.  The
+default (--no-utf8-strings) is to assume that arguments are encoded in
+the character set as specified by --display-charset. These options
+affect all following arguments.  Both options may be used multiple
+times.
 </para></listitem></varlistentry>
 
 
@@ -1732,9 +1737,9 @@ Put the name value pair into the signature as notation data.
 must contain a '@' character.  This is to help prevent pollution of
 the IETF reserved notation namespace.  The --expert flag overrides the
 '@' check.  &ParmValue; may be any printable string; it will be
-encoded in UTF8, so you should check that your --charset is set
-correctly.  If you prefix &ParmName; with an exclamation mark (!), the
-notation data will be flagged as critical (rfc2440:5.2.3.15).
+encoded in UTF8, so you should check that your --display-charset is
+set correctly.  If you prefix &ParmName; with an exclamation mark (!),
+the notation data will be flagged as critical (rfc2440:5.2.3.15).
 --sig-notation sets a notation for data signatures.  --cert-notation
 sets a notation for key signatures (certifications).  --set-notation
 sets both.
@@ -1936,14 +1941,14 @@ conventional encryption.
 <term>--simple-sk-checksum</term>
 <listitem><para>
 Secret keys are integrity protected by using a SHA-1 checksum.  This
-method will be part of an enhanced OpenPGP specification but GnuPG
-already uses it as a countermeasure against certain attacks.  Old
-applications don't understand this new format, so this option may be
-used to switch back to the old behaviour.  Using this this option
-bears a security risk.  Note that using this option only takes effect
-when the secret key is encrypted - the simplest way to make this
-happen is to change the passphrase on the key (even changing it to the
-same value is acceptable).
+method is part of the upcoming enhanced OpenPGP specification but
+GnuPG already uses it as a countermeasure against certain attacks.
+Old applications don't understand this new format, so this option may
+be used to switch back to the old behaviour.  Using this option bears
+a security risk.  Note that using this option only takes effect when
+the secret key is encrypted - the simplest way to make this happen is
+to change the passphrase on the key (even changing it to the same
+value is acceptable).
 </para></listitem></varlistentry>
 
 
@@ -2368,11 +2373,11 @@ verification is not needed.
 <term>--with-colons</term>
 <listitem><para>
 Print key listings delimited by colons.  Note that the output will be
-encoded in UTF-8 regardless of any --charset setting.  This format is
-useful when GnuPG is called from scripts and other programs as it is
-easily machine parsed.  The details of this format are documented in
-the file doc/DETAILS, which is included in the GnuPG source
-distribution.
+encoded in UTF-8 regardless of any --display-charset setting.  This
+format is useful when GnuPG is called from scripts and other programs
+as it is easily machine parsed.  The details of this format are
+documented in the file doc/DETAILS, which is included in the GnuPG
+source distribution.
 </para></listitem></varlistentry>