gpg: Synchronize translation template.
[gnupg.git] / doc / gpgsm.texi
index 7bfbc9d..2bcbec5 100644 (file)
@@ -2,6 +2,8 @@
 @c This is part of the GnuPG manual.
 @c For copying conditions, see the file gnupg.texi.
 
+@include defs.inc
+
 @node Invoking GPGSM
 @chapter Invoking GPGSM
 @cindex GPGSM command options
@@ -165,20 +167,12 @@ use @samp{--help} to get a list of supported operations.
 @table @gnupgtabopt
 @item --gen-key
 @opindex gen-key
-@ifclear gpgtwoone
--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.
-@end ifclear
-@ifset gpgtwoone
 This command allows the creation of a certificate signing request or a
 self-signed certificate.  It is commonly used along with the
 @option{--output} option to save the created CSR or certificate into a
 file.  If used with the @option{--batch} a parameter file is used to
 create the CSR or certificate and it is further possible to create
 non-self-signed certificates.
-@end ifset
 
 @item --list-keys
 @itemx -k
@@ -259,13 +253,24 @@ certificate are only exported if all @var{pattern} are given as
 fingerprints or keygrips.
 
 @item --export-secret-key-p12 @var{key-id}
-@opindex export
+@opindex export-secret-key-p12
 Export the private key and the certificate identified by @var{key-id} in
-a PKCS#12 format. When using along with the @code{--armor} option a few
+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. (@pxref{option --p12-charset})
 
+@item --export-secret-key-p8 @var{key-id}
+@itemx --export-secret-key-raw @var{key-id}
+@opindex export-secret-key-p8
+@opindex export-secret-key-raw
+Export the private key of the certificate identified by @var{key-id}
+with any encryption stripped.  The @code{...-raw} command exports in
+PKCS#1 format; the @code{...-p8} command exports in PKCS#8 format.
+When used with the @code{--armor} option a few informational lines are
+prepended to the output.  These commands are useful to prepare a key
+for use on a TLS server.
+
 @item --import [@var{files}]
 @opindex import
 Import the certificates from the PEM or binary encoded files as well as
@@ -304,7 +309,7 @@ and to change the default configuration.
 * Certificate Options::     Certificate related options.
 * Input and Output::        Input and Output.
 * CMS Options::             How to change how the CMS is created.
-* Esoteric Options::        Doing things one usually don't want to do.
+* Esoteric Options::        Doing things one usually do not want to do.
 @end menu
 
 
@@ -319,6 +324,7 @@ in the option file.
 
 @table @gnupgtabopt
 
+@anchor{gpgsm-option --options}
 @item --options @var{file}
 @opindex options
 Reads configuration from @var{file} instead of from the default
@@ -344,16 +350,16 @@ Change the default name of the policy file to @var{filename}.
 @item --agent-program @var{file}
 @opindex agent-program
 Specify an agent program to be used for secret key operations.  The
-default value is the @file{/usr/local/bin/gpg-agent}.  This is only used
-as a fallback when the environment variable @code{GPG_AGENT_INFO} is not
-set or a running agent can't be connected.
+default value is determined by running the command @command{gpgconf}.
+Note that the pipe symbol (@code{|}) is used for a regression test
+suite hack and may thus not be used in the file name.
 
 @item --dirmngr-program @var{file}
-@opindex dirmnr-program
+@opindex dirmngr-program
 Specify a dirmngr program to be used for @acronym{CRL} checks.  The
-default value is @file{/usr/sbin/dirmngr}.  This is only used as a
+default value is @file{@value{BINDIR}/dirmngr}.  This is only used as a
 fallback when the environment variable @code{DIRMNGR_INFO} is not set or
-a running dirmngr can't be connected.
+a running dirmngr cannot be connected.
 
 @item --prefer-system-dirmngr
 @opindex prefer-system-dirmngr
@@ -365,9 +371,17 @@ always used.
 @item --disable-dirmngr
 Entirely disable the use of the Dirmngr.
 
+@item --no-autostart
+@opindex no-autostart
+Do not start the gpg-agent or the dirmngr if it has not yet been
+started and its service is required.  This option is mostly useful on
+machines where the connection to gpg-agent has been redirected to
+another machines.  If dirmngr is required on the remote machine, it
+may be started manually using @command{gpgconf --launch dirmngr}.
+
 @item --no-secmem-warning
 @opindex no-secmem-warning
