Reworked passing of envars to Pinentry.
[gnupg.git] / doc / gpgsm.texi
index d936b3e..e784f71 100644 (file)
@@ -77,21 +77,22 @@ only one command is allowed.
 @table @gnupgtabopt
 @item --version
 @opindex version
-Print the program version and licensing information.  Not that you can
-abbreviate this command.
+Print the program version and licensing information.  Note that you
+cannot abbreviate this command.
 
 @item --help, -h
 @opindex help
 Print a usage message summarizing the most usefule command-line options.
-Not that you can abbreviate this command.
+Note that you cannot abbreviate this command.
 
 @item --warranty
 @opindex warranty
-Print warranty information.
+Print warranty information.  Note that you cannot abbreviate this
+command.
 
 @item --dump-options
 @opindex dump-options
-Print a list of all available options and commands.  Not that you can
+Print a list of all available options and commands.  Note that you cannot
 abbreviate this command.
 @end table
 
@@ -164,9 +165,10 @@ use @samp{--help} to get a list of supported operations.
 @table @gnupgtabopt
 @item --gen-key
 @opindex gen-key
-This command allows the interactive creation of a certifcate signing
-request.  It is commonly used along with the @option{--output} option to
-save the created CSR into a file.
+This command allows the creation of a certificate signing request.  It
+is commonly used along with the @option{--output} option to save the
+created CSR into a file.  If used with the @option{--batch} a parameter
+file is used to create the CSR.
 
 @item --list-keys
 @itemx -k 
@@ -224,7 +226,13 @@ checked right before it is used.
 
 @item --delete-keys @var{pattern}
 @opindex delete-keys
-Delete the keys matching @var{pattern}.
+Delete the keys matching @var{pattern}.  Note that there is no command
+to delete the secret part of the key directly.  In case you need to do
+this, you should run the command @code{gpgsm --dump-secret-keys KEYID}
+before you delete the key, copy the string of hex-digits in the
+``keygrip'' line and delete the file consisting of these hex-digits
+and the suffix @code{.key} from the @file{private-keys-v1.d} directory
+below our GnuPG home directory (usually @file{~/.gnupg}).
 
 @item --export [@var{pattern}]
 @opindex export
@@ -233,10 +241,12 @@ optional @var{pattern}. Those pattern consist of a list of user ids
 (@pxref{how-to-specify-a-user-id}).  When used along with the
 @option{--armor} option a few informational lines are prepended before
 each block.  There is one limitation: As there is no commonly agreed
-upon way to pack more than one certificate into an ASN.1 structure, the
-binary export (i.e. without using @option{armor}) works only for the
-export of one certificate.  Thus it is required to specify a
-@var{pattern} which yields exactly one certificate.
+upon way to pack more than one certificate into an ASN.1 structure,
+the binary export (i.e. without using @option{armor}) works only for
+the export of one certificate.  Thus it is required to specify a
+@var{pattern} which yields exactly one certificate.  Ephemeral
+certificate are only exported if all @var{pattern} are given as
+fingerprints or keygrips.
 
 @item --export-secret-key-p12 @var{key-id}
 @opindex export
@@ -342,6 +352,9 @@ to connect to this one.  Fallback to a pipe based server if this does
 not work.  Under Windows this option is ignored because the system dirmngr is
 always used.
 
+@item --disable-dirmngr
+Entirely disable the use of the Dirmngr.
+
 @item --no-secmem-warning
 @opindex no-secmem-warning
 Don't print a warning when the so called "secure memory" can't be used.
@@ -556,6 +569,12 @@ encryption.  For convenience the strings @code{3DES}, @code{AES} and
 @code{AES256} may be used instead of their OIDs.  The default is
 @code{3DES} (1.2.840.113549.3.7).
   
+@item --digest-algo @code{name}
+Use @code{name} as the message digest algorithm.  Usually this
+algorithm is deduced from the respective signing certificate.  This
+option forces the use of the given algorithm and may lead to severe
+interoperability problems.
+
 @end table
 
 
@@ -591,7 +610,9 @@ forth to @var{epoch} which is the number of seconds elapsed since the year
 
 @item --with-ephemeral-keys
 @opindex with-ephemeral-keys
-Include ephemeral flagged keys in the output of key listings.
+Include ephemeral flagged keys in the output of key listings.  Note
+that they are included anyway if the key specification for a listing
+is given as fingerprint or keygrip.
 
 @item --debug-level @var{level}
 @opindex debug-level
@@ -673,6 +694,10 @@ Supply the passphrase @var{string} to the gpg-protect-tool.  This
 option is only useful for the regression tests included with this
 package and may be revised or removed at any time without notice.
 
+@item --no-common-certs-import
+@opindex no-common-certs-import
+Suppress the import of common certificates on keybox creation.
+
 @end table
 
 All the long options may also be given in the configuration file after
@@ -780,6 +805,14 @@ For a reference of the help file's syntax, please see the installed
 @file{help.txt} file.
 
 
+@item com-certs.pem
+@cindex com-certs.pem
+This file is a collection of common certificates used to populated a
+newly created @file{pubring.kbx}.  An administrator may replace this
+file with a custom one.  The format is a concatenation of PEM encoded
+X.509 certificates.  This global file is installed in the data directory
+(e.g. @file{/usr/share/gnupg/qualified.txt}).
+
 @end table
 
 @c man:.RE
@@ -789,7 +822,7 @@ start up with a working configuration.  For existing users the a small
 helper script is provided to create these files (@pxref{addgnupghome}).
 
 For internal purposes gpgsm creates and maintaines a few other files;
-They all live in in the current home directory (@pxref{option
+they all live in in the current home directory (@pxref{option
 --homedir}).  Only @command{gpgsm} may modify these files.
 
 
@@ -799,7 +832,7 @@ They all live in in the current home directory (@pxref{option
 This a database file storing the certificates as well as meta
 information.  For debugging purposes the tool @command{kbxutil} may be
 used to show the internal structure of this file.
-      
+
 @item random_seed
 @cindex random_seed
 This content of this file is used to maintain the internal state of the