fixed severe exploit
[gnupg.git] / doc / gpg.1pod
1 =head1 NAME
2
3 gpg - GNU Privacy Guard
4
5 =head1 SYNOPSIS
6
7 B<gpg> [--homedir name] [--options file] [options] command [args]
8 B<gpgm> [--homedir name] [--options file] [options] command [args]
9
10 =head1 DESCRIPTION
11
12 B<gpg> is the main program for the GNUPG system. B<gpgm> is a maintenance
13 tool which has some commands B<gpgm> does not have; it is there because
14 it does not handle sensitive data ans therefore has no need to allocate
15 secure memory.
16
17 =head1 COMMANDS
18
19 B<gpg> recognizes these commands:
20
21 B<-s>, B<--sign>
22     Make a signature. This option may be combined
23     with B<--encrypt>.
24
25 B<--clearsign>
26     Make a clear text signature.
27
28 B<-b>, B<--detach-sign>
29     Make a detached signature.
30
31 B<-e>, B<--encrypt>
32     Encrypt data. This option may be combined with B<--sign>.
33
34 B<-c>, B<--symmetric>
35     Encrypt with symmetric cipher only
36     This command asks for a passphrase.
37
38 B<--store>
39     store only (make a simple RFC1991 packet).
40
41 B<--decrypt> [I<file>]
42     Decrypt file (or stdin if no file is specified) and
43     write it to stdout (or the file specified with
44     B<--output>). If the decrypted file is signed, the
45     signature is also verified. This command differs
46     from the default operation, as it never writes to the
47     filename which is included in the file and it
48     rejects files which don't begin with an encrypted
49     message.
50
51 B<--verify> [[I<sigfile>] {I<signed-files>}]
52     Assume that I<filename> is a signature and verify it
53     without generating any output.  With no arguments,
54     the signature packet is read from stdin (it may be a
55     detached signature when not used in batch mode). If
56     only a sigfile is given, it may be a complete signature
57     or a detached signature, in which case the signed stuff
58     is expected from stdin. With more than 1 argument, the
59     first should be a detached signature and the remaining
60     files are the signed stuff.
61
62 B<-k> [I<username>] [I<keyring>]
63     Kludge to be somewhat compatible with PGP.
64     Without arguments, all public keyrings are listed.
65     With one argument, only I<keyring> is listed.
66     Special combinations are also allowed, but it may
67     give strange results when combined with more options.
68     B<-kv>    Same as B<-k>
69     B<-kvv>   List the signatures with every key.
70     B<-kvvv>  Additionally check all signatures.
71     B<-kvc>   List fingerprints
72     B<-kvvc>  List fingerprints and signatures
73
74 B<--list-keys>  [I<names>]
75     List all keys from the default public keyring, or just the ones
76     given on the command line.
77
78 B<--list-sigs>  [I<names>]
79     Same as B<--list-keys>, but the signatures are listed too.
80
81 B<--check-sigs> [I<names>]
82     Same as B<--list-sigs>, but the signatures are verified.
83
84 B<--fingerprint> [I<names>]
85     List all keys with their fingerprints. This is the
86     same output as B<list-keys> but with the additonal output
87     of a line with the fingerprint. May also be combined
88     with B<--list-sigs> or B<--check-sigs>.
89
90 B<--list-packets>
91     List only the sequence of packets. This is mainly
92     useful for debugging.
93
94 B<--gen-key>
95     Generate a new key pair. This command can only be
96     used interactive.
97
98 B<--add-key> I<name>
99     Add a subkey to an already existing key. This
100     command is similiar to B<--gen-key> but a primary
101     key must already exit.
102
103 B<--sign-key> I<name>
104     Make a signature on key of user I<name>.
105     This looks for the key, displays the key and checks
106     all existing signatures of this key. If the key is
107     not yet signed by the default user (or the users given
108     with B<-u>), the program displays the information of
109     the key again, together with its fingerprint and
110     asks whether it should be signed. This question
111     is repeated for all users specified with B<-u>.
112     The key is then signed and the keyring which
113     contains the key is updated.
114
115
116 B<--delete-key>
117     Remove key from the public keyring
118
119 B<--delete-secret-key>
120     Remove key from the secret and public keyring
121
122 B<--edit-key>
123     Edit/remove a key signature.
124
125 B<--change-passphrase>
126     Change the passphrase of your secret keyring
127
128 B<--gen-revoke>
129     Generate a revocation certificate.
130
131 B<--export> [I<names>]
132     Either export all keys from all keyrings (default
133     keyrings and those registered via option B<--keyring>),
134     or if at least one name is given, those of the given
135     name. The new keyring is written to F<stdout> or to
136     the file given with option "output".  Use together
137     with B<-a> to mail those keys.
138
139 B<--import>
140     import/merge keys
141
142 B<--list-ownertrust>
143     List the assigned ownertrust values in ascii format for
144     backup purposes [B<gpgm> only].
145
146 =head1 OPTIONS
147
148 Long options can be put in an options file (default F<~/.gnupg/options>);
149 do not write the 2 dashes, but simply the name of the option and any
150 arguments if required.  Lines with a hash as the first non-white-space
151 character are ignored. Commands may be put in this file too, but that
152 does not make sense.
153
154 B<gpg> recognizes these options:
155
156
157 B<-a>, B<--armor>
158     Create ASCII armored output.
159
160 B<-o> I<file>, B<--output> I<file>
161     Write output to I<file>.
162
163 B<-u> I<name>, B<--local-user> I<name>
164     Use I<name> as the user-id to sign.
165     This option is silently ignored for the list commands,
166     so that it can be used in an options file.
167
168 B<--default-key>  I<name>
169     Use I<name> as default user-id for signatures.  If this
170     is not used the default user-id is the first user-id in
171     the secret keyring.
172
173 B<-r>  I<name>, B<--remote-user>  I<name>
174     Use I<name> as the user-id for encryption.
175     This option is silently ignored for the list commands,
176     so that it can be used in an options file.
177
178 B<-v>, B<--verbose>
179     Give more information during processing. If used
180     twice, the input data is listed in detail.
181
182
183 B<-z> I<n>
184     Set compress level to I<n>. A value of 0 for I<n>
185     disables compression. Default is to use the default
186     compression level of zlib (which is 6).
187
188 B<-t>, B<--textmode>
189     Use canonical text mode.  Used to make clear-text
190     signatures.
191
192 B<-n>, B<--dry-run>
193     Don't make any changes (not yet implemented).
194
195 B<--batch>
196     Batch mode; never ask, do not allow interactive
197     commands.
198
199 B<--no-batch>
200     Disable batch mode; this may be used if B<batch>
201     is used in the options file.
202
203 B<--yes>
204     Assume yes on most questions.
205
206 B<--no>
207     Assume no on most questions.
208
209 B<--keyring> I<file>
210     Add I<file> to the list of keyrings.
211     If I<file> begins with a tilde and a slash, these
212     are replaced by the HOME directory. If the filename
213     does not contain a slash, it is assumed to be in the
214     home-directory (F<~/.gnupg> if B<--homedir>) is not used.
215
216 B<--secret-keyring> I<file>
217     Same as B<--keyring> but for secret keyrings.
218
219
220 B<--homedir> I<dir>
221     Set the name of the home directory to I<dir>. If this
222     option is not used it defaults to F<~/.gnupg>. It does
223     not make sense to use this in a options file. This
224     also overrides the environment variable C<GNUPGHOME>.
225
226 B<--options> I<file>
227     Read options from I<file> and do not try to read
228     them from the default options file in the homedir
229     (see B<--homedir>). This option is ignored when used
230     in an options file.
231
232 B<--no-options>
233     Shortcut for B<--options> I</dev/null>.  This option is
234     detected before an attempt to open an option file.
235
236 B<--load-extension> I<modulename>
237     Load an extension module. If I<modulename> does not
238     contain a slash it is searched in B</usr/local/lib/gnupg>
239     See the manual for more information about extensions.
240
241 B<--debug> I<flags>
242     Set debugging flags. All flags are or-ed and I<flags> may
243     be given in C syntax (e.g. 0x0042).
244
245 B<--debug-all>
246     Set all useful debugging flags.
247
248 B<--status-fd> I<n>
249     Write special status strings to the file descriptor I<n>.
250
251 B<--no-comment>
252     Do not write comment packets.
253
254 B<--completes-needed> I<n>
255     Number of completely trusted users to introduce a new
256     key signator (defaults to 1).
257
258 B<--marginals-needed> I<n>
259     Number of marginally trusted users to introduce a new
260     key signator (defaults to 3)
261
262 B<--cipher-algo> I<name>
263     Use I<name> as cipher algorithm. Running the program
264     with the option B<--verbose> yields a list of supported
265     algorithms.
266
267 B<--digest-algo> I<name>
268     Use I<name> as message digest algorithm. Running the
269     program with the option B<--verbose> yields a list of
270     supported algorithms.
271
272 B<--compress-algo> I<number>
273     Use compress algorithm I<number>. Default is I<2> which is
274     RFC1950 compression; you may use I<1> to use the old zlib
275     version which is used by PGP. This is only used for
276     new messages. The default algorithm may give better
277     results because the window size is not limited to 8K.
278
279 B<--passphrase-fd> I<n>
280     Read the passphrase from file descriptor I<n>. If you use
281     0 for I<n>, the passphrase will be read from stdin.  This
282     can only be used if only one passphrase is supplied.
283     B<Don't use this option if you can avoid it>
284
285 B<--no-verbose>
286     Reset verbose level to 0.
287
288 B<--no-greeting>
289     Suppress the initial copyright message but do not
290     enter batch mode.
291
292 B<--no-armor>
293     Assume the input data is not in ASCCI armored format.
294
295 B<--no-default-keyring>
296     Do not add the default keyrings to the list of
297     keyrings.
298
299 B<--skip-verify>
300     Skip the signature verification step.  This may be used to
301     make the encryption faster if the signature verification
302     is not needed.
303
304 B<--version>
305     Print version information along with a list
306     of supported algorithms.
307
308 B<--with-colons>
309     Print key listings delimited by colons.
310
311 B<--warranty>
312     Print warranty information.
313
314 B<-h>, B<--help>
315     Print usage information.
316
317
318 =head1 RETURN VALUE
319
320 The Program returns 0 if everything was fine, 1 if at least
321 a signature was bad and other errorcode for fatal errors.
322
323 =head1 EXAMPLES
324
325   -se -r Bob [file]          sign and encrypt for user Bob
326   -sat [file]                make a clear text signature
327   -sb  [file]                make a detached signature
328   -k   [userid]              show keys
329   -kc  [userid]              show fingerprint
330
331 =head1 ENVIRONMENT
332
333 C<HOME>       Used to locate the default home directory.
334 C<GNUPGHOME>  If set, direcory used instead of F<~/.gnupg>.
335
336 =head1 FILES
337
338 F<~/.gnupg/secring.gpg>     The secret keyring
339
340 F<~/.gnupg/pubring.gpg>     The public keyring
341
342 F<~/.gnupg/trustdb.gpg>     The trust database
343
344 F<~/.gnupg/options>         May contain options
345
346 =head1 SEE ALSO
347
348 gpgm(1)  gpgd(1)
349
350
351 =head1 WARNINGS
352
353 Use a B<good> password for your user account and a B<good> passphrase
354 to protect your secret key.  This passphrase is the weakest part of the
355 whole system.  Programs to do dictionary attacks on your secret keyring
356 are very easy to write and so you should protect your B<~/.gnupg/>
357 directory very good.
358
359 Keep in mind that, if this program is used over a network (telnet), it
360 is B<very> easy to spy out your passphrase!
361
362 =head1 BUGS
363
364 On many systems this program should be installed as setuid(root); this
365 is necessary to lock some pages of memory. If you get no warning message
366 about insecure memory you have a nice OS kernel and you don't need to make
367 it setuid.
368