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