Changeset View
Changeset View
Standalone View
Standalone View
doc/gpgsm.texi
Context not available. | |||||
@mansect description | @mansect description | ||||
@command{gpgsm} is a tool similar to @command{gpg} to provide digital | @command{gpgsm} is a tool similar to @command{gpg} to provide digital | ||||
encryption and signing servicesd on X.509 certificates and the CMS | encryption and signing services on X.509 certificates and the CMS | ||||
protocol. It is mainly used as a backend for S/MIME mail processing. | protocol. It is mainly used as a backend for S/MIME mail processing. | ||||
@command{gpgsm} includes a full features certificate management and | @command{gpgsm} includes a full features certificate management and | ||||
complies with all rules defined for the German Sphinx project. | complies with all rules defined for the German Sphinx project. | ||||
Context not available. | |||||
@item --help, -h | @item --help, -h | ||||
@opindex help | @opindex help | ||||
Print a usage message summarizing the most usefule command-line options. | Print a usage message summarizing the most useful command-line options. | ||||
Note that you cannot abbreviate this command. | Note that you cannot abbreviate this command. | ||||
@item --warranty | @item --warranty | ||||
Context not available. | |||||
@item --verify | @item --verify | ||||
@opindex verify | @opindex verify | ||||
Check a signature file for validity. Depending on the arguments a | Check a signature file for validity. Depending on the arguments a | ||||
detached signatrue may also be checked. | detached signature may also be checked. | ||||
@item --server | @item --server | ||||
@opindex server | @opindex server | ||||
Context not available. | |||||
Behave as a Dirmngr client issuing the request @var{command} with the | Behave as a Dirmngr client issuing the request @var{command} with the | ||||
optional list of @var{args}. The output of the Dirmngr is printed | optional list of @var{args}. The output of the Dirmngr is printed | ||||
stdout. Please note that file names given as arguments should have an | stdout. Please note that file names given as arguments should have an | ||||
absulte 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 | 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 | 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} | is not possible to pass data via stdin to the Dirmngr. @var{command} | ||||
Context not available. | |||||
@opindex keydb-clear-some-cert-flags | @opindex keydb-clear-some-cert-flags | ||||
This is a debugging aid to reset certain flags in the key database | This is a debugging aid to reset certain flags in the key database | ||||
which are used to cache certain certificate stati. It is especially | which are used to cache certain certificate stati. It is especially | ||||
useful if a bad CRL or a weird running OCSP reponder did accidently | useful if a bad CRL or a weird running OCSP responder did accidentally | ||||
revoke certificate. There is no security issue with this command | revoke certificate. There is no security issue with this command | ||||
because @command{gpgsm} always make sure that the validity of a certificate is | because @command{gpgsm} always make sure that the validity of a certificate is | ||||
checked right before it is used. | checked right before it is used. | ||||
Context not available. | |||||
@node GPGSM Options | @node GPGSM Options | ||||
@section Option Summary | @section Option Summary | ||||
@command{GPGSM} comes features a bunch ofoptions to control the exact behaviour | @command{GPGSM} comes features a bunch of options to control the exact behaviour | ||||
and to change the default configuration. | and to change the default configuration. | ||||
@menu | @menu | ||||
Context not available. | |||||
@node Configuration Options | @node Configuration Options | ||||
@subsection How to change the configuration | @subsection How to change the configuration | ||||
These options are used to change the configuraton and are usually found | These options are used to change the configuration and are usually found | ||||
in the option file. | in the option file. | ||||
@table @gnupgtabopt | @table @gnupgtabopt | ||||
Context not available. | |||||
@opindex agent-program | @opindex agent-program | ||||
Specify an agent program to be used for secret key operations. The | 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 | default value is the @file{/usr/local/bin/gpg-agent}. This is only used | ||||
as a fallback when the envrionment variable @code{GPG_AGENT_INFO} is not | as a fallback when the environment variable @code{GPG_AGENT_INFO} is not | ||||
set or a running agent can't be connected. | set or a running agent can't be connected. | ||||
@item --dirmngr-program @var{file} | @item --dirmngr-program @var{file} | ||||
Context not available. | |||||
@opindex force-crl-refresh | @opindex force-crl-refresh | ||||
Tell the dirmngr to reload the CRL for each request. For better | Tell the dirmngr to reload the CRL for each request. For better | ||||
performance, the dirmngr will actually optimize this by suppressing | performance, the dirmngr will actually optimize this by suppressing | ||||
the loading for short time intervalls (e.g. 30 minutes). This option | 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 | 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 | 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 | along with the option @option{--with-validation} for a key listing | ||||
Context not available. | |||||
@opindex auto-issuer-key-retrieve | @opindex auto-issuer-key-retrieve | ||||
If a required certificate is missing while validating the chain of | If a required certificate is missing while validating the chain of | ||||
certificates, try to load that certificate from an external location. | certificates, try to load that certificate from an external location. | ||||
This usually means that Dirmngr is employed t search for the | This usually means that Dirmngr is employed to search for the | ||||
certificate. Note that this option makes a "web bug" like behavior | certificate. Note that this option makes a "web bug" like behavior | ||||
possible. LDAP server operators can see which keys you request, so by | 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 | sending you a message signed by a brand new key (which you naturally | ||||
Context not available. | |||||
When used along with --import, a validation of the certificate to | When used along with --import, a validation of the certificate to | ||||
import is done and only imported if it succeeds the test. Note that | import is done and only imported if it succeeds the test. Note that | ||||
this does not affect an already available cwertificate in the DB. | this does not affect an already available certificate in the DB. | ||||
This option is therefore useful to simply verify a certificate. | This option is therefore useful to simply verify a certificate. | ||||
Context not available. | |||||
@opindex extra-digest-algo | @opindex extra-digest-algo | ||||
Sometimes signatures are broken in that they announce a different digest | Sometimes signatures are broken in that they announce a different digest | ||||
algorithm than actually used. @command{gpgsm} uses a one-pass data | algorithm than actually used. @command{gpgsm} uses a one-pass data | ||||
processing model and thus needs to rely on the announcde digest | processing model and thus needs to rely on the announced digest | ||||
algorithms to properly hash the data. As a workaround this option may | algorithms to properly hash the data. As a workaround this option may | ||||
be used to tell gpg to also hash the data using the algorithm | be used to tell gpg to also hash the data using the algorithm | ||||
@var{name}; this slows processing down a little bit but allows to verify | @var{name}; this slows processing down a little bit but allows to verify | ||||
Context not available. | |||||
@opindex faked-system-time | @opindex faked-system-time | ||||
This option is only useful for testing; it sets the system time back or | 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 | forth to @var{epoch} which is the number of seconds elapsed since the year | ||||
1970. Alternativly @var{epoch} may be given as a full ISO time string | 1970. Alternatively @var{epoch} may be given as a full ISO time string | ||||
(e.g. "20070924T154812"). | (e.g. "20070924T154812"). | ||||
@item --with-ephemeral-keys | @item --with-ephemeral-keys | ||||
Context not available. | |||||
trace Assuan protocol | trace Assuan protocol | ||||
@end table | @end table | ||||
Note, that all flags set using this option may get overriden by | Note, that all flags set using this option may get overridden by | ||||
@code{--debug-level}. | @code{--debug-level}. | ||||
@item --debug-all | @item --debug-all | ||||
Context not available. | |||||
@item --debug-ignore-expiration | @item --debug-ignore-expiration | ||||
@opindex debug-ignore-expiration | @opindex debug-ignore-expiration | ||||
This is actually not a debugging option but only useful as such. It | 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 regresssion | lets @command{gpgsm} ignore all notAfter dates, this is used by the regression | ||||
tests. | tests. | ||||
@item --fixed-passphrase @var{string} | @item --fixed-passphrase @var{string} | ||||
Context not available. | |||||
@c man:.RE | @c man:.RE | ||||
Note that on larger installations, it is useful to put predefined files | Note that on larger installations, it is useful to put predefined files | ||||
into the directory @file{/etc/skel/.gnupg/} so that newly created users | into the directory @file{/etc/skel/.gnupg/} so that newly created users | ||||
start up with a working configuration. For existing users the a small | start up with a working configuration. For existing users a small | ||||
helper script is provided to create these files (@pxref{addgnupghome}). | helper script is provided to create these files (@pxref{addgnupghome}). | ||||
For internal purposes gpgsm creates and maintaines a few other files; | For internal purposes gpgsm creates and maintains a few other files; | ||||
they all live in in the current home directory (@pxref{option | they all live in in the current home directory (@pxref{option | ||||
--homedir}). Only @command{gpgsm} may modify these files. | --homedir}). Only @command{gpgsm} may modify these files. | ||||
Context not available. | |||||
@item random_seed | @item random_seed | ||||
@cindex random_seed | @cindex random_seed | ||||
This content of this file is used to maintain the internal state of the | This content of this file is used to maintain the internal state of the | ||||
random number generator accross invocations. The same file is used by | random number generator across invocations. The same file is used by | ||||
other programs of this software too. | other programs of this software too. | ||||
@item S.gpg-agent | @item S.gpg-agent | ||||
Context not available. | |||||
not set, @command{gpgsm} will first try to connect to this socket for | not set, @command{gpgsm} will first try to connect to this socket for | ||||
accessing @command{gpg-agent} before starting a new @command{gpg-agent} | accessing @command{gpg-agent} before starting a new @command{gpg-agent} | ||||
instance. Under Windows this socket (which in reality be a plain file | instance. Under Windows this socket (which in reality be a plain file | ||||
describing a regular TCP litening port) is the standard way of | describing a regular TCP listening port) is the standard way of | ||||
connecting the @command{gpg-agent}. | connecting the @command{gpg-agent}. | ||||
@end table | @end table | ||||
Context not available. | |||||
It is very important to understand the semantics used with signature | It is very important to understand the semantics used with signature | ||||
verification. Checking a signature is not as simple as it may sound and | verification. Checking a signature is not as simple as it may sound and | ||||
so the ooperation si a bit complicated. In mosted cases it is required | 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 | to look at several status lines. Here is a table of all cases a signed | ||||
message may have: | message may have: | ||||
Context not available. | |||||
@item The signature is invalid | @item The signature is invalid | ||||
This means that the signature verification failed (this is an indication | This means that the signature verification failed (this is an indication | ||||
of af a transfer error, a programm error or tampering with the message). | of af a transfer error, a program error or tampering with the message). | ||||
@command{gpgsm} issues one of these status codes sequences: | @command{gpgsm} issues one of these status codes sequences: | ||||
@table @code | @table @code | ||||
@item @code{BADSIG} | @item @code{BADSIG} | ||||
Context not available. | |||||
@node GPGSM ENCRYPT | @node GPGSM ENCRYPT | ||||
@subsection Encrypting a Message | @subsection Encrypting a Message | ||||
Before encrytion can be done the recipient must be set using the | Before encryption can be done the recipient must be set using the | ||||
command: | command: | ||||
@example | @example | ||||
Context not available. | |||||
OUTPUT. With @code{--detached}, a detached signature is created | OUTPUT. With @code{--detached}, a detached signature is created | ||||
(surprise). | (surprise). | ||||
The key used for signining is the default one or the one specified in | 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 | the configuration file. To get finer control over the keys, it is | ||||
possible to use the command | possible to use the command | ||||
Context not available. | |||||
@end example | @end example | ||||
is used. The data is expected on the file descriptor set with the | is used. The data is expected on the file descriptor set with the | ||||
@code{INPUT} command. Certain checks are performend on the | @code{INPUT} command. Certain checks are performed on the | ||||
certificate. Note that the code will also handle PKCS#12 files and | certificate. Note that the code will also handle PKCS#12 files and | ||||
import private keys; a helper program is used for that. | import private keys; a helper program is used for that. | ||||
Context not available. |