dirmngr: Make t-http.c work again with gnutls.
[gnupg.git] / doc / gpgsm.texi
index 4e67d75..b92eaea 100644 (file)
@@ -85,7 +85,7 @@ cannot abbreviate this command.
 @item --help, -h
 @opindex help
 Print a usage message summarizing the most useful command-line options.
-Note that you can abbreviate this command.
+Note that you cannot abbreviate this command.
 
 @item --warranty
 @opindex warranty
@@ -165,7 +165,9 @@ use @samp{--help} to get a list of supported operations.
 @subsection How to manage the certificates and keys
 
 @table @gnupgtabopt
-@item --gen-key
+@item --generate-key
+@opindex generate-key
+@itemx --gen-key
 @opindex gen-key
 This command allows the creation of a certificate signing request or a
 self-signed certificate.  It is commonly used along with the
@@ -258,7 +260,7 @@ Export the private key and the certificate identified by @var{key-id} in
 a PKCS#12 format. When used with the @code{--armor} option a few
 informational lines are prepended to the output.  Note, that the PKCS#12
 format is not very secure and this command is only provided if there is
-no other way to exchange the private key. (@xref{option --p12-charset})
+no other way to exchange the private key. (@xref{option --p12-charset}.)
 
 @item --export-secret-key-p8 @var{key-id}
 @itemx --export-secret-key-raw @var{key-id}
@@ -283,7 +285,9 @@ Read information about the private keys from the smartcard and import
 the certificates from there.  This command utilizes the @command{gpg-agent}
 and in turn the @command{scdaemon}.
 
-@item --passwd @var{user_id}
+@item --change-passphrase @var{user_id}
+@opindex change-passphrase
+@itemx --passwd @var{user_id}
 @opindex passwd
 Change the passphrase of the private key belonging to the certificate
 specified as @var{user_id}.  Note, that changing the passphrase/PIN of a
@@ -569,7 +573,7 @@ When doing a key listing, do a full validation check for each key and
 print the result.  This is usually a slow operation because it
 requires a CRL lookup and other operations.
 
-When used along with --import, a validation of the certificate to
+When used along with @option{--import}, a validation of the certificate to
 import is done and only imported if it succeeds the test.  Note that
 this does not affect an already available certificate in the DB.
 This option is therefore useful to simply verify a certificate.
@@ -581,7 +585,7 @@ certificate.
 
 @item --with-keygrip
 Include the keygrip in standard key listings.  Note that the keygrip is
-always listed in --with-colons mode.
+always listed in @option{--with-colons} mode.
 
 @item --with-secret
 @opindex with-secret
@@ -594,7 +598,7 @@ done with @code{--with-colons}.
 @c *************  CMS OPTIONS  ***************
 @c *******************************************
 @node CMS Options
-@subsection How to change how the CMS is created.
+@subsection How to change how the CMS is created
 
 @table @gnupgtabopt
 @item --include-certs @var{n}
@@ -625,7 +629,7 @@ interoperability problems.
 @c ********  ESOTERIC OPTIONS  ***************
 @c *******************************************
 @node Esoteric Options
-@subsection Doing things one usually do not want to do.
+@subsection Doing things one usually do not want to do
 
 
 @table @gnupgtabopt
@@ -636,7 +640,7 @@ Sometimes signatures are broken in that they announce a different digest
 algorithm than actually used.  @command{gpgsm} uses a one-pass data
 processing model and thus needs to rely on the announced digest
 algorithms to properly hash the data.  As a workaround this option may
-be used to tell gpg to also hash the data using the algorithm
+be used to tell @command{gpgsm} to also hash the data using the algorithm
 @var{name}; this slows processing down a little bit but allows verification of
 such broken signatures.  If @command{gpgsm} prints an error like
 ``digest algo 8 has not been enabled'' you may want to try this option,
@@ -703,7 +707,7 @@ memory allocation
 @item 6  (64)
 caching
 @item 7  (128)
-show memory statistics.
+show memory statistics
 @item 9  (512)
 write hashed data to files named @code{dbgmd-000*}
 @item 10 (1024)
@@ -834,7 +838,7 @@ They are defined as certificates capable of creating legally binding
 signatures in the same way as handwritten signatures are.  Comments
 start with a hash mark and empty lines are ignored.  Lines do have a
 length limit but this is not a serious limitation as the format of the
-entries is fixed and checked by gpgsm: A non-comment line starts with
+entries is fixed and checked by @command{gpgsm}: A non-comment line starts with
 optional whitespace, followed by exactly 40 hex characters, white space
 and a lowercased 2 letter country code.  Additional data delimited with
 by a white space is current ignored but might late be used for other
@@ -893,7 +897,7 @@ into the directory @file{/etc/skel/.gnupg/} so that newly created users
 start up with a working configuration.  For existing users a small
 helper script is provided to create these files (@pxref{addgnupghome}).
 
-For internal purposes gpgsm creates and maintains a few other files;
+For internal purposes @command{gpgsm} creates and maintains a few other files;
 they all live in in the current home directory (@pxref{option
 --homedir}).  Only @command{gpgsm} may modify these files.
 
@@ -1005,7 +1009,7 @@ this is a missing certificate.
 @node CSR and certificate creation
 @subsection CSR and certificate creation
 
