← Back to branch summary

~ubuntu-branches/ubuntu/feisty/gnupg2/feisty

« back to all changes in this revision

Viewing changes to doc/gpgsm.texi

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2006-11-24 18:48:23 UTC
  • mfrom: (1.1.4 upstream)
  • Revision ID: james.westby@ubuntu.com-20061124184823-17ir9m46tl09n9k4
Tags: 2.0.0-4ubuntu1
* Synchronize to Debian, reapply remaining Ubuntu changes to pristine Debian
  version:
  - Remove libpcsclite-dev, libopensc2-dev build dependencies (they are in
    universe).

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/gpgsm.texi
8
8
@cindex command options
9
9
@cindex options, GPGSM command
10
10
 
11
 
@c man begin DESCRIPTION
12
 
 
 
11
@manpage gpgsm.1
 
12
@ifset manverb
 
13
.B gpgsm
 
14
\- CMS encryption and signing tool
 
15
@end ifset
 
16
 
 
17
@mansect synopsis
 
18
@ifset manverb
 
19
.B  gpgsm
 
20
.RB [ \-\-homedir
 
21
.IR dir ]
 
22
.RB [ \-\-options
 
23
.IR file ]
 
24
.RI [ options ]  
 
25
.I command
 
26
.RI [ args ]
 
27
@end ifset
 
28
 
 
29
 
 
30
@mansect description
13
31
@command{gpgsm} is a tool similar to @command{gpg} to provide digital
14
32
encryption and signing servicesd on X.509 certificates and the CMS
15
33
protocol.  It is mainly used as a backend for S/MIME mail processing.
16
34
@command{gpgsm} includes a full features certificate management and
17
35
complies with all rules defined for the German Sphinx project.
18
36
 
19
 
@c man end
20
 
 
 
37
@manpause
21
38
@xref{Option Index}, for an index to @command{GPGSM}'s commands and options.
 
39
@mancont
22
40
 
23
41
@menu
24
42
* GPGSM Commands::        List of all commands.
31
49
* GPGSM Protocol::        The protocol the server mode uses.
32
50
@end menu
33
51
 
34
 
@c man begin COMMANDS
35
 
 
 
52
@c *******************************************
 
53
@c ***************            ****************
 
54
@c ***************  COMMANDS  ****************
 
55
@c ***************            ****************
 
56
@c *******************************************
 
57
@mansect commands
36
58
@node GPGSM Commands
37
59
@section Commands
38
60
 
39
61
Commands are not distinguished from options execpt for the fact that
40
 
only one one command is allowed.
 
62
only one command is allowed.
41
63
 
42
64
@menu
43
 
* General Commands::        Commands not specific to the functionality.
44
 
* Operational Commands::    Commands to select the type of operation.
45
 
* Certificate Management::  How to manage certificates.
 
65
* General GPGSM Commands::        Commands not specific to the functionality.
 
66
* Operational GPGSM Commands::    Commands to select the type of operation.
 
67
* Certificate Management::        How to manage certificates.
46
68
@end menu
47
69
 
48
 
@node General Commands
 
70
 
 
71
@c *******************************************
 
72
@c **********  GENERAL COMMANDS  *************
 
73
@c *******************************************
 
74
@node General GPGSM Commands
49
75
@subsection Commands not specific to the function
50
76
 
51
77
@table @gnupgtabopt
59
85
Print a usage message summarizing the most usefule command-line options.
60
86
Not that you can abbreviate this command.
61
87
 
 
88
@item --warranty
 
89
@opindex warranty
 
90
Print warranty information.
 
91
 
62
92
@item --dump-options
63
93
@opindex dump-options
64
94
Print a list of all available options and commands.  Not that you can
66
96
@end table
67
97
 
68
98
 
69
 
 
70
 
@node Operational Commands
 
99
@c *******************************************
 
100
@c ********  OPERATIONAL COMMANDS  ***********
 
101
@c *******************************************
 
