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