-Don't print a warning when the so called "secure memory" can't be used.
+Do not print a warning when the so called "secure memory" cannot be used.
 
 @item --log-file @var{file}
 @opindex log-file
@@ -407,7 +421,7 @@ By default the @acronym{CRL} for trusted root certificates are checked
 like for any other certificates.  This allows a CA to revoke its own
 certificates voluntary without the need of putting all ever issued
 certificates into a CRL.  The disable option may be used to switch this
-extra check off.  Due to the caching done by the Dirmngr, there won't be
+extra check off.  Due to the caching done by the Dirmngr, there will not be
 any noticeable performance gain.  Note, that this also disables possible
 OCSP checks for trusted root certificates.  A more specific way of
 disabling this check is by adding the ``relax'' keyword to the root CA
@@ -428,12 +442,12 @@ command.  This option should not be used in a configuration file.
 @itemx --disable-ocsp
 @opindex enable-ocsp
 @opindex disable-ocsp
-Be default @acronym{OCSP} checks are disabled.  The enable option may
+By default @acronym{OCSP} checks are disabled.  The enable option may
 be used to enable OCSP checks via Dirmngr.  If @acronym{CRL} checks
 are also enabled, CRLs will be used as a fallback if for some reason an
-OCSP request won't succeed.  Note, that you have to allow OCSP
+OCSP request will not succeed.  Note, that you have to allow OCSP
 requests in Dirmngr's configuration too (option
-@option{--allow-ocsp} and configure dirmngr properly.  If you don't do
+@option{--allow-ocsp}) and configure Dirmngr properly.  If you do not do
 so you will get the error code @samp{Not supported}.
 
 @item --auto-issuer-key-retrieve
@@ -448,13 +462,15 @@ will not have on your local keybox), the operator can tell both your IP
 address and the time when you verified the signature.
 
 
+@anchor{gpgsm-option --validation-model}
 @item --validation-model @var{name}
 @opindex validation-model
 This option changes the default validation model.  The only possible
-values are "shell" (which is the default) and "chain" which forces the
-use of the chain model.  The chain model is also used if an option in
-the @file{trustlist.txt} or an attribute of the certificate requests it.
-However the standard model (shell) is in that case always tried first.
+values are "shell" (which is the default), "chain" which forces the
+use of the chain model and "steed" for a new simplified model.  The
+chain model is also used if an option in the @file{trustlist.txt} or
+an attribute of the certificate requests it.  However the standard
+model (shell) is in that case always tried first.
 
 @item --ignore-cert-extension @var{oid}
 @opindex ignore-cert-extension
@@ -463,7 +479,7 @@ Add @var{oid} to the list of ignored certificate extensions.  The
 @code{2.5.29.3}.  This option may be used more than once.  Critical
 flagged certificate extensions matching one of the OIDs in the list
 are treated as if they are actually handled and thus the certificate
-won't be rejected due to an unknown critical extension.  Use this
+will not be rejected due to an unknown critical extension.  Use this
 option with care because extensions are usually flagged as critical
 for a reason.
 
@@ -505,7 +521,7 @@ Assume the input data is binary encoded.
 PKCS#12 files.  This option may be used to force the passphrase to be
 encoded in the specified encoding @var{name}.  This is useful if the
 application used to import the key uses a different encoding and thus
-won't be able to import a file generated by @command{gpgsm}.  Commonly
+will not be able to import a file generated by @command{gpgsm}.  Commonly
 used values for @var{name} are @code{Latin1} and @code{CP850}.  Note
 that @command{gpgsm} itself automagically imports any file with a
 passphrase encoded to the most commonly used encodings.
@@ -539,6 +555,7 @@ may be given (@pxref{how-to-specify-a-user-id}).
 Write output to @var{file}.  The default is to write it to stdout.
 
 
+@anchor{gpgsm-option --with-key-data}
 @item --with-key-data
 @opindex with-key-data
 Displays extra information with the @code{--list-keys} commands.  Especially
@@ -546,6 +563,7 @@ a line tagged @code{grp} is printed which tells you the keygrip of a
 key.  This string is for example used as the file name of the
 secret key.
 
+@anchor{gpgsm-option --with-validation}
 @item --with-validation
 @opindex with-validation
 When doing a key listing, do a full validation check for each key and
