← Back to branch summary

~ubuntu-branches/ubuntu/lucid/gnupg2/lucid-updates

« back to all changes in this revision

Viewing changes to doc/gpgsm.texi

  • Committer: Bazaar Package Importer
  • Author(s): Michael Bienia
  • Date: 2009-11-07 13:12:03 UTC
  • mfrom: (1.1.13 upstream) (7.1.2 squeeze)
  • Revision ID: james.westby@ubuntu.com-20091107131203-vgyndyfgtwch7v61
Tags: 2.0.13-1ubuntu1
https://launchpad.net/bugs/477491
* Merge with Debian testing (lp: #477491). Remaining changes:
  - Build-depend on libreadline-dev instead of libreadline5-dev.
  - debian/gnupg2.dev: udev rules to set ACLs on SCM smartcard readers.
  - debian/rules: Call dh_installudev.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/gpgsm.texi
29
29
 
30
30
@mansect description
31
31
@command{gpgsm} is a tool similar to @command{gpg} to provide digital
32
 
encryption and signing servicesd on X.509 certificates and the CMS
 
32
encryption and signing services on X.509 certificates and the CMS
33
33
protocol.  It is mainly used as a backend for S/MIME mail processing.
34
34
@command{gpgsm} includes a full features certificate management and
35
35
complies with all rules defined for the German Sphinx project.
82
82
 
83
83
@item --help, -h
84
84
@opindex help
85
 
Print a usage message summarizing the most usefule command-line options.
 
85
Print a usage message summarizing the most useful command-line options.
86
86
Note that you cannot abbreviate this command.
87
87
 
88
88
@item --warranty
123
123
@item --verify
124
124
@opindex verify
125
125
Check a signature file for validity.  Depending on the arguments a
126
 
detached signatrue may also be checked.
 
126
detached signature may also be checked.
127
127
 
128
128
@item --server
129
129
@opindex server
134
134
Behave as a Dirmngr client issuing the request @var{command} with the
135
135
optional list of @var{args}.  The output of the Dirmngr is printed
136
136
stdout.  Please note that file names given as arguments should have an
137
 
absulte file name (i.e. commencing with @code{/} because they are
 
137
absolute file name (i.e. commencing with @code{/} because they are
138
138
passed verbatim to the Dirmngr and the working directory of the
139
139
Dirmngr might not be the same as the one of this client.  Currently it
140
140
is not possible to pass data via stdin to the Dirmngr.  @var{command}
165
165
@table @gnupgtabopt
166
166
@item --gen-key
167
167
@opindex gen-key
168
 
This command allows the interactive creation of a certifcate signing
169
 
request.  It is commonly used along with the @option{--output} option to
170
 
save the created CSR into a file.
 
168
This command allows the creation of a certificate signing request.  It
 
169
is commonly used along with the @option{--output} option to save the
 
170
created CSR into a file.  If used with the @option{--batch} a parameter
 
171
file is used to create the CSR.
171
172
 
172
173
@item --list-keys
173
174
@itemx -k 
218
219
@opindex keydb-clear-some-cert-flags
219
220
This is a debugging aid to reset certain flags in the key database
220
221
which are used to cache certain certificate stati.  It is especially
221
 
useful if a bad CRL or a weird running OCSP reponder did accidently
 
222
useful if a bad CRL or a weird running OCSP responder did accidentally
222
223
revoke certificate.  There is no security issue with this command
223
224
because @command{gpgsm} always make sure that the validity of a certificate is
224
225
checked right before it is used.
285
286
@node GPGSM Options
286
287
@section Option Summary
287
288
 
288
 
@command{GPGSM} comes features a bunch ofoptions to control the exact behaviour
 
289
@command{GPGSM} comes features a bunch of options to control the exact behaviour
289
290
and to change the default configuration.
290
291
 
291
292
@menu 
303
304
@node Configuration Options
304
305
@subsection How to change the configuration
305
306
 
306
 
These options are used to change the configuraton and are usually found
 
307
These options are used to change the configuration and are usually found
307
308
in the option file.
308
309
 
309
310
@table @gnupgtabopt
334
335
@opindex agent-program
335
336
Specify an agent program to be used for secret key operations.  The
336
337
default value is the @file{/usr/local/bin/gpg-agent}.  This is only used
337
 
as a fallback when the envrionment variable @code{GPG_AGENT_INFO} is not
 
338
as a fallback when the environment variable @code{GPG_AGENT_INFO} is not
338
339
set or a running agent can't be connected.
339
340
  
340
341
@item --dirmngr-program @var{file}
407
408
@opindex force-crl-refresh
408
409
Tell the dirmngr to reload the CRL for each request.  For better
409
410
performance, the dirmngr will actually optimize this by suppressing
410
 
the loading for short time intervalls (e.g. 30 minutes). This option
 
411
the loading for short time intervals (e.g. 30 minutes). This option
411
412
is useful to make sure that a fresh CRL is available for certificates
412
413
hold in the keybox.  The suggested way of doing this is by using it
413
414
along with the option @option{--with-validation} for a key listing
429
430
@opindex auto-issuer-key-retrieve
430
431
If a required certificate is missing while validating the chain of
431
432
certificates, try to load that certificate from an external location.
432
 
This usually means that Dirmngr is employed t search for the
 
433
This usually means that Dirmngr is employed to search for the
433
434
certificate.  Note that this option makes a "web bug" like behavior
434
435
possible.  LDAP server operators can see which keys you request, so by
435
436
sending you a message signed by a brand new key (which you naturally
536
537
 
537
538
When used along with --import, a validation of the certificate to
538
539
import is done and only imported if it succeeds the test.  Note that
539
 
this does not affect an already available cwertificate in the DB.
 
540
this does not affect an already available certificate in the DB.
540
541
This option is therefore useful to simply verify a certificate.
541
542
 
542
543
 
591
592
@opindex extra-digest-algo
592
593
Sometimes signatures are broken in that they announce a different digest
593
594
algorithm than actually used.  @command{gpgsm} uses a one-pass data
594
 
processing model and thus needs to rely on the announcde digest
 
595
processing model and thus needs to rely on the announced digest
595
596
algorithms to properly hash the data.  As a workaround this option may
596
597
be used to tell gpg to also hash the data using the algorithm
597
598
@var{name}; this slows processing down a little bit but allows to verify
604
605
@opindex faked-system-time
605
606
This option is only useful for testing; it sets the system time back or
606
607
forth to @var{epoch} which is the number of seconds elapsed since the year
607
 
1970.  Alternativly @var{epoch} may be given as a full ISO time string
 
608
1970.  Alternatively @var{epoch} may be given as a full ISO time string
608
609
(e.g. "20070924T154812").
609
610
 
610
611
@item --with-ephemeral-keys
661
662
trace Assuan protocol
662
663
@end table
663
664
 
664
 
Note, that all flags set using this option may get overriden by
 
665
Note, that all flags set using this option may get overridden by
665
666
@code{--debug-level}.
666
667
 
667
668
@item --debug-all
684
685
@item --debug-ignore-expiration
685
686
@opindex debug-ignore-expiration
686
687
This is actually not a debugging option but only useful as such.  It
687
 
lets @command{gpgsm} ignore all notAfter dates, this is used by the regresssion
 
688
lets @command{gpgsm} ignore all notAfter dates, this is used by the regression
688
689
tests.
689
690
 
690
691
@item --fixed-passphrase @var{string}
733
734
startup.  It may contain any valid long option; the leading two dashes
734
735
may not be entered and the option may not be abbreviated.  This default
735
736
name may be changed on the command line (@pxref{option
736
 
  --options}).
 
737
  --options}).  You should backup this file.
 
738
 
737
739
 
738
740
@item policies.txt
739
741
@cindex policies.txt
742
744
lines starting with a hash mark are ignored.  Policies missing in this
743
745
file and not marked as critical in the certificate will print only a
744
746
warning; certificates with policies marked as critical and not listed
745
 
in this file will fail the signature verification.
 
747
in this file will fail the signature verification.  You should backup
 
748
this file.
746
749
 
747
750
For example, to allow only the policy 2.289.9.9, the file should look
748
751
like this:
817
820
@c man:.RE
818
821
Note that on larger installations, it is useful to put predefined files
819
822
into the directory @file{/etc/skel/.gnupg/} so that newly created users
820
 
start up with a working configuration.  For existing users the a small
 
823
start up with a working configuration.  For existing users a small
821
824
helper script is provided to create these files (@pxref{addgnupghome}).
822
825
 
823
 
For internal purposes gpgsm creates and maintaines a few other files;
 
826
For internal purposes gpgsm creates and maintains a few other files;
824
827
they all live in in the current home directory (@pxref{option
825
828
--homedir}).  Only @command{gpgsm} may modify these files.
826
829
 
830
833
@cindex pubring.kbx
831
834
This a database file storing the certificates as well as meta
832
835
information.  For debugging purposes the tool @command{kbxutil} may be
833
 
used to show the internal structure of this file.
 
836
used to show the internal structure of this file.  You should backup
 
837
this file.
834
838
 
835
839
@item random_seed
836
840
@cindex random_seed
837
841
This content of this file is used to maintain the internal state of the
838
 
random number generator accross invocations.  The same file is used by
 
842
random number generator across invocations.  The same file is used by
839
843
other programs of this software too.
840
844
 
841
845
@item S.gpg-agent
844
848
not set, @command{gpgsm} will first try to connect to this socket for
845
849
accessing @command{gpg-agent} before starting a new @command{gpg-agent}
846
850
instance.  Under Windows this socket (which in reality be a plain file
847
 
describing a regular TCP litening port) is the standard way of
 
851
describing a regular TCP listening port) is the standard way of
848
852
connecting the @command{gpg-agent}.
849
853
 
850
854
@end table
890
894
 
891
895
It is very important to understand the semantics used with signature
892
896
verification.  Checking a signature is not as simple as it may sound and
893
 
so the ooperation si a bit complicated.  In mosted cases it is required
 
897
so the operation is a bit complicated.  In most cases it is required
894
898
to look at several status lines.  Here is a table of all cases a signed
895
899
message may have:
896
900
 
915
919
 
916
920
@item The signature is invalid
917
921
This means that the signature verification failed (this is an indication
918
 
of af a transfer error, a programm error or tampering with the message).
 
922
of af a transfer error, a program error or tampering with the message).
919
923
@command{gpgsm} issues one of these status codes sequences:
920
924
  @table @code