102
@node Operational GPGSM Commands
71
103
@subsection Commands to select the type of operation
72
104
 
73
105
@table @gnupgtabopt
74
106
@item --encrypt
75
107
@opindex encrypt
76
 
Perform an encryption.
 
108
Perform an encryption.  The keys the data is encrypted too must be set
 
109
using the option @option{--recipient}.
77
110
 
78
111
@item --decrypt
79
112
@opindex decrypt
80
 
Perform a decryption; the type of input is automatically detmerined.  It
 
113
Perform a decryption; the type of input is automatically determined.  It
81
114
may either be in binary form or PEM encoded; automatic determination of
82
115
base-64 encoding is not done.
83
116
 
84
117
@item --sign
85
118
@opindex sign
86
119
Create a digital signature.  The key used is either the fist one found
87
 
in the keybox or thise set with the -u option
 
120
in the keybox or those set with the @option{--local-user} option.
88
121
 
89
122
@item --verify
90
123
@opindex verify
122
155
@end table
123
156
 
124
157
 
 
158
@c *******************************************
 
159
@c *******  CERTIFICATE MANAGEMENT  **********
 
160
@c *******************************************
125
161
@node Certificate Management
126
 
@subsection How to manage the certificate and keys
 
162
@subsection How to manage the certificates and keys
127
163
 
128
164
@table @gnupgtabopt
129
165
@item --gen-key
148
184
List certificates matching @var{pattern} using an external server.  This
149
185
utilizes the @code{dirmngr} service.  
150
186
 
151
 
@item --dump-keys
 
187
@item --list-chain
 
188
@opindex list-chain
 
189
Same as @option{--list-keys} but also prints all keys making up the chain.
 
190
 
 
191
 
 
192
@item --dump-cert
 
193
@itemx --dump-keys
 
194
@opindex dump-cert
152
195
@opindex dump-keys
153
196
List all available certificates stored in the local key database using a
154
197
format useful mainly for debugging.
155
198
 
 
199
@item --dump-chain
 
200
@opindex dump-chain
 
201
Same as @option{--dump-keys} but also prints all keys making up the chain.
 
202
 
156
203
@item --dump-secret-keys
157
204
@opindex dump-secret-keys
158
205
List all available certificates for which a corresponding a secret key
200
247
@item --learn-card
201
248
@opindex learn-card
202
249
Read information about the private keys from the smartcard and import
203
 
the certificates from there.  This command utilizes the @sc{gpg-agent}
204
 
and in turn the @sc{scdaemon}.
 
250
the certificates from there.  This command utilizes the @command{gpg-agent}
 
251
and in turn the @command{scdaemon}.
205
252
 
206
253
@item --passwd @var{user_id}
207
254
@opindex passwd
212
259
@end table
213
260
 
214
261
 
 
262
@c *******************************************
 
263
@c ***************            ****************
 
264
@c ***************  OPTIONS   ****************
 
265
@c ***************            ****************
 
266
@c *******************************************
 
267
@mansect options
215
268
@node GPGSM Options
216
269
@section Option Summary
217
270
 
226
279
* Esoteric Options::        Doing things one usually don't want to do.
227
280
@end menu
228
281
 
229
 
@c man begin OPTIONS
230
282
 
 
283
@c *******************************************
 
284
@c ********  CONFIGURATION OPTIONS  **********
 
285
@c *******************************************
231
286
@node Configuration Options
232
287
@subsection How to change the configuration
233
288
 
243
298
@file{gpgsm.conf} and expected in the @file{.gnupg} directory directly
244
299
below the home directory of the user.
245
300
 
246
 
@item --homedir @var{dir}
247
 
@opindex homedir
248
 
Set the name of the home directory to @var{dir}. If his option is not
249
 
used, the home directory defaults to @file{~/.gnupg}.  It is only
250
 
recognized when given on the command line.  It also overrides any home
251
 
directory stated through the environment variable @env{GNUPGHOME} or
252
 