@@ -566,6 +584,11 @@ certificate.
 Include the keygrip in standard key listings.  Note that the keygrip is
 always listed in --with-colons mode.
 
+@item --with-secret
+@opindex with-secret
+Include info about the presence of a secret key in public key listings
+done with @code{--with-colons}.
+
 @end table
 
 @c *******************************************
@@ -587,7 +610,7 @@ certificates starting with the signer cert.  The default is -2.
 Use the cipher algorithm with the ASN.1 object identifier @var{oid} for
 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).
+@code{AES} (2.16.840.1.101.3.4.1.2).
 
 @item --digest-algo @code{name}
 Use @code{name} as the message digest algorithm.  Usually this
@@ -603,7 +626,7 @@ interoperability problems.
 @c ********  ESOTERIC OPTIONS  ***************
 @c *******************************************
 @node Esoteric Options
-@subsection Doing things one usually don't want to do.
+@subsection Doing things one usually do not want to do.
 
 
 @table @gnupgtabopt
@@ -759,8 +782,8 @@ current home directory (@pxref{option --homedir}).
 This is the standard configuration file read by @command{gpgsm} on
 startup.  It may contain any valid long option; the leading two dashes
 may not be entered and the option may not be abbreviated.  This default
-name may be changed on the command line (@pxref{option
-  --options}).  You should backup this file.
+name may be changed on the command line (@pxref{gpgsm-option --options}).
+You should backup this file.
 
 
 @item policies.txt
@@ -801,7 +824,7 @@ mean that the certificate is trusted; in general the certificates listed
 in this file need to be listed also in @file{trustlist.txt}.
 
 This is a global file an installed in the data directory
-(e.g. @file{/usr/share/gnupg/qualified.txt}).  GnuPG installs a suitable
+(e.g. @file{@value{DATADIR}/qualified.txt}).  GnuPG installs a suitable
 file with root certificates as used in Germany.  As new Root-CA
 certificates may be issued over time, these entries may need to be
 updated; new distributions of this software should come with an updated
@@ -826,9 +849,9 @@ This is plain text file with a few help entries used with
 @command{gpg} and @command{gpgsm}.  The standard file has English help
 texts; to install localized versions use filenames like @file{help.LL.txt}
 with LL denoting the locale.  GnuPG comes with a set of predefined help
-files in the data directory (e.g. @file{/usr/share/gnupg/help.de.txt})
+files in the data directory (e.g. @file{@value{DATADIR}/gnupg/help.de.txt})
 and allows overriding of any help item by help files stored in the
-system configuration directory (e.g. @file{/etc/gnupg/help.de.txt}).
+system configuration directory (e.g. @file{@value{SYSCONFDIR}/help.de.txt}).
 For a reference of the help file's syntax, please see the installed
 @file{help.txt} file.
 
@@ -839,7 +862,7 @@ 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/com-certs.pem}).
+(e.g. @file{@value{DATADIR}/com-certs.pem}).
 
 @end table
 
@@ -870,8 +893,8 @@ other programs of this software too.
 
 @item S.gpg-agent
 @cindex S.gpg-agent
-If this file exists and the environment variable @env{GPG_AGENT_INFO} is
-not set, @command{gpgsm} will first try to connect to this socket for
+If this file exists
+@command{gpgsm} will first try to connect to this socket for
 accessing @command{gpg-agent} before starting a new @command{gpg-agent}
 instance.  Under Windows this socket (which in reality be a plain file
 describing a regular TCP listening port) is the standard way of
@@ -914,8 +937,8 @@ but may also be used in the standard operation mode by using the
 * CSR and certificate creation::  CSR and certificate creation.
 @end menu
 
-@node Automated signature checking,,,Unattended Usage
-@section Automated signature checking
+@node Automated signature checking
+@subsection Automated signature checking
 
 It is very important to understand the semantics used with signature
 verification.  Checking a signature is not as simple as it may sound and
@@ -952,24 +975,18 @@ of af a transfer error, a program error or tampering with the message).
   @end table
 
 @item Error verifying a signature
-For some reason the signature could not be verified, i.e. it can't be
+For some reason the signature could not be verified, i.e. it cannot be
 decided whether the signature is valid or invalid.  A common reason for
 this is a missing certificate.
 
 @end table
 