921
925
  @item  @code{BADSIG}
967
971
@node GPGSM ENCRYPT
968
972
@subsection Encrypting a Message
969
973
 
970
 
Before encrytion can be done the recipient must be set using the
 
974
Before encryption can be done the recipient must be set using the
971
975
command:
972
976
 
973
977
@example
1082
1086
OUTPUT.  With @code{--detached}, a detached signature is created
1083
1087
(surprise).
1084
1088
 
1085
 
The key used for signining is the default one or the one specified in
 
1089
The key used for signing is the default one or the one specified in
1086
1090
the configuration file.  To get finer control over the keys, it is
1087
1091
possible to use the command
1088
1092
 
1218
1222
To import certificates into the internal key database, the command
1219
1223
 
1220
1224
@example
1221
 
  IMPORT
 
1225
  IMPORT [--re-import]
1222
1226
@end example
1223
1227
 
1224
1228
is used.  The data is expected on the file descriptor set with the
1225
 
@code{INPUT} command.  Certain checks are performend on the
1226
 
certificate.  Note that the code will also handle PKCS\#12 files and
 
1229
@code{INPUT} command.  Certain checks are performed on the
 
1230
certificate.  Note that the code will also handle PKCS#12 files and
1227
1231
import private keys; a helper program is used for that.
1228
1232
 
 
1233
With the option @option{--re-import} the input data is expected to a be
 
1234
a linefeed separated list of fingerprints.  The command will re-import
 
1235
the corresponding certificates; that is they are made permanent by
 
1236
removing their ephemeral flag.
 
1237
 
1229
1238
 
1230
1239
@node GPGSM DELETE
1231
1240
@subsection Delete certificates
1258
1267
Return the version of the program.
1259
1268
@item pid
1260
1269
Return the process id of the process.
 
1270
@item agent-check
 
1271
Return success if the agent is running.
 
1272
@item cmd_has_option @var{cmd} @var{opt}
 
1273
Return success if the command @var{cmd} implements the option @var{opt}.
 
1274
The leading two dashes usually used with @var{opt} shall not be given.
1261
1275
@end table
1262
1276
 
1263
1277
@mansect see also