(on W32 systems) by means on the Registry entry
253
 
@var{HKCU\Software\GNU\GnuPG:HomeDir}.
 
301
@include opt-homedir.texi
254
302
 
255
303
 
256
304
@item -v
296
344
@end table
297
345
 
298
346
 
 
347
@c *******************************************
 
348
@c ********  CERTIFICATE OPTIONS  ************
 
349
@c *******************************************
299
350
@node Certificate Options
300
351
@subsection Certificate related options
301
352
 
326
377
certificates into a CRL.  The disable option may be used to switch this
327
378
extra check off.  Due to the caching done by the Dirmngr, there won't be
328
379
any noticeable performance gain.  Note, that this also disables possible
329
 
OCSP checks for trusted root certificates.
 
380
OCSP checks for trusted root certificates.  A more specific way of
 
381
disabling this check is by adding the ``relax'' keyword to the root CA
 
382
line of the @file{trustlist.txt}
 
383
 
330
384
 
331
385
@item --force-crl-refresh
332
386
@opindex force-crl-refresh
335
389
the loading for short time intervalls (e.g. 30 minutes). This option
336
390
is useful to make sure that a fresh CRL is available for certificates
337
391
hold in the keybox.  The suggested way of doing this is by using it
338
 
along with the option @option{--with-validation} for a ke listing
 
392
along with the option @option{--with-validation} for a key listing
339
393
command.  This option should not be used in a configuration file. 
340
394
 
341
395
@item  --enable-ocsp
352
406
 
353
407
@end table
354
408
 
 
409
@c *******************************************
 
410
@c ***********  INPUT AND OUTPUT  ************
 
411
@c *******************************************
355
412
@node Input and Output
356
413
@subsection Input and Output
357
414
 
386
443
Set the user(s) to be used for signing.  The default is the first
387
444
secret key found in the database.
388
445
 
 
446
 
 
447
@item --recipient @var{name}
 
448
@itemx -r
 
449
@opindex recipient
 
450
Encrypt to the user id @var{name}.  There are several ways a user id
 
451
may be given (@pxref{how-to-specify-a-user-id}).
 
452
 
 
453
 
 
454
@item --output @var{file}
 
455
@itemx -o @var{file}
 
456
@opindex output
 
457
Write output to @var{file}.  The default is to write it to stdout.
 
458
 
 
459
 
389
460
@item --with-key-data
390
461
@opindex with-key-data
391
462
Displays extra information with the @code{--list-keys} commands.  Especially
411
482
 
412
483
@end table
413
484
 
 
485
@c *******************************************
 
486
@c *************  CMS OPTIONS  ***************
 
487
@c *******************************************
414
488
@node CMS Options
415
489
@subsection How to change how the CMS is created.
416
490
 
417
491
@table @gnupgtabopt
418
492
@item --include-certs @var{n}
 
493
@opindex include-certs
419
494
Using @var{n} of -2 includes all certificate except for the root cert,
420
495
-1 includes all certs, 0 does not include any certs, 1 includes only
421
496
the signers cert (this is the default) and all other positive
422
497
values include up to @var{n} certificates starting with the signer cert.
 
498
 
 
499
 
 
500
@item --cipher-algo @var{oid}
 
501
@opindex cipher-algo
 
502
Use the cipher algorithm with the ASN.1 object identifier @var{oid} for
 
503
encryption.  For convenience the strings @code{3DES}, @code{AES} and
 
504
@code{AES256} may be used instead of their OIDs.  The default is
 
505
@code{3DES} (1.2.840.113549.3.7).
423
506
  
424
507
@end table
425
508
 
426
509
 
427
510
 
 
511
@c *******************************************
 
512
@c ********  ESOTERIC OPTIONS  ***************
 
513
@c *******************************************
428
514
@node Esoteric Options
429
515
@subsection Doing things one usually don't want to do.
430
516
 
446
532
Select the debug level for investigating problems. @var{level} may be
447
533
one of:
448
534
 