-@node CSR and certificate creation,,,Unattended Usage
-@section CSR and certificate creation
-
-@ifclear gpgtwoone
-@strong{Please notice}: The immediate creation of certificates is only
-supported by GnuPG version 2.1 or later.  With a 2.0 version you may
-only create a CSR.
-@end ifclear
+@node CSR and certificate creation
+@subsection CSR and certificate creation
 
 The command @option{--gen-key} may be used along with the option
 @option{--batch} to either create a certificate signing request (CSR)
-or an X.509 certificate. The is controlled by a parameter file; the
+or an X.509 certificate.  This is controlled by a parameter file; the
 format of this file is as follows:
 
 @itemize @bullet
@@ -1042,9 +1059,9 @@ already existing key.  Key-Length will be ignored when given.
 
 @item Key-Usage: @var{usage-list}
 Space or comma delimited list of key usage, allowed values are
-@samp{encrypt} and @samp{sign}.  This is used to generate the keyUsage
-extension.  Please make sure that the algorithm is capable of this
-usage.  Default is to allow encrypt and sign.
+@samp{encrypt}, @samp{sign} and @samp{cert}.  This is used to generate
+the keyUsage extension.  Please make sure that the algorithm is
+capable of this usage.  Default is to allow encrypt and sign.
 
 @item Name-DN: @var{subject-name}
 This is the Distinguished Name (DN) of the subject in RFC-2253 format.
@@ -1105,7 +1122,7 @@ keygrip with a @samp{&}.
 Use @var{hash-algo} for this CSR or certificate.  The supported hash
 algorithms are: @samp{sha1}, @samp{sha256}, @samp{sha384} and
 @samp{sha512}; they may also be specified with uppercase letters.  The
-default is @samp{sha1}.
+default is @samp{sha256}.
 
 @end table
 
@@ -1138,7 +1155,9 @@ Assuan manual for details.
 * GPGSM EXPORT::          Export certificates.
 * GPGSM IMPORT::          Import certificates.
 * GPGSM DELETE::          Delete certificates.
+* GPGSM GETAUDITLOG::     Retrieve an audit log.
 * GPGSM GETINFO::         Information about the process
+* GPGSM OPTION::          Session options.
 @end menu
 
 
@@ -1156,7 +1175,7 @@ Set the recipient for the encryption.  @var{userID} should be the
 internal representation of the key; the server may accept any other way
 of specification.  If this is a valid and trusted recipient the server
 does respond with OK, otherwise the return is an ERR with the reason why
-the recipient can't be used, the encryption will then not be done for
+the recipient cannot be used, the encryption will then not be done for
 this recipient.  If the policy is not to encrypt at all if not all
 recipients are valid, the client has to take care of this.  All
 @code{RECIPIENT} commands are cumulative until a @code{RESET} or an
@@ -1204,7 +1223,8 @@ It takes the plaintext from the @code{INPUT} command, writes to the
 ciphertext to the file descriptor set with the @code{OUTPUT} command,
 take the recipients from all the recipients set so far.  If this command
 fails the clients should try to delete all output currently done or
-otherwise mark it as invalid.  @command{GPGSM} does ensure that there won't be any
+otherwise mark it as invalid.  @command{GPGSM} does ensure that there
+will not be any
 security problem with leftover data on the output in this case.
 
 This command should in general not fail, as all necessary checks have
@@ -1272,7 +1292,7 @@ to the signer's key.  @var{userID} should be the
 internal representation of the key; the server may accept any other way
 of specification.  If this is a valid and trusted recipient the server
 does respond with OK, otherwise the return is an ERR with the reason why
-the key can't be used, the signature will then not be created using
+the key cannot be used, the signature will then not be created using
 this key.  If the policy is not to sign at all if not all
 keys are valid, the client has to take care of this.  All
 @code{SIGNER} commands are cumulative until a @code{RESET} is done.
@@ -1327,6 +1347,7 @@ may be issued as a progress indicator.
 
 @node GPGSM LISTKEYS
 @subsection List available keys
+@anchor{gpgsm-cmd listkeys}
 
 To list the keys in the internal database or using an external key
 provider, the command:
@@ -1426,6 +1447,23 @@ this requires that the usual escape quoting rules are done.
 The certificates must be specified unambiguously otherwise an error is
 returned.
 
