@table @gnupgtabopt
@item --encrypt
@opindex encrypt
-Perform an encryption. The keys the data is encrypted too must be set
+Perform an encryption. The keys the data is encrypted to must be set
using the option @option{--recipient}.
@item --decrypt
Behave as a Dirmngr client issuing the request @var{command} with the
optional list of @var{args}. The output of the Dirmngr is printed
stdout. Please note that file names given as arguments should have an
-absolute file name (i.e. commencing with @code{/} because they are
+absolute file name (i.e. commencing with @code{/}) because they are
passed verbatim to the Dirmngr and the working directory of the
Dirmngr might not be the same as the one of this client. Currently it
is not possible to pass data via stdin to the Dirmngr. @var{command}
@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
@item --export-secret-key-p12 @var{key-id}
@opindex export-secret-key-p12
-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
+Export the private key and the certificate identified by @var{key-id}
+using the 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})
+format is not very secure and proper transport security should be used
+to convey the exported key. (@xref{option --p12-charset}.)
@item --export-secret-key-p8 @var{key-id}
@itemx --export-secret-key-raw @var{key-id}
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
@item --prefer-system-dirmngr
@opindex prefer-system-dirmngr
-If a system wide @command{dirmngr} is running in daemon mode, first try
-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.
+This option is obsolete and ignored.
@item --disable-dirmngr
Entirely disable the use of the Dirmngr.
@item --log-file @var{file}
@opindex log-file
When running in server mode, append all logging output to @var{file}.
+Use @file{socket://} to log to socket.
@end table
Displays extra information with the @code{--list-keys} commands. Especially
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.
+secret key. Implies @code{--with-colons}.
@anchor{gpgsm-option --with-validation}
@item --with-validation
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.
@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
@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}
@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
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
-@var{name}; this slows processing down a little bit but allows to verify
+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,
with @samp{SHA256} for @var{name}.
@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)
Pinentry the user is not prompted again if he enters a bad password.
@end table
+@item --request-origin @var{origin}
+@opindex request-origin
+Tell gpgsm to assume that the operation ultimately originated at
+@var{origin}. Depending on the origin certain restrictions are applied
+and the Pinentry may include an extra note on the origin. Supported
+values for @var{origin} are: @code{local} which is the default,
+@code{remote} to indicate a remote origin or @code{browser} for an
+operation requested by a web browser.
+
@item --no-common-certs-import
@opindex no-common-certs-import
Suppress the import of common certificates on keybox creation.
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
-optional whitespace, followed by exactly 40 hex character, white space
+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
purposes.
list but it is still the responsibility of the Administrator to check
that this list is correct.
-Everytime @command{gpgsm} uses a certificate for signing or verification
+Every time @command{gpgsm} uses a certificate for signing or verification
this file will be consulted to check whether the certificate under
question has ultimately been issued by one of these CAs. If this is the
case the user will be informed that the verified signature represents a
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;
-they all live in in the current home directory (@pxref{option
+For internal purposes @command{gpgsm} creates and maintains a few other files;
+they all live in the current home directory (@pxref{option
--homedir}). Only @command{gpgsm} may modify these files.
@item The signature is invalid
This means that the signature verification failed (this is an indication
-of af a transfer error, a program error or tampering with the message).
+of a transfer error, a program error or tampering with the message).
@command{gpgsm} issues one of these status codes sequences:
@table @code
@item @code{BADSIG}
@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:
The requested length of a generated key in bits. Defaults to 2048.
@item Key-Grip: @var{hexstring}
-This is optional and used to generate a CSR or certificatet for an
+This is optional and used to generate a CSR or certificate for an
already existing key. Key-Length will be ignored when given.
@item Key-Usage: @var{usage-list}
@item Serial: @var{sn}
If this parameter is given an X.509 certificate will be generated.
@var{sn} is expected to be a hex string representing an unsigned
-integer of arbitary length. The special value @samp{random} can be
+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.
@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
Set the file descriptor to be used for the output (i.e. the encrypted
message). Obviously the pipe must be open at that point, the server
-establishes its own end. If the server returns an error he client
+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
@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.
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
SIGNER @var{userID}
@end example
-to the signer's key. @var{userID} should be the
+to set 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
keys are valid, the client has to take care of this. All
@code{SIGNER} commands are cumulative until a @code{RESET} is done.
Note that a @code{SIGN} does not reset this list of signers which is in
-contrats to the @code{RECIPIENT} command.
+contrast to the @code{RECIPIENT} command.
@node GPGSM VERIFY
@subsection Verifying a Message
-To verify a mesage the command:
+To verify a message the command:
@example
VERIFY
Lists only the keys where a secret key is available.
-The list commands commands are affected by the option
+The list commands are affected by the option
@example
OPTION list-mode=@var{mode}
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
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.
@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
+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.
@end table
@node GPGSM OPTION
-@subsection Session options.
+@subsection Session options
The standard Assuan option handler supports these options.
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
+certificates, 0 does not include any certificates, 1 includes only the
+signers certificate and all other positive values include up to
@var{value} certificates starting with the signer cert.
@item list-mode
@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
@item validation-model
This option overrides the command line option
@option{validation-model} for the session.
-(@pxref{gpgsm-option --validation-model}.)
+(@xref{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}.)
+@option{--with-key-data}. (@xref{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}.)
+(@xref{gpgsm-cmd getauditlog}.)
@item allow-pinentry-notify
If this option is used notifications about the launch of a Pinentry