449
 
   @table @code
450
 
   @item none
451
 
   no debugging at all.
452
 
   @item basic  
453
 
   some basic debug messages
454
 
   @item advanced
455
 
   more verbose debug messages
456
 
   @item expert
457
 
   even more detailed messages
458
 
   @item guru
459
 
   all of the debug messages you can get
460
 
   @end table
 
535
@table @code
 
536
@item none
 
537
no debugging at all.
 
538
@item basic  
 
539
some basic debug messages
 
540
@item advanced
 
541
more verbose debug messages
 
542
@item expert
 
543
even more detailed messages
 
544
@item guru
 
545
all of the debug messages you can get
 
546
@end table
461
547
 
462
548
How these messages are mapped to the actual debugging flags is not
463
549
specified and may change with newer releaes of this program. They are
470
556
preferred method to select the debug verbosity.  FLAGS are bit encoded
471
557
and may be given in usual C-Syntax. The currently defined bits are:
472
558
 
473
 
   @table @code
474
 
   @item 0  (1)
475
 
   X.509 or OpenPGP protocol related data
476
 
   @item 1  (2)  
477
 
   values of big number integers 
478
 
   @item 2  (4)
479
 
   low level crypto operations
480
 
   @item 5  (32)
481
 
   memory allocation
482
 
   @item 6  (64)
483
 
   caching
484
 
   @item 7  (128)
485
 
   show memory statistics.
486
 
   @item 9  (512)
487
 
   write hashed data to files named @code{dbgmd-000*}
488
 
   @item 10 (1024)
489
 
   trace Assuan protocol
490
 
   @end table
 
559
@table @code
 
560
@item 0  (1)
 
561
X.509 or OpenPGP protocol related data
 
562
@item 1  (2)  
 
563
values of big number integers 
 
564
@item 2  (4)
 
565
low level crypto operations
 
566
@item 5  (32)
 
567
memory allocation
 
568
@item 6  (64)
 
569
caching
 
570
@item 7  (128)
 
571
show memory statistics.
 
572
@item 9  (512)
 
573
write hashed data to files named @code{dbgmd-000*}
 
574
@item 10 (1024)
 
575
trace Assuan protocol
 
576
@end table
491
577
 
492
578
Note, that all flags set using this option may get overriden by
493
579
@code{--debug-level}.
526
612
All the long options may also be given in the configuration file after
527
613
stripping off the two leading dashes.
528
614
 
529
 
 
530
 
@c man begin FILES
531
 
 
 
615
@c *******************************************
 
616
@c ***************            ****************
 
617
@c ***************  USER ID   ****************
 
618
@c ***************            ****************
 
619
@c *******************************************
 
620
@mansect how to specify a user id
 
621
@ifset isman
 
622
@include specify-user-id.texi
 
623
@end ifset
 
624
 
 
625
@c *******************************************
 
626
@c ***************            ****************
 
627
@c ***************   FILES    ****************
 
628
@c ***************            ****************
 
629
@c *******************************************
 
630
@mansect files
532
631
@node GPGSM Configuration
533
632
@section Configuration files
534
633
 
558
657
For example, to allow only the policy 2.289.9.9, the file should look
559
658
like this:
560
659
 
 
660
@c man:.RS
561
661
@example
562
662
# Allowed policies
563
663
2.289.9.9  
564
664
@end example
 
665
@c man:.RE
565
666
 
566
667
@item qualified.txt
567
668
@cindex qualified.txt
601
702
 
602
703
@end table
603
704
 
 
705
@c man:.RE
604
706
Note that on larger installations, it is useful to put predefined files
605
707
into the directory @file{/etc/skel/.gnupg/} so that newly created users
606
708
start up with a working configuration.  For existing users the a small
607
709
helper script is provided to create these files (@pxref{addgnupghome}).
608
710
 
609
 
 
610
711
For internal purposes gpgsm creates and maintaines a few other files;
611
712
They all live in in the current home directory (@pxref{option
612
713
--homedir}).  Only @command{gpgsm} may modify these files.
613
714
 
 
715
 