-The command @option{--gen-key} may be used along with the option
+The command @option{--generate-key} may be used along with the option
 @option{--batch} to either create a certificate signing request (CSR)
 or an X.509 certificate.  This is controlled by a parameter file; the
 format of this file is as follows:
@@ -1114,7 +1118,7 @@ integer of arbitrary length.  The special value @samp{random} can be
 used to create a 64 bit random serial number.
 
 @item Issuer-DN: @var{issuer-name}
-This is the DN name of the issuer in rfc2253 format.  If it is not set
+This is the DN name of the issuer in RFC-2253 format.  If it is not set
 it will default to the subject DN and a special GnuPG extension will
 be included in the certificate to mark it as a standalone certificate.
 
@@ -1153,7 +1157,7 @@ default is @samp{sha256}.
 @c ***************           *****************
 @c *******************************************
 @node GPGSM Protocol
-@section The Protocol the Server Mode Uses.
+@section The Protocol the Server Mode Uses
 
 Description of the protocol used to access @command{GPGSM}.
 @command{GPGSM} does implement the Assuan protocol and in addition
@@ -1230,8 +1234,8 @@ message). Obviously the pipe must be open at that point, the server
 establishes its own end.  If the server returns an error the client
 should consider this session failed.
 
-The option armor encodes the output in @acronym{PEM} format, the
-@code{--base64} option applies just a base 64 encoding.  No option
+The option @option{--armor} encodes the output in @acronym{PEM} format, the
+@option{--base64} option applies just a base-64 encoding.  No option
 creates binary output (@acronym{BER}).
 
 The actual encryption is done using the command
@@ -1257,19 +1261,19 @@ closed.
 @subsection Decrypting a message
 
 Input and output FDs are set the same way as in encryption, but
-@code{INPUT} refers to the ciphertext and output to the plaintext. There
+@code{INPUT} refers to the ciphertext and @code{OUTPUT} to the plaintext. There
 is no need to set recipients.  @command{GPGSM} automatically strips any
 @acronym{S/MIME} headers from the input, so it is valid to pass an
 entire MIME part to the INPUT pipe.
 
-The encryption is done by using the command
+The decryption is done by using the command
 
 @example
   DECRYPT
 @end example
 
 It performs the decrypt operation after doing some check on the internal
-state. (e.g. that all needed data has been set).  Because it utilizes
+state (e.g. that all needed data has been set).  Because it utilizes
 the GPG-Agent for the session key decryption, there is no need to ask
 the client for a protecting passphrase - GpgAgent takes care of this by
 requesting this from the user.
@@ -1297,8 +1301,8 @@ requested, only the signature is written.
   SIGN [--detached]
 @end example
 
-Sign the data set with the INPUT command and write it to the sink set by
-OUTPUT.  With @code{--detached}, a detached signature is created
+Sign the data set with the @code{INPUT} command and write it to the sink set by
+@code{OUTPUT}.  With @code{--detached}, a detached signature is created
 (surprise).
 
 The key used for signing is the default one or the one specified in
@@ -1422,14 +1426,14 @@ required: Spaces are to be translated into "+" or into "%20"; in turn
 this requires that the usual escape quoting rules are done.
 
 If the @option{--data} option has not been given, the format of the
-output depends on what was set with the OUTPUT command.  When using
+output depends on what was set with the @code{OUTPUT} command.  When using
 @acronym{PEM} encoding a few informational lines are prepended.
 
-If the @option{--data} has been given, a target set via OUTPUT is
+If the @option{--data} has been given, a target set via @code{OUTPUT} is
 ignored and the data is returned inline using standard
 @code{D}-lines. This avoids the need for an extra file descriptor.  In
 this case the options @option{--armor} and @option{--base64} may be used
-in the same way as with the OUTPUT command.
+in the same way as with the @code{OUTPUT} command.
 
 
 @node GPGSM IMPORT
@@ -1469,7 +1473,7 @@ The certificates must be specified unambiguously otherwise an error is
 returned.
 
 @node GPGSM GETAUDITLOG
-@subsection Retrieve an audit log.
+@subsection Retrieve an audit log
 @anchor{gpgsm-cmd getauditlog}
 
 This command is used to retrieve an audit log.
@@ -1479,7 +1483,7 @@ GETAUDITLOG [--data] [--html]
 @end example
 
 If @option{--data} is used, the audit log is send using D-lines
-instead of being sent to the file descriptor given by an OUTPUT
+instead of being sent to the file descriptor given by an @code{OUTPUT}
 command.  If @option{--html} is used, the output is formatted as an
 XHTML block. This is designed to be incorporated into a HTML
 document.
@@ -1512,7 +1516,7 @@ started with option @option{--disable-dirmngr}.
 @end table
 
 @node GPGSM OPTION
-@subsection  Session options.
+@subsection  Session options
 
 The standard Assuan option handler supports these options.
 
@@ -1570,7 +1574,7 @@ signers certicate and all other positive values include up to
 @item list-to-output
 If @var{value} is true the output of the list commands
 (@pxref{gpgsm-cmd listkeys}) is written to the file descriptor set
-with the last OUTPUT command.  If @var{value} is false the output is
+with the last @code{OUTPUT} command.  If @var{value} is false the output is
 written via data lines; this is the default.
 
 @item with-validation