mirror of
git://git.gnupg.org/gnupg.git
synced 2024-10-31 20:08:43 +01:00
89df86157e
* sm/gpgsm.c (opts): Add option --ldapserver and make --keyserver an
alias.
--
We should use "keyserver" for OpenPGP and thus it is better to allow
for "ldapserver" here - it is the same convention as now used in
dirmngr.
Signed-off-by: Werner Koch <wk@gnupg.org>
(cherry picked from commit d6df1bf849)
1680 lines
59 KiB
Plaintext
1680 lines
59 KiB
Plaintext
@c Copyright (C) 2002 Free Software Foundation, Inc.
|
|
@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
|
|
@cindex command options
|
|
@cindex options, GPGSM command
|
|
|
|
@manpage gpgsm.1
|
|
@ifset manverb
|
|
.B gpgsm
|
|
\- CMS encryption and signing tool
|
|
@end ifset
|
|
|
|
@mansect synopsis
|
|
@ifset manverb
|
|
.B gpgsm
|
|
.RB [ \-\-homedir
|
|
.IR dir ]
|
|
.RB [ \-\-options
|
|
.IR file ]
|
|
.RI [ options ]
|
|
.I command
|
|
.RI [ args ]
|
|
@end ifset
|
|
|
|
|
|
@mansect description
|
|
@command{gpgsm} is a tool similar to @command{gpg} to provide digital
|
|
encryption and signing services on X.509 certificates and the CMS
|
|
protocol. It is mainly used as a backend for S/MIME mail processing.
|
|
@command{gpgsm} includes a full featured certificate management and
|
|
complies with all rules defined for the German Sphinx project.
|
|
|
|
@manpause
|
|
@xref{Option Index}, for an index to @command{GPGSM}'s commands and options.
|
|
@mancont
|
|
|
|
@menu
|
|
* GPGSM Commands:: List of all commands.
|
|
* GPGSM Options:: List of all options.
|
|
* GPGSM Configuration:: Configuration files.
|
|
* GPGSM Examples:: Some usage examples.
|
|
|
|
Developer information:
|
|
* Unattended Usage:: Using @command{gpgsm} from other programs.
|
|
* GPGSM Protocol:: The protocol the server mode uses.
|
|
@end menu
|
|
|
|
@c *******************************************
|
|
@c *************** ****************
|
|
@c *************** COMMANDS ****************
|
|
@c *************** ****************
|
|
@c *******************************************
|
|
@mansect commands
|
|
@node GPGSM Commands
|
|
@section Commands
|
|
|
|
Commands are not distinguished from options except for the fact that
|
|
only one command is allowed.
|
|
|
|
@menu
|
|
* General GPGSM Commands:: Commands not specific to the functionality.
|
|
* Operational GPGSM Commands:: Commands to select the type of operation.
|
|
* Certificate Management:: How to manage certificates.
|
|
@end menu
|
|
|
|
|
|
@c *******************************************
|
|
@c ********** GENERAL COMMANDS *************
|
|
@c *******************************************
|
|
@node General GPGSM Commands
|
|
@subsection Commands not specific to the function
|
|
|
|
@table @gnupgtabopt
|
|
@item --version
|
|
@opindex version
|
|
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 useful command-line options.
|
|
Note that you cannot abbreviate this command.
|
|
|
|
@item --warranty
|
|
@opindex warranty
|
|
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. Note that you cannot
|
|
abbreviate this command.
|
|
@end table
|
|
|
|
|
|
@c *******************************************
|
|
@c ******** OPERATIONAL COMMANDS ***********
|
|
@c *******************************************
|
|
@node Operational GPGSM Commands
|
|
@subsection Commands to select the type of operation
|
|
|
|
@table @gnupgtabopt
|
|
@item --encrypt
|
|
@opindex encrypt
|
|
Perform an encryption. The keys the data is encrypted to must be set
|
|
using the option @option{--recipient}.
|
|
|
|
@item --decrypt
|
|
@opindex decrypt
|
|
Perform a decryption; the type of input is automatically determined. It
|
|
may either be in binary form or PEM encoded; automatic determination of
|
|
base-64 encoding is not done.
|
|
|
|
@item --sign
|
|
@opindex sign
|
|
Create a digital signature. The key used is either the fist one found
|
|
in the keybox or those set with the @option{--local-user} option.
|
|
|
|
@item --verify
|
|
@opindex verify
|
|
Check a signature file for validity. Depending on the arguments a
|
|
detached signature may also be checked.
|
|
|
|
@item --server
|
|
@opindex server
|
|
Run in server mode and wait for commands on the @code{stdin}.
|
|
|
|
@item --call-dirmngr @var{command} [@var{args}]
|
|
@opindex call-dirmngr
|
|
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
|
|
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}
|
|
should not contain spaces.
|
|
|
|
This is command is required for certain maintaining tasks of the dirmngr
|
|
where a dirmngr must be able to call back to @command{gpgsm}. See the Dirmngr
|
|
manual for details.
|
|
|
|
@item --call-protect-tool @var{arguments}
|
|
@opindex call-protect-tool
|
|
Certain maintenance operations are done by an external program call
|
|
@command{gpg-protect-tool}; this is usually not installed in a directory
|
|
listed in the PATH variable. This command provides a simple wrapper to
|
|
access this tool. @var{arguments} are passed verbatim to this command;
|
|
use @samp{--help} to get a list of supported operations.
|
|
|
|
|
|
@end table
|
|
|
|
|
|
@c *******************************************
|
|
@c ******* CERTIFICATE MANAGEMENT **********
|
|
@c *******************************************
|
|
@node Certificate Management
|
|
@subsection How to manage the certificates and keys
|
|
|
|
@table @gnupgtabopt
|
|
@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
|
|
@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.
|
|
|
|
@item --list-keys
|
|
@itemx -k
|
|
@opindex list-keys
|
|
List all available certificates stored in the local key database.
|
|
Note that the displayed data might be reformatted for better human
|
|
readability and illegal characters are replaced by safe substitutes.
|
|
|
|
@item --list-secret-keys
|
|
@itemx -K
|
|
@opindex list-secret-keys
|
|
List all available certificates for which a corresponding a secret key
|
|
is available.
|
|
|
|
@item --list-external-keys @var{pattern}
|
|
@opindex list-keys
|
|
List certificates matching @var{pattern} using an external server. This
|
|
utilizes the @code{dirmngr} service.
|
|
|
|
@item --list-chain
|
|
@opindex list-chain
|
|
Same as @option{--list-keys} but also prints all keys making up the chain.
|
|
|
|
|
|
@item --dump-cert
|
|
@itemx --dump-keys
|
|
@opindex dump-cert
|
|
@opindex dump-keys
|
|
List all available certificates stored in the local key database using a
|
|
format useful mainly for debugging.
|
|
|
|
@item --dump-chain
|
|
@opindex dump-chain
|
|
Same as @option{--dump-keys} but also prints all keys making up the chain.
|
|
|
|
@item --dump-secret-keys
|
|
@opindex dump-secret-keys
|
|
List all available certificates for which a corresponding a secret key
|
|
is available using a format useful mainly for debugging.
|
|
|
|
@item --dump-external-keys @var{pattern}
|
|
@opindex dump-external-keys
|
|
List certificates matching @var{pattern} using an external server.
|
|
This utilizes the @code{dirmngr} service. It uses a format useful
|
|
mainly for debugging.
|
|
|
|
@item --show-certs [@var{files}]
|
|
@opindex show-certs
|
|
This command takes certificate files as input and prints information
|
|
about them in the same format as @option{--dump-cert} does. Each file
|
|
may either contain a single binary certificate or several PEM encoded
|
|
certificates. If no files are given, the input is taken from stdin.
|
|
|
|
Please note that the listing format may be changed in future releases
|
|
and that the option @option{--with-colons} has currently no effect.
|
|
|
|
|
|
@item --keydb-clear-some-cert-flags
|
|
@opindex keydb-clear-some-cert-flags
|
|
This is a debugging aid to reset certain flags in the key database
|
|
which are used to cache certain certificate statuses. It is especially
|
|
useful if a bad CRL or a weird running OCSP responder did accidentally
|
|
revoke certificate. There is no security issue with this command
|
|
because @command{gpgsm} always make sure that the validity of a certificate is
|
|
checked right before it is used.
|
|
|
|
@item --delete-keys @var{pattern}
|
|
@opindex delete-keys
|
|
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
|
|
Export all certificates stored in the Keybox or those specified by the
|
|
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. 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-secret-key-p12
|
|
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 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}
|
|
@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
|
|
from signed-only messages. This command may also be used to import a
|
|
secret key from a PKCS#12 file.
|
|
|
|
@item --learn-card
|
|
@opindex learn-card
|
|
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 --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
|
|
smartcard is not yet supported.
|
|
|
|
@end table
|
|
|
|
|
|
@c *******************************************
|
|
@c *************** ****************
|
|
@c *************** OPTIONS ****************
|
|
@c *************** ****************
|
|
@c *******************************************
|
|
@mansect options
|
|
@node GPGSM Options
|
|
@section Option Summary
|
|
|
|
@command{GPGSM} features a bunch of options to control the exact behaviour
|
|
and to change the default configuration.
|
|
|
|
@menu
|
|
* Configuration Options:: How to change the 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 do not want to do.
|
|
@end menu
|
|
|
|
|
|
@c *******************************************
|
|
@c ******** CONFIGURATION OPTIONS **********
|
|
@c *******************************************
|
|
@node Configuration Options
|
|
@subsection How to change the configuration
|
|
|
|
These options are used to change the configuration and are usually found
|
|
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
|
|
per-user configuration file. The default configuration file is named
|
|
@file{gpgsm.conf} and expected in the @file{.gnupg} directory directly
|
|
below the home directory of the user.
|
|
|
|
@include opt-homedir.texi
|
|
|
|
|
|
@item -v
|
|
@item --verbose
|
|
@opindex v
|
|
@opindex verbose
|
|
Outputs additional information while running.
|
|
You can increase the verbosity by giving several
|
|
verbose commands to @command{gpgsm}, such as @samp{-vv}.
|
|
|
|
@item --ldapserver @var{string}
|
|
@itemx --keyserver @var{string}
|
|
@opindex ldapserver
|
|
@opindex keyserver
|
|
Add an LDAP server to use for X.509 certificate and CRL lookup. This
|
|
option can be given multiple times to configure more than one LDAP
|
|
server. Note that in general @command{dirmngr} should be configured
|
|
with the list of LDAP servers; if this option is also configured here,
|
|
it is used in addition to those configured in dirmngr. For the syntax
|
|
see the description of dirmngr's ldapserver option.
|
|
|
|
@item --policy-file @var{filename}
|
|
@opindex policy-file
|
|
Change the default name of the policy file to @var{filename}. The
|
|
default name is @file{policies.txt}.
|
|
|
|
@item --agent-program @var{file}
|
|
@opindex agent-program
|
|
Specify an agent program to be used for secret key operations. The
|
|
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 dirmngr-program
|
|
Specify a dirmngr program to be used for @acronym{CRL} checks. The
|
|
default value is @file{@value{BINDIR}/dirmngr}.
|
|
|
|
@item --prefer-system-dirmngr
|
|
@opindex prefer-system-dirmngr
|
|
This option is obsolete and ignored.
|
|
|
|
@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
|
|
Do not print a warning when the so called "secure memory" cannot be used.
|
|
|
|
@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
|
|
|
|
|
|
@c *******************************************
|
|
@c ******** CERTIFICATE OPTIONS ************
|
|
@c *******************************************
|
|
@node Certificate Options
|
|
@subsection Certificate related options
|
|
|
|
@table @gnupgtabopt
|
|
|
|
@item --enable-policy-checks
|
|
@itemx --disable-policy-checks
|
|
@opindex enable-policy-checks
|
|
@opindex disable-policy-checks
|
|
By default policy checks are enabled. These options may be used to
|
|
change it.
|
|
|
|
@item --enable-crl-checks
|
|
@itemx --disable-crl-checks
|
|
@opindex enable-crl-checks
|
|
@opindex disable-crl-checks
|
|
By default the @acronym{CRL} checks are enabled and the DirMngr is
|
|
used to check for revoked certificates. The disable option is most
|
|
useful with an off-line network connection to suppress this check and
|
|
also to avoid that new certificates introduce a web bug by including a
|
|
certificate specific CRL DP. The disable option also disables an
|
|
issuer certificate lookup via the authorityInfoAccess property of the
|
|
certificate; the @option{--enable-issuer-key-retrieve} can be used
|
|
to make use of that property anyway.
|
|
|
|
@item --enable-trusted-cert-crl-check
|
|
@itemx --disable-trusted-cert-crl-check
|
|
@opindex enable-trusted-cert-crl-check
|
|
@opindex disable-trusted-cert-crl-check
|
|
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 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
|
|
line of the @file{trustlist.txt}
|
|
|
|
|
|
@item --force-crl-refresh
|
|
@opindex force-crl-refresh
|
|
Tell the dirmngr to reload the CRL for each request. For better
|
|
performance, the dirmngr will actually optimize this by suppressing
|
|
the loading for short time intervals (e.g. 30 minutes). This option
|
|
is useful to make sure that a fresh CRL is available for certificates
|
|
hold in the keybox. The suggested way of doing this is by using it
|
|
along with the option @option{--with-validation} for a key listing
|
|
command. This option should not be used in a configuration file.
|
|
|
|
@item --enable-issuer-based-crl-check
|
|
@opindex enable-issuer-based-crl-check
|
|
Run a CRL check even for certificates which do not have any CRL
|
|
distribution point. This requires that a suitable LDAP server has
|
|
been configured in Dirmngr and that the CRL can be found using the
|
|
issuer. This option reverts to what GnuPG did up to version 2.2.20.
|
|
This option is in general not useful.
|
|
|
|
@item --enable-ocsp
|
|
@itemx --disable-ocsp
|
|
@opindex enable-ocsp
|
|
@opindex disable-ocsp
|
|
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 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 do not do
|
|
so you will get the error code @samp{Not supported}.
|
|
|
|
@item --auto-issuer-key-retrieve
|
|
@opindex auto-issuer-key-retrieve
|
|
If a required certificate is missing while validating the chain of
|
|
certificates, try to load that certificate from an external location.
|
|
This usually means that Dirmngr is employed to search for the
|
|
certificate. Note that this option makes a "web bug" like behavior
|
|
possible. LDAP server operators can see which keys you request, so by
|
|
sending you a message signed by a brand new key (which you naturally
|
|
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), "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
|
|
Add @var{oid} to the list of ignored certificate extensions. The
|
|
@var{oid} is expected to be in dotted decimal form, like
|
|
@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
|
|
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.
|
|
|
|
@end table
|
|
|
|
@c *******************************************
|
|
@c *********** INPUT AND OUTPUT ************
|
|
@c *******************************************
|
|
@node Input and Output
|
|
@subsection Input and Output
|
|
|
|
@table @gnupgtabopt
|
|
@item --armor
|
|
@itemx -a
|
|
@opindex armor
|
|
Create PEM encoded output. Default is binary output.
|
|
|
|
@item --base64
|
|
@opindex base64
|
|
Create Base-64 encoded output; i.e. PEM without the header lines.
|
|
|
|
@item --assume-armor
|
|
@opindex assume-armor
|
|
Assume the input data is PEM encoded. Default is to autodetect the
|
|
encoding but this is may fail.
|
|
|
|
@item --assume-base64
|
|
@opindex assume-base64
|
|
Assume the input data is plain base-64 encoded.
|
|
|
|
@item --assume-binary
|
|
@opindex assume-binary
|
|
Assume the input data is binary encoded.
|
|
|
|
@anchor{option --p12-charset}
|
|
@item --p12-charset @var{name}
|
|
@opindex p12-charset
|
|
@command{gpgsm} uses the UTF-8 encoding when encoding passphrases for
|
|
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
|
|
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.
|
|
|
|
|
|
@item --default-key @var{user_id}
|
|
@opindex default-key
|
|
Use @var{user_id} as the standard key for signing. This key is used if
|
|
no other key has been defined as a signing key. Note, that the first
|
|
@option{--local-users} option also sets this key if it has not yet been
|
|
set; however @option{--default-key} always overrides this.
|
|
|
|
|
|
@item --local-user @var{user_id}
|
|
@item -u @var{user_id}
|
|
@opindex local-user
|
|
Set the user(s) to be used for signing. The default is the first
|
|
secret key found in the database.
|
|
|
|
|
|
@item --recipient @var{name}
|
|
@itemx -r
|
|
@opindex recipient
|
|
Encrypt to the user id @var{name}. There are several ways a user id
|
|
may be given (@pxref{how-to-specify-a-user-id}).
|
|
|
|
|
|
@item --output @var{file}
|
|
@itemx -o @var{file}
|
|
@opindex output
|
|
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
|
|
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. Implies @code{--with-colons}.
|
|
|
|
@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
|
|
print the result. This is usually a slow operation because it
|
|
requires a CRL lookup and other operations.
|
|
|
|
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-md5-fingerprint
|
|
For standard key listings, also print the MD5 fingerprint of the
|
|
certificate.
|
|
|
|
@item --with-keygrip
|
|
Include the keygrip in standard key listings. Note that the keygrip is
|
|
always listed in @option{--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 *******************************************
|
|
@c ************* CMS OPTIONS ***************
|
|
@c *******************************************
|
|
@node CMS Options
|
|
@subsection How to change how the CMS is created
|
|
|
|
@table @gnupgtabopt
|
|
@item --include-certs @var{n}
|
|
@opindex include-certs
|
|
Using @var{n} of -2 includes all certificate except for the root cert,
|
|
-1 includes all certs, 0 does not include any certs, 1 includes only the
|
|
signers cert and all other positive values include up to @var{n}
|
|
certificates starting with the signer cert. The default is -2.
|
|
|
|
@item --cipher-algo @var{oid}
|
|
@opindex cipher-algo
|
|
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{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
|
|
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
|
|
|
|
|
|
|
|
@c *******************************************
|
|
@c ******** ESOTERIC OPTIONS ***************
|
|
@c *******************************************
|
|
@node Esoteric Options
|
|
@subsection Doing things one usually do not want to do
|
|
|
|
|
|
@table @gnupgtabopt
|
|
|
|
@item --chuid @var{uid}
|
|
@opindex chuid
|
|
Change the current user to @var{uid} which may either be a number or a
|
|
name. This can be used from the root account to run gpgsm for
|
|
another user. If @var{uid} is not the current UID a standard PATH is
|
|
set and the envvar GNUPGHOME is unset. To override the latter the
|
|
option @option{--homedir} can be used. This option has only an effect
|
|
when used on the command line. This option has currently no effect at
|
|
all on Windows.
|
|
|
|
|
|
@item --extra-digest-algo @var{name}
|
|
@opindex extra-digest-algo
|
|
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 @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 --faked-system-time @var{epoch}
|
|
@opindex faked-system-time
|
|
This option is only useful for testing; it sets the system time back or
|
|
forth to @var{epoch} which is the number of seconds elapsed since the year
|
|
1970. Alternatively @var{epoch} may be given as a full ISO time string
|
|
(e.g. "20070924T154812").
|
|
|
|
@item --with-ephemeral-keys
|
|
@opindex with-ephemeral-keys
|
|
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
|
|
Select the debug level for investigating problems. @var{level} may be
|
|
a numeric value or by a keyword:
|
|
|
|
@table @code
|
|
@item none
|
|
No debugging at all. A value of less than 1 may be used instead of
|
|
the keyword.
|
|
@item basic
|
|
Some basic debug messages. A value between 1 and 2 may be used
|
|
instead of the keyword.
|
|
@item advanced
|
|
More verbose debug messages. A value between 3 and 5 may be used
|
|
instead of the keyword.
|
|
@item expert
|
|
Even more detailed messages. A value between 6 and 8 may be used
|
|
instead of the keyword.
|
|
@item guru
|
|
All of the debug messages you can get. A value greater than 8 may be
|
|
used instead of the keyword. The creation of hash tracing files is
|
|
only enabled if the keyword is used.
|
|
@end table
|
|
|
|
How these messages are mapped to the actual debugging flags is not
|
|
specified and may change with newer releases of this program. They are
|
|
however carefully selected to best aid in debugging.
|
|
|
|
@item --debug @var{flags}
|
|
@opindex debug
|
|
Set debug flags. All flags are or-ed and @var{flags} may be given
|
|
in C syntax (e.g. 0x0042) or as a comma separated list of flag names.
|
|
To get a list of all supported flags the single word "help" can be
|
|
used. This option is only useful for debugging and the behavior may
|
|
change at any time without notice.
|
|
|
|
Note, that all flags set using this option may get overridden by
|
|
@code{--debug-level}.
|
|
|
|
@item --debug-all
|
|
@opindex debug-all
|
|
Same as @code{--debug=0xffffffff}
|
|
|
|
@item --debug-allow-core-dump
|
|
@opindex debug-allow-core-dump
|
|
Usually @command{gpgsm} tries to avoid dumping core by well written code and by
|
|
disabling core dumps for security reasons. However, bugs are pretty
|
|
durable beasts and to squash them it is sometimes useful to have a core
|
|
dump. This option enables core dumps unless the Bad Thing happened
|
|
before the option parsing.
|
|
|
|
@item --debug-no-chain-validation
|
|
@opindex debug-no-chain-validation
|
|
This is actually not a debugging option but only useful as such. It
|
|
lets @command{gpgsm} bypass all certificate chain validation checks.
|
|
|
|
@item --debug-ignore-expiration
|
|
@opindex debug-ignore-expiration
|
|
This is actually not a debugging option but only useful as such. It
|
|
lets @command{gpgsm} ignore all notAfter dates, this is used by the regression
|
|
tests.
|
|
|
|
@item --passphrase-fd @code{n}
|
|
@opindex passphrase-fd
|
|
Read the passphrase from file descriptor @code{n}. Only the first line
|
|
will be read from file descriptor @code{n}. If you use 0 for @code{n},
|
|
the passphrase will be read from STDIN. This can only be used if only
|
|
one passphrase is supplied.
|
|
|
|
Note that this passphrase is only used if the option @option{--batch}
|
|
has also been given.
|
|
|
|
@item --pinentry-mode @code{mode}
|
|
@opindex pinentry-mode
|
|
Set the pinentry mode to @code{mode}. Allowed values for @code{mode}
|
|
are:
|
|
@table @asis
|
|
@item default
|
|
Use the default of the agent, which is @code{ask}.
|
|
@item ask
|
|
Force the use of the Pinentry.
|
|
@item cancel
|
|
Emulate use of Pinentry's cancel button.
|
|
@item error
|
|
Return a Pinentry error (``No Pinentry'').
|
|
@item loopback
|
|
Redirect Pinentry queries to the caller. Note that in contrast to
|
|
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.
|
|
|
|
@end table
|
|
|
|
All the long options may also be given in the configuration file after
|
|
stripping off the two leading dashes.
|
|
|
|
@c *******************************************
|
|
@c *************** ****************
|
|
@c *************** USER ID ****************
|
|
@c *************** ****************
|
|
@c *******************************************
|
|
@mansect how to specify a user id
|
|
@ifset isman
|
|
@include specify-user-id.texi
|
|
@end ifset
|
|
|
|
@c *******************************************
|
|
@c *************** ****************
|
|
@c *************** FILES ****************
|
|
@c *************** ****************
|
|
@c *******************************************
|
|
@mansect files
|
|
@node GPGSM Configuration
|
|
@section Configuration files
|
|
|
|
There are a few configuration files to control certain aspects of
|
|
@command{gpgsm}'s operation. Unless noted, they are expected in the
|
|
current home directory (@pxref{option --homedir}).
|
|
|
|
@table @file
|
|
|
|
@item gpgsm.conf
|
|
@efindex gpgsm.conf
|
|
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{gpgsm-option --options}).
|
|
You should backup this file.
|
|
|
|
@item common.conf
|
|
@efindex common.conf
|
|
This is an optional configuration file read by @command{gpgsm} on
|
|
startup. It may contain options pertaining to all components of
|
|
GnuPG. Its current main use is for the "use-keyboxd" option.
|
|
|
|
@item policies.txt
|
|
@efindex policies.txt
|
|
This is a list of allowed CA policies. This file should list the
|
|
object identifiers of the policies line by line. Empty lines and
|
|
lines starting with a hash mark are ignored. Policies missing in this
|
|
file and not marked as critical in the certificate will print only a
|
|
warning; certificates with policies marked as critical and not listed
|
|
in this file will fail the signature verification. You should backup
|
|
this file.
|
|
|
|
For example, to allow only the policy 2.289.9.9, the file should look
|
|
like this:
|
|
|
|
@c man:.RS
|
|
@example
|
|
# Allowed policies
|
|
2.289.9.9
|
|
@end example
|
|
@c man:.RE
|
|
|
|
@item qualified.txt
|
|
@efindex qualified.txt
|
|
This is the list of root certificates used for qualified certificates.
|
|
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 @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.
|
|
|
|
Note that even if a certificate is listed in this file, this does not
|
|
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 sysconf directory (e.g.
|
|
@file{@value{SYSCONFDIR}/qualified.txt}).
|
|
|
|
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
|
|
legally binding (``qualified'') signature. When creating a signature
|
|
using such a certificate an extra prompt will be issued to let the user
|
|
confirm that such a legally binding signature shall really be created.
|
|
|
|
Because this software has not yet been approved for use with such
|
|
certificates, appropriate notices will be shown to indicate this fact.
|
|
|
|
@item help.txt
|
|
@efindex help.txt
|
|
This is plain text file with a few help entries used with
|
|
@command{pinentry} as well as a large list of help items for
|
|
@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{@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{@value{SYSCONFDIR}/help.de.txt}).
|
|
For a reference of the help file's syntax, please see the installed
|
|
@file{help.txt} file.
|
|
|
|
|
|
@item com-certs.pem
|
|
@efindex 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{@value{DATADIR}/com-certs.pem}).
|
|
|
|
@end table
|
|
|
|
@c man:.RE
|
|
Note that on larger installations, it is useful to put predefined files
|
|
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 @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.
|
|
|
|
|
|
@table @file
|
|
@item pubring.kbx
|
|
@efindex pubring.kbx
|
|
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. You should backup
|
|
this file.
|
|
|
|
@item random_seed
|
|
@efindex random_seed
|
|
This content of this file is used to maintain the internal state of the
|
|
random number generator across invocations. The same file is used by
|
|
other programs of this software too.
|
|
|
|
@item S.gpg-agent
|
|
@efindex S.gpg-agent
|
|
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
|
|
connecting the @command{gpg-agent}.
|
|
|
|
@end table
|
|
|
|
|
|
@c *******************************************
|
|
@c *************** ****************
|
|
@c *************** EXAMPLES ****************
|
|
@c *************** ****************
|
|
@c *******************************************
|
|
@mansect examples
|
|
@node GPGSM Examples
|
|
@section Examples
|
|
|
|
@example
|
|
$ gpgsm -er goo@@bar.net <plaintext >ciphertext
|
|
@end example
|
|
|
|
|
|
@c *******************************************
|
|
@c *************** **************
|
|
@c *************** UNATTENDED **************
|
|
@c *************** **************
|
|
@c *******************************************
|
|
@manpause
|
|
@node Unattended Usage
|
|
@section Unattended Usage
|
|
|
|
@command{gpgsm} is often used as a backend engine by other software. To help
|
|
with this a machine interface has been defined to have an unambiguous
|
|
way to do this. This is most likely used with the @code{--server} command
|
|
but may also be used in the standard operation mode by using the
|
|
@code{--status-fd} option.
|
|
|
|
@menu
|
|
* Automated signature checking:: Automated signature checking.
|
|
* CSR and certificate creation:: CSR and certificate creation.
|
|
@end menu
|
|
|
|
@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
|
|
so the operation is a bit complicated. In most cases it is required
|
|
to look at several status lines. Here is a table of all cases a signed
|
|
message may have:
|
|
|
|
@table @asis
|
|
@item The signature is valid
|
|
This does mean that the signature has been successfully verified, the
|
|
certificates are all sane. However there are two subcases with
|
|
important information: One of the certificates may have expired or a
|
|
signature of a message itself as expired. It is a sound practise to
|
|
consider such a signature still as valid but additional information
|
|
should be displayed. Depending on the subcase @command{gpgsm} will issue
|
|
these status codes:
|
|
@table @asis
|
|
@item signature valid and nothing did expire
|
|
@code{GOODSIG}, @code{VALIDSIG}, @code{TRUST_FULLY}
|
|
@item signature valid but at least one certificate has expired
|
|
@code{EXPKEYSIG}, @code{VALIDSIG}, @code{TRUST_FULLY}
|
|
@item signature valid but expired
|
|
@code{EXPSIG}, @code{VALIDSIG}, @code{TRUST_FULLY}
|
|
Note, that this case is currently not implemented.
|
|
@end table
|
|
|
|
@item The signature is invalid
|
|
This means that the signature verification failed (this is an indication
|
|
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}
|
|
@item @code{GOODSIG}, @code{VALIDSIG} @code{TRUST_NEVER}
|
|
@end table
|
|
|
|
@item Error verifying a signature
|
|
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
|
|
@subsection CSR and certificate creation
|
|
|
|
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:
|
|
|
|
@itemize @bullet
|
|
@item Text only, line length is limited to about 1000 characters.
|
|
@item UTF-8 encoding must be used to specify non-ASCII characters.
|
|
@item Empty lines are ignored.
|
|
@item Leading and trailing while space is ignored.
|
|
@item A hash sign as the first non white space character indicates
|
|
a comment line.
|
|
@item Control statements are indicated by a leading percent sign, the
|
|
arguments are separated by white space from the keyword.
|
|
@item Parameters are specified by a keyword, followed by a colon. Arguments
|
|
are separated by white space.
|
|
@item The first parameter must be @samp{Key-Type}, control statements
|
|
may be placed anywhere.
|
|
@item
|
|
The order of the parameters does not matter except for @samp{Key-Type}
|
|
which must be the first parameter. The parameters are only used for
|
|
the generated CSR/certificate; parameters from previous sets are not
|
|
used. Some syntactically checks may be performed.
|
|
@item
|
|
Key generation takes place when either the end of the parameter file
|
|
is reached, the next @samp{Key-Type} parameter is encountered or at the
|
|
control statement @samp{%commit} is encountered.
|
|
@end itemize
|
|
|
|
@noindent
|
|
Control statements:
|
|
|
|
@table @asis
|
|
|
|
@item %echo @var{text}
|
|
Print @var{text} as diagnostic.
|
|
|
|
@item %dry-run
|
|
Suppress actual key generation (useful for syntax checking).
|
|
|
|
@item %commit
|
|
Perform the key generation. Note that an implicit commit is done at
|
|
the next @asis{Key-Type} parameter.
|
|
|
|
@c %certfile <filename>
|
|
@c [Not yet implemented!]
|
|
@c Do not write the certificate to the keyDB but to <filename>.
|
|
@c This must be given before the first
|
|
@c commit to take place, duplicate specification of the same filename
|
|
@c is ignored, the last filename before a commit is used.
|
|
@c The filename is used until a new filename is used (at commit points)
|
|
@c and all keys are written to that file. If a new filename is given,
|
|
@c this file is created (and overwrites an existing one).
|
|
@c Both control statements must be given.
|
|
@end table
|
|
|
|
@noindent
|
|
General Parameters:
|
|
|
|
@table @asis
|
|
|
|
@item Key-Type: @var{algo}
|
|
Starts a new parameter block by giving the type of the primary
|
|
key. The algorithm must be capable of signing. This is a required
|
|
parameter. The supported values for @var{algo} are @samp{rsa},
|
|
@samp{ecdsa}, and @samp{eddsa}.
|
|
|
|
@item Key-Length: @var{nbits}
|
|
The requested length of a generated key in bits. Defaults to
|
|
3072. The value is ignored for ECC algorithms.
|
|
|
|
@item Key-Grip: @var{hexstring}
|
|
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}
|
|
Space or comma delimited list of key usage, allowed values are
|
|
@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.
|
|
|
|
@item Name-Email: @var{string}
|
|
This is an email address for the altSubjectName. This parameter is
|
|
optional but may occur several times to add several email addresses to
|
|
a certificate.
|
|
|
|
@item Name-DNS: @var{string}
|
|
The is an DNS name for the altSubjectName. This parameter is optional
|
|
but may occur several times to add several DNS names to a certificate.
|
|
|
|
@item Name-URI: @var{string}
|
|
This is an URI for the altSubjectName. This parameter is optional but
|
|
may occur several times to add several URIs to a certificate.
|
|
@end table
|
|
|
|
@noindent
|
|
Additional parameters used to create a certificate (in contrast to a
|
|
certificate signing request):
|
|
|
|
@table @asis
|
|
|
|
@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 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 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.
|
|
|
|
@item Creation-Date: @var{iso-date}
|
|
@itemx Not-Before: @var{iso-date}
|
|
Set the notBefore date of the certificate. Either a date like
|
|
@samp{1986-04-26} or @samp{1986-04-26 12:00} or a standard ISO
|
|
timestamp like @samp{19860426T042640} may be used. The time is
|
|
considered to be UTC. If it is not given the current date is used.
|
|
|
|
@item Expire-Date: @var{iso-date}
|
|
@itemx Not-After: @var{iso-date}
|
|
Set the notAfter date of the certificate. Either a date like
|
|
@samp{2063-04-05} or @samp{2063-04-05 17:00} or a standard ISO
|
|
timestamp like @samp{20630405T170000} may be used. The time is
|
|
considered to be UTC. If it is not given a default value in the not
|
|
too far future is used.
|
|
|
|
@item Signing-Key: @var{keygrip}
|
|
This gives the keygrip of the key used to sign the certificate. If it
|
|
is not given a self-signed certificate will be created. For
|
|
compatibility with future versions, it is suggested to prefix the
|
|
keygrip with a @samp{&}.
|
|
|
|
@item Hash-Algo: @var{hash-algo}
|
|
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{sha256}.
|
|
|
|
@item Authority-Key-Id: @var{hexstring}
|
|
Insert the decoded value of @var{hexstring} as authorityKeyIdentifier.
|
|
If this is not given and an ECC algorithm is used the public part of
|
|
the certified public key is used as authorityKeyIdentifier. To
|
|
inhibit any authorityKeyIdentifier use the special value @code{none}
|
|
for @var{hexstring}.
|
|
|
|
@item Subject-Key-Id: @var{hexstring}
|
|
Insert the decoded value of @var{hexstring} as subjectKeyIdentifier.
|
|
If this is not given and an ECC algorithm is used the public part of
|
|
the signing key is used as authorityKeyIdentifier. To inhibit any
|
|
subjectKeyIdentifier use the special value @code{none} for
|
|
@var{hexstring}.
|
|
|
|
@end table
|
|
|
|
@c *******************************************
|
|
@c *************** *****************
|
|
@c *************** ASSSUAN *****************
|
|
@c *************** *****************
|
|
@c *******************************************
|
|
@node GPGSM Protocol
|
|
@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
|
|
provides a regular command line interface which exhibits a full client
|
|
to this protocol (but uses internal linking). To start
|
|
@command{gpgsm} as a server the command line the option
|
|
@code{--server} must be used. Additional options are provided to
|
|
select the communication method (i.e. the name of the socket).
|
|
|
|
We assume that the connection has already been established; see the
|
|
Assuan manual for details.
|
|
|
|
@menu
|
|
* GPGSM ENCRYPT:: Encrypting a message.
|
|
* GPGSM DECRYPT:: Decrypting a message.
|
|
* GPGSM SIGN:: Signing a message.
|
|
* GPGSM VERIFY:: Verifying a message.
|
|
* GPGSM GENKEY:: Generating a key.
|
|
* GPGSM LISTKEYS:: List available keys.
|
|
* 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
|
|
|
|
|
|
@node GPGSM ENCRYPT
|
|
@subsection Encrypting a Message
|
|
|
|
Before encryption can be done the recipient must be set using the
|
|
command:
|
|
|
|
@example
|
|
RECIPIENT @var{userID}
|
|
@end example
|
|
|
|
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 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
|
|
successful @code{ENCRYPT} command.
|
|
|
|
@example
|
|
INPUT FD[=@var{n}] [--armor|--base64|--binary]
|
|
@end example
|
|
|
|
Set the file descriptor for the message to be encrypted to @var{n}.
|
|
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. If @var{n} is not given, this commands uses the
|
|
last file descriptor passed to the application.
|
|
@xref{fun-assuan_sendfd, ,the assuan_sendfd function,assuan,the Libassuan
|
|
manual}, on how to do descriptor passing.
|
|
|
|
The @code{--armor} option may be used to advise the server that the
|
|
input data is in @acronym{PEM} format, @code{--base64} advises that a
|
|
raw base-64 encoding is used, @code{--binary} advises of raw binary
|
|
input (@acronym{BER}). If none of these options is used, the server
|
|
tries to figure out the used encoding, but this may not always be
|
|
correct.
|
|
|
|
@example
|
|
OUTPUT FD[=@var{n}] [--armor|--base64]
|
|
@end example
|
|
|
|
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 the client
|
|
should consider this session failed.
|
|
|
|
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
|
|
|
|
@example
|
|
ENCRYPT
|
|
@end example
|
|
|
|
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
|
|
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
|
|
been done while setting the recipients. The input and output pipes are
|
|
closed.
|
|
|
|
|
|
@node GPGSM DECRYPT
|
|
@subsection Decrypting a message
|
|
|
|
Input and output FDs are set the same way as in encryption, but
|
|
@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 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
|
|
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.
|
|
|
|
|
|
@node GPGSM SIGN
|
|
@subsection Signing a Message
|
|
|
|
Signing is usually done with these commands:
|
|
|
|
@example
|
|
INPUT FD[=@var{n}] [--armor|--base64|--binary]
|
|
@end example
|
|
|
|
This tells @command{GPGSM} to read the data to sign from file descriptor @var{n}.
|
|
|
|
@example
|
|
OUTPUT FD[=@var{m}] [--armor|--base64]
|
|
@end example
|
|
|
|
Write the output to file descriptor @var{m}. If a detached signature is
|
|
requested, only the signature is written.
|
|
|
|
@example
|
|
SIGN [--detached]
|
|
@end example
|
|
|
|
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
|
|
the configuration file. To get finer control over the keys, it is
|
|
possible to use the command
|
|
|
|
@example
|
|
SIGNER @var{userID}
|
|
@end example
|
|
|
|
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
|
|
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.
|
|
Note that a @code{SIGN} does not reset this list of signers which is in
|
|
contrast to the @code{RECIPIENT} command.
|
|
|
|
|
|
@node GPGSM VERIFY
|
|
@subsection Verifying a Message
|
|
|
|
To verify a message the command:
|
|
|
|
@example
|
|
VERIFY
|
|
@end example
|
|
|
|
is used. It does a verify operation on the message send to the input FD.
|
|
The result is written out using status lines. If an output FD was
|
|
given, the signed text will be written to that. If the signature is a
|
|
detached one, the server will inquire about the signed material and the
|
|
client must provide it.
|
|
|
|
@node GPGSM GENKEY
|
|
@subsection Generating a Key
|
|
|
|
This is used to generate a new keypair, store the secret part in the
|
|
@acronym{PSE} and the public key in the key database. We will probably
|
|
add optional commands to allow the client to select whether a hardware
|
|
token is used to store the key. Configuration options to
|
|
@command{GPGSM} can be used to restrict the use of this command.
|
|
|
|
@example
|
|
GENKEY
|
|
@end example
|
|
|
|
@command{GPGSM} checks whether this command is allowed and then does an
|
|
INQUIRY to get the key parameters, the client should then send the
|
|
key parameters in the native format:
|
|
|
|
@example
|
|
S: INQUIRE KEY_PARAM native
|
|
C: D foo:fgfgfg
|
|
C: D bar
|
|
C: END
|
|
@end example
|
|
|
|
Please note that the server may send Status info lines while reading the
|
|
data lines from the client. After this the key generation takes place
|
|
and the server eventually does send an ERR or OK response. Status lines
|
|
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:
|
|
|
|
@example
|
|
LISTKEYS @var{pattern}
|
|
@end example
|
|
|
|
is used. To allow multiple patterns (which are ORed during the search)
|
|
quoting is required: Spaces are to be translated into "+" or into "%20";
|
|
in turn this requires that the usual escape quoting rules are done.
|
|
|
|
@example
|
|
LISTSECRETKEYS @var{pattern}
|
|
@end example
|
|
|
|
Lists only the keys where a secret key is available.
|
|
|
|
The list commands are affected by the option
|
|
|
|
@example
|
|
OPTION list-mode=@var{mode}
|
|
@end example
|
|
|
|
where mode may be:
|
|
@table @code
|
|
@item 0
|
|
Use default (which is usually the same as 1).
|
|
@item 1
|
|
List only the internal keys.
|
|
@item 2
|
|
List only the external keys.
|
|
@item 3
|
|
List internal and external keys.
|
|
@end table
|
|
|
|
Note that options are valid for the entire session.
|
|
|
|
|
|
@node GPGSM EXPORT
|
|
@subsection Export certificates
|
|
|
|
To export certificate from the internal key database the command:
|
|
|
|
@example
|
|
EXPORT [--data [--armor] [--base64]] [--] @var{pattern}
|
|
@end example
|
|
|
|
is used. To allow multiple patterns (which are ORed) quoting is
|
|
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 @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 @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 @code{OUTPUT} command.
|
|
|
|
|
|
@node GPGSM IMPORT
|
|
@subsection Import certificates
|
|
|
|
To import certificates into the internal key database, the command
|
|
|
|
@example
|
|
IMPORT [--re-import]
|
|
@end example
|
|
|
|
is used. The data is expected on the file descriptor set with the
|
|
@code{INPUT} command. Certain checks are performed on the
|
|
certificate. Note that the code will also handle PKCS#12 files and
|
|
import private keys; a helper program is used for that.
|
|
|
|
With the option @option{--re-import} the input data is expected to a be
|
|
a linefeed separated list of fingerprints. The command will re-import
|
|
the corresponding certificates; that is they are made permanent by
|
|
removing their ephemeral flag.
|
|
|
|
|
|
@node GPGSM DELETE
|
|
@subsection Delete certificates
|
|
|
|
To delete a certificate the command
|
|
|
|
@example
|
|
DELKEYS @var{pattern}
|
|
@end example
|
|
|
|
is used. To allow multiple patterns (which are ORed) quoting is
|
|
required: Spaces are to be translated into "+" or into "%20"; in turn
|
|
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 @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.
|
|
|
|
|
|
@node GPGSM GETINFO
|
|
@subsection Return information about the process
|
|
|
|
This is a multipurpose function to return a variety of information.
|
|
|
|
@example
|
|
GETINFO @var{what}
|
|
@end example
|
|
|
|
The value of @var{what} specifies the kind of information returned:
|
|
@table @code
|
|
@item version
|
|
Return the version of the program.
|
|
@item pid
|
|
Return the process id of the process.
|
|
@item agent-check
|
|
Return OK if the agent is running.
|
|
@item cmd_has_option @var{cmd} @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
|
|
@efindex DISPLAY
|
|
Set the session environment variable @code{DISPLAY} is set to @var{value}.
|
|
@item ttyname
|
|
@efindex GPG_TTY
|
|
Set the session environment variable @code{GPG_TTY} is set to @var{value}.
|
|
@item ttytype
|
|
@efindex TERM
|
|
Set the session environment variable @code{TERM} is set to @var{value}.
|
|
@item lc-ctype
|
|
@efindex LC_CTYPE
|
|
Set the session environment variable @code{LC_CTYPE} is set to @var{value}.
|
|
@item lc-messages
|
|
@efindex LC_MESSAGES
|
|
Set the session environment variable @code{LC_MESSAGES} is set to @var{value}.
|
|
@item xauthority
|
|
@efindex XAUTHORITY
|
|
Set the session environment variable @code{XAUTHORITY} is set to @var{value}.
|
|
@item pinentry-user-data
|
|
@efindex 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
|
|
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
|
|
@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 @code{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.
|
|
(@xref{gpgsm-option --validation-model}.)
|
|
|
|
@item with-key-data
|
|
This option globally enables the command line option
|
|
@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.
|
|
(@xref{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
|
|
@ifset isman
|
|
@command{gpg2}(1),
|
|
@command{gpg-agent}(1)
|
|
@end ifset
|
|
@include see-also-note.texi
|