614
716
@table @file
615
717
@item pubring.kbx
616
718
@cindex pubring.kbx
627
729
@end table
628
730
 
629
731
 
630
 
@c 
631
 
@c  Examples
632
 
@c
 
732
@c *******************************************
 
733
@c ***************            ****************
 
734
@c ***************  EXAMPLES  ****************
 
735
@c ***************            ****************
 
736
@c *******************************************
 
737
@mansect examples
633
738
@node GPGSM Examples
634
739
@section Examples
635
740
 
636
 
@c man begin EXAMPLES
637
 
 
638
741
@example
639
742
$ gpgsm -er goo@@bar.net <plaintext >ciphertext
640
743
@end example
641
744
 
 
745
 
642
746
@c man end
643
747
 
644
748
 
645
 
 
646
 
@c ---------------------------------
647
 
@c    The machine interface
648
 
@c --------------------------------
 
749
@c *******************************************
 
750
@c ***************              **************
 
751
@c ***************  UNATTENDED  **************
 
752
@c ***************              **************
 
753
@c *******************************************
649
754
@node Unattended Usage
650
755
@section Unattended Usage
651
756
 
704
809
@end table
705
810
 
706
811
 
707
 
@c 
708
 
@c  Assuan Protocol
709
 
@c
 
812
@c *******************************************
 
813
@c ***************           *****************
 
814
@c ***************  ASSSUAN  *****************
 
815
@c ***************           *****************
 
816
@c *******************************************
 
817
@manpause
710
818
@node GPGSM Protocol
711
819
@section The Protocol the Server Mode Uses.
712
820
 
755
863
successful @code{ENCRYPT} command.
756
864
 
757
865
@example
758
 
  INPUT FD=@var{n} [--armor|--base64|--binary]
 
866
  INPUT FD[=@var{n}] [--armor|--base64|--binary]
759
867
@end example
760
868
 
761
869
Set the file descriptor for the message to be encrypted to @var{n}.
762
870
Obviously the pipe must be open at that point, the server establishes
763
871
its own end.  If the server returns an error the client should consider
764
 
this session failed.
 
872
this session failed.  If @var{n} is not given, this commands uses the
 
873
last file descriptor passed to the application.
 
874
@xref{fun-assuan_sendfd, ,the assuan_sendfd function,assuan,the Libassuan
 
875
manual}, on how to do descriptor passing.
765
876
 
766
877
The @code{--armor} option may be used to advice the server that the
767
878
input data is in @acronym{PEM} format, @code{--base64} advices that a
771
882
correct.
772
883
 
773
884
@example
774
 
  OUTPUT FD=@var{n} [--armor|--base64]
 
885
  OUTPUT FD[=@var{n}] [--armor|--base64]
775
886
@end example
776
887
 
777
888
Set the file descriptor to be used for the output (i.e. the encrypted
829
940
Signing is usually done with these commands:
830
941
 
831
942
@example
832
 
  INPUT FD=@var{n} [--armor|--base64|--binary]
 
943
  INPUT FD[=@var{n}] [--armor|--base64|--binary]
833
944
@end example
834
945
 
835
946
This tells @command{GPGSM} to read the data to sign from file descriptor @var{n}.
836
947
 
837
948
@example
838
 
  OUTPUT FD=@var{m} [--armor|--base64]
 
949
  OUTPUT FD[=@var{m}] [--armor|--base64]
839
950
@end example
840
951
 
841
952
Write the output to file descriptor @var{m}.  If a detached signature is
1004
1115
The certificates must be specified unambiguously otherwise an error is
1005
1116
returned.
1006
1117
 
 
1118
 
 
1119
@mansect see also
 
1120
@ifset isman
 
1121
@command{gpg2}(1), 
 
1122
@command{gpg-agent}(1)
 
1123
@end ifset
 
1124
@include see-also-note.texi