+@node GPGSM GETAUDITLOG
+@subsection Retrieve an audit log.
+@anchor{gpgsm-cmd getauditlog}
+
+This command is used to retrieve an audit log.
+
+@example
+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
+command.  If @option{--html} is used, the output is formated as an
+XHTML block. This is designed to be incorporated into a HTML
+document.
+
+
 @node GPGSM GETINFO
 @subsection  Return information about the process
 
@@ -1442,10 +1480,113 @@ Return the version of the program.
 @item pid
 Return the process id of the process.
 @item agent-check
-Return success if the agent is running.
+Return OK if the agent is running.
 @item cmd_has_option @var{cmd} @var{opt}
-Return success if the command @var{cmd} implements the option @var{opt}.
+Return OK if the command @var{cmd} implements the option @var{opt}.
 The leading two dashes usually used with @var{opt} shall not be given.
+@item offline
+Return OK if the connection is in offline mode.  This may be either
+due to a @code{OPTION offline=1} or due to @command{gpgsm} being
+started with option @option{--disable-dirmngr}.
+@end table
+
+@node GPGSM OPTION
+@subsection  Session options.
+
+The standard Assuan option handler supports these options.
+
+@example
+OPTION @var{name}[=@var{value}]
+@end example
+
+These @var{name}s are recognized:
+
+@table @code
+
+@item putenv
+Change the session's environment to be passed via gpg-agent to
+Pinentry.  @var{value} is a string of the form
+@code{<KEY>[=[<STRING>]]}.  If only @code{<KEY>} is given the
+environment variable @code{<KEY>} is removed from the session
+environment, if @code{<KEY>=} is given that environment variable is
+set to the empty string, and if @code{<STRING>} is given it is set to
+that string.
+
+@item display
+Set the session environment variable @code{DISPLAY} is set to @var{value}.
+@item ttyname
+Set the session environment variable @code{GPG_TTY} is set to @var{value}.
+@item ttytype
+Set the session environment variable @code{TERM} is set to @var{value}.
+@item lc-ctype
+Set the session environment variable @code{LC_CTYPE} is set to @var{value}.
+@item lc-messages
+Set the session environment variable @code{LC_MESSAGES} is set to @var{value}.
+@item xauthority
+Set the session environment variable @code{XAUTHORITY} is set to @var{value}.
+@item pinentry-user-data
+Set the session environment variable @code{PINENTRY_USER_DATA} is set
+to @var{value}.
+
+@item include-certs
+This option overrides the command line option
+@option{--include-certs}.  A @var{value} of -2 includes all
+certificates except for the root certificate, -1 includes all
+certicates, 0 does not include any certicates, 1 includes only the
+signers certicate and all other positive values include up to
+@var{value} certificates starting with the signer cert.
+
+@item list-mode
+@xref{gpgsm-cmd listkeys}.
+
+@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
+written via data lines; this is the default.
+
+@item with-validation
+If @var{value} is true for each listed certificate the validation
+status is printed.  This may result in the download of a CRL or the
+user being asked about the trustworthiness of a root certificate.  The
+default is given by a command line option (@pxref{gpgsm-option
+--with-validation}).
+
+
+@item with-secret
+If @var{value} is true certificates with a corresponding private key
+are marked by the list commands.
+
+@item validation-model
+This option overrides the command line option
+@option{validation-model} for the session.
+(@pxref{gpgsm-option --validation-model}.)
+
+@item with-key-data
+This option globally enables the command line option
+@option{--with-key-data}.  (@pxref{gpgsm-option --with-key-data}.)
+
+@item enable-audit-log
+If @var{value} is true data to write an audit log is gathered.
+(@pxref{gpgsm-cmd getauditlog}.)
+
+@item allow-pinentry-notify
+If this option is used notifications about the launch of a Pinentry
+are passed back to the client.
+
+@item with-ephemeral-keys
+If @var{value} is true ephemeral certificates are included in the
+output of the list commands.
+
+@item no-encrypt-to
+If this option is used all keys set by the command line option
+@option{--encrypt-to} are ignored.
+
+@item offline
+If @var{value} is true or @var{value} is not given all network access
+is disabled for this session.  This is the same as the command line
+option @option{--disable-dirmngr}.
+
 @end table
 
 @mansect see also