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 B<gpgm> [--homedir name] [--options file] [options] command [args]
  10
  11 =head1 DESCRIPTION
  12
  13 B<gpg> is the main program for the GNUPG system. B<gpgm> is a maintenance
  14 tool which has some commands B<gpgm> does not have; it is there because
  15 it does not handle sensitive data ans therefore has no need to allocate
  16 secure memory.
  17
  18 =head1 COMMANDS
  19
  20 B<gpg> recognizes these commands:
  21
  22 B<-s>, B<--sign>
  23     Make a signature. This option may be combined
  24     with B<--encrypt>.
  25
  26 B<--clearsign>
  27     Make a clear text signature.
  28
  29 B<-b>, B<--detach-sign>
  30     Make a detached signature.
  31
  32 B<-e>, B<--encrypt>
  33     Encrypt data. This option may be combined with B<--sign>.
  34
  35 B<-c>, B<--symmetric>
  36     Encrypt with symmetric cipher only
  37     This command asks for a passphrase.
  38
  39 B<--store>
  40     store only (make a simple RFC1991 packet).
  41
  42 B<--decrypt> [I<file>]
  43     Decrypt file (or stdin if no file is specified) and
  44     write it to stdout (or the file specified with
  45     B<--output>). If the decrypted file is signed, the
  46     signature is also verified. This command differs
  47     from the default operation, as it never writes to the
  48     filename which is included in the file and it
  49     rejects files which don't begin with an encrypted
  50     message.
  51
  52 B<--verify> [[I<sigfile>] {I<signed-files>}]
  53     Assume that I<filename> is a signature and verify it
  54     without generating any output.  With no arguments,
  55     the signature packet is read from stdin (it may be a
  56     detached signature when not used in batch mode). If
  57     only a sigfile is given, it may be a complete
  58     signature or a detached signature, in which case
  59     the signed stuff is expected in a file without the
  60     I<.sig> or I<.asc> extension (if such a file does
  61     not exist it is expected at stdin - use B<-> as
  62     filename to force a read from stdin). With more than
  63     1 argument, the first should be a detached signature
  64     and the remaining files are the signed stuff.
  65
  66 B<-k> [I<username>] [I<keyring>]
  67     Kludge to be somewhat compatible with PGP.
  68     Without arguments, all public keyrings are listed.
  69     With one argument, only I<keyring> is listed.
  70     Special combinations are also allowed, but it may
  71     give strange results when combined with more options.
  72     B<-kv>    Same as B<-k>
  73     B<-kvv>   List the signatures with every key.
  74     B<-kvvv>  Additionally check all signatures.
  75     B<-kvc>   List fingerprints
  76     B<-kvvc>  List fingerprints and signatures
  77
  78 B<--list-keys>  [I<names>]
  79     List all keys from the public keyrings, or just the
  80     ones given on the command line.
  81
  82 B<--list-secret-keys> [I<names>]
  83     List all keys from the secret keyrings, or just the
  84     ones given on the command line.
  85
  86 B<--list-sigs>  [I<names>]
  87     Same as B<--list-keys>, but the signatures are listed
  88     too.
  89
  90 B<--check-sigs> [I<names>]
  91     Same as B<--list-sigs>, but the signatures are verified.
  92
  93 B<--fingerprint> [I<names>]
  94     List all keys with their fingerprints. This is the
  95     same output as B<list-keys> but with the additonal output
  96     of a line with the fingerprint. May also be combined
  97     with B<--list-sigs> or B<--check-sigs>.
  98
  99 B<--list-packets>
 100     List only the sequence of packets. This is mainly
 101     useful for debugging.
 102
 103 B<--gen-key>
 104     Generate a new key pair. This command can only be
 105     used interactive.
 106
 107
 108 B<--edit-key> I<name>
 109     Present a menu which enables you to do all key
 110     related tasks:
 111     B<sign>
 112       Make a signature on key of user I<name>.
 113       If the key is not yet signed by the default
 114       user (or the users given with B<-u>), the
 115       program displays the information of the key
 116       again, together with its fingerprint and
 117       asks whether it should be signed. This
 118       question is repeated for all users specified
 119       with B<-u>.
 120     B<trust>
 121       Change the owner trust value. This updates the
 122       trust-db immediately and no save is required.
 123     B<adduid>
 124       Create an alternate user id.
 125     B<deluid>
 126       Delete an user id.
 127     B<addkey>
 128        Add a subkey to this key.
 129     B<delkey>
 130        Remove a subkey.
 131     B<passwd>
 132        Change the passphrase of the secret key.
 133     B<uid> I<n>
 134        Toggle selection of user id with index I<n>.
 135        Use 0 to deselect all.
 136     B<key> I<n>
 137        Toggle selection of subkey with index I<n>.
 138        Use 0 to deselect all.
 139     B<check>
 140        Check all selected user ids.
 141     B<pref>
 142        List preferences.
 143     B<toggle>
 144        Toggle between public and secret key listing.
 145     B<save>
 146        Save all changes to the key rings and quit.
 147     B<quit>
 148        Quit the program without updating the
 149        key rings.
 150     The listing shows you the key with its secondary
 151     keys and all user ids. Selected keys or user ids
 152     indicated by an asterisk. The trust value is
 153     displayed with the primary key: The first one is the
 154     assigned owner trust and the second the calculated
 155     trust value; letters are used for the values:
 156       B<->  No ownertrust assigned.
 157       B<o>  Trust not yet calculated.
 158       B<e>  Trust calculation failed.
 159       B<q>  Not enough information for calculation.
 160       B<n>  Never trust this key.
 161       B<m>  Marginally trusted.
 162       B<f>  Fully trusted.
 163       B<u>  Ultimately trusted
 164
 165
 166 B<--delete-key>
 167     Remove key from the public keyring
 168
 169 B<--delete-secret-key>
 170     Remove key from the secret and public keyring
 171
 172 B<--gen-revoke>
 173     Generate a revocation certificate.
 174
 175 B<--export> [I<names>]
 176     Either export all keys from all keyrings (default
 177     keyrings and those registered via option B<--keyring>),
 178     or if at least one name is given, those of the given
 179     name. The new keyring is written to F<stdout> or to
 180     the file given with option "output".  Use together
 181     with B<-a> to mail those keys.
 182
 183
 184 B<--export-secret-keys> [I<names>
 185     Same as B<--export>, but does export the secret keys.
 186     This is normally not very useful.
 187
 188 B<--import>
 189     import/merge keys
 190
 191 B<--export-ownertrust>
 192     List the assigned ownertrust values in ascii format
 193     for backup purposes [B<gpgm> only].
 194
 195 B<--import-ownertrust> [I<filename>]
 196     Update the trustdb with the ownertrust values stored
 197     in I<filename> (or stdin if not given); existing
 198     values will be overwritten. [B<gpgm> only].
 199
 200 =head1 OPTIONS
 201
 202 Long options can be put in an options file (default F<~/.gnupg/options>);
 203 do not write the 2 dashes, but simply the name of the option and any
 204 arguments if required.  Lines with a hash as the first non-white-space
 205 character are ignored. Commands may be put in this file too, but that
 206 does not make sense.
 207
 208 B<gpg> recognizes these options:
 209
 210
 211 B<-a>, B<--armor>
 212     Create ASCII armored output.
 213
 214 B<-o> I<file>, B<--output> I<file>
 215     Write output to I<file>.
 216
 217 B<-u> I<name>, B<--local-user> I<name>
 218     Use I<name> as the user-id to sign.
 219     This option is silently ignored for the list commands,
 220     so that it can be used in an options file.
 221
 222 B<--default-key>  I<name>
 223     Use I<name> as default user-id for signatures.  If this
 224     is not used the default user-id is the first user-id
 225     from the secret keyring.
 226
 227 B<-r>  I<name>, B<--remote-user>  I<name>
 228     Use I<name> as the user-id for encryption.
 229     This option is silently ignored for the list commands,
 230     so that it can be used in an options file.
 231
 232 B<-v>, B<--verbose>
 233     Give more information during processing. If used
 234     twice, the input data is listed in detail.
 235
 236
 237 B<-z> I<n>
 238     Set compress level to I<n>. A value of 0 for I<n>
 239     disables compression. Default is to use the default
 240     compression level of zlib (which is 6).
 241
 242 B<-t>, B<--textmode>
 243     Use canonical text mode.  Used to make clear-text
 244     signatures.
 245
 246 B<-n>, B<--dry-run>
 247     Don't make any changes (not yet implemented).
 248
 249 B<--batch>
 250     Batch mode; never ask, do not allow interactive
 251     commands.
 252
 253 B<--no-batch>
 254     Disable batch mode; this may be used if B<batch>
 255     is used in the options file.
 256
 257 B<--yes>
 258     Assume yes on most questions.
 259
 260 B<--no>
 261     Assume no on most questions.
 262
 263 B<--keyring> I<file>
 264     Add I<file> to the list of keyrings.
 265     If I<file> begins with a tilde and a slash, these
 266     are replaced by the HOME directory. If the filename
 267     does not contain a slash, it is assumed to be in the
 268     home-directory (F<~/.gnupg> if B<--homedir>) is not used.
 269
 270 B<--secret-keyring> I<file>
 271     Same as B<--keyring> but for secret keyrings.
 272
 273
 274 B<--homedir> I<dir>
 275     Set the name of the home directory to I<dir>. If this
 276     option is not used it defaults to F<~/.gnupg>. It does
 277     not make sense to use this in a options file. This
 278     also overrides the environment variable C<GNUPGHOME>.
 279
 280 B<--options> I<file>
 281     Read options from I<file> and do not try to read
 282     them from the default options file in the homedir
 283     (see B<--homedir>). This option is ignored when used
 284     in an options file.
 285
 286 B<--no-options>
 287     Shortcut for B<--options> I</dev/null>.  This option is
 288     detected before an attempt to open an option file.
 289
 290 B<--load-extension> I<modulename>
 291     Load an extension module. If I<modulename> does not
 292     contain a slash it is searched in B</usr/local/lib/gnupg>
 293     See the manual for more information about extensions.
 294
 295 B<--debug> I<flags>
 296     Set debugging flags. All flags are or-ed and I<flags> may
 297     be given in C syntax (e.g. 0x0042).
 298
 299 B<--debug-all>
 300     Set all useful debugging flags.
 301
 302 B<--status-fd> I<n>
 303     Write special status strings to the file descriptor I<n>.
 304
 305 B<--no-comment>
 306     Do not write comment packets.
 307
 308 B<--completes-needed> I<n>
 309     Number of completely trusted users to introduce a new
 310     key signator (defaults to 1).
 311
 312 B<--marginals-needed> I<n>
 313     Number of marginally trusted users to introduce a new
 314     key signator (defaults to 3)
 315
 316 B<--cipher-algo> I<name>
 317     Use I<name> as cipher algorithm. Running the program
 318     with the option B<--verbose> yields a list of supported
 319     algorithms. If this is not used the cipher algorithm is
 320     selected from the preferences stored with the key.
 321
 322 B<--digest-algo> I<name>
 323     Use I<name> as message digest algorithm. Running the
 324     program with the option B<--verbose> yields a list of
 325     supported algorithms.
 326
 327 B<--s2k-cipher-algo> I<name>
 328     Use I<name> as the cipher algorithm used to protect secret
 329     keys.  The default cipher is BLOWFISH.  This cipher is
 330     also used for conventional encryption if B<--cipher-algo>
 331     is not given.
 332
 333 B<--s2k-digest-algo> I<name>
 334     Use I<name> as the digest algorithm used to mangle the
 335     passphrases.  The default algorithm is RIPE-MD-160.
 336     This digest algorithm is also used for conventional
 337     encryption if B<--digest-algo> is not given.
 338
 339 B<--s2k-mode> I<number>
 340     Selects how passphrases are mangled: A number of I<0>
 341     uses the plain passphrase (which is not recommended),
 342     a I<1> (default) adds a salt to the passphrase and
 343     I<3> interates the whole process a couple of times.
 344     Unless -B<--rfc1991> is used, this mode is also used
 345     for conventional encryption.
 346
 347 B<--compress-algo> I<number>
 348     Use compress algorithm I<number>. Default is I<2> which is
 349     RFC1950 compression; you may use I<1> to use the old zlib
 350     version which is used by PGP. This is only used for
 351     new messages. The default algorithm may give better
 352     results because the window size is not limited to 8K.
 353     If this is not used the OpenPGP behaviour is used; i.e.
 354     the compression algorith is selected from the preferences.
 355
 356 B<--digest-algo> I<name>
 357     Use I<name> as message digest algorithm. Running the
 358     program with the option B<--verbose> yields a list of
 359     supported algorithms.
 360
 361
 362 B<--throw-keyid>
 363     Do not put the keyid into encrypted packets.  This option
 364     hides the receiver of the message and is a countermeasure
 365     against traffic analysis.  It may slow down the decryption
 366     process because all available secret keys are tried.
 367
 368 B<--passphrase-fd> I<n>
 369     Read the passphrase from file descriptor I<n>. If you use
 370     0 for I<n>, the passphrase will be read from stdin.  This
 371     can only be used if only one passphrase is supplied.
 372     B<Don't use this option if you can avoid it>
 373
 374 B<--no-verbose>
 375     Reset verbose level to 0.
 376
 377 B<--no-greeting>
 378     Suppress the initial copyright message but do not
 379     enter batch mode.
 380
 381 B<--no-armor>
 382     Assume the input data is not in ASCCI armored format.
 383
 384 B<--no-default-keyring>
 385     Do not add the default keyrings to the list of
 386     keyrings.
 387
 388 B<--skip-verify>
 389     Skip the signature verification step.  This may be
 390     used to make the encryption faster if the signature
 391     verification is not needed.
 392
 393 B<--version>
 394     Print version information along with a list
 395     of supported algorithms.
 396
 397 B<--with-colons>
 398     Print key listings delimited by colons.
 399
 400 B<--warranty>
 401     Print warranty information.
 402
 403 B<-h>, B<--help>
 404     Print usage information.
 405
 406
 407 =head1 RETURN VALUE
 408
 409 The Program returns 0 if everything was fine, 1 if at least
 410 a signature was bad and other errorcode for fatal errors.
 411
 412 =head1 EXAMPLES
 413
 414   -se -r Bob [file]          sign and encrypt for user Bob
 415   -sat [file]                make a clear text signature
 416   -sb  [file]                make a detached signature
 417   -k   [userid]              show keys
 418   -kc  [userid]              show fingerprint
 419
 420 =head1 ENVIRONMENT
 421
 422 C<HOME>       Used to locate the default home directory.
 423 C<GNUPGHOME>  If set, direcory used instead of F<~/.gnupg>.
 424
 425 =head1 FILES
 426
 427 F<~/.gnupg/secring.gpg>     The secret keyring
 428
 429 F<~/.gnupg/pubring.gpg>     The public keyring
 430
 431 F<~/.gnupg/trustdb.gpg>     The trust database
 432
 433 F<~/.gnupg/options>         May contain options
 434
 435 F</usr[/local]/lib/gnupg/>  Default location for extensions
 436
 437 =head1 SEE ALSO
 438
 439 gpg(1)  gpgm(1)
 440
 441
 442 =head1 WARNINGS
 443
 444 Use a B<good> password for your user account and a B<good> passphrase
 445 to protect your secret key.  This passphrase is the weakest part of the
 446 whole system.  Programs to do dictionary attacks on your secret keyring
 447 are very easy to write and so you should protect your B<~/.gnupg/>
 448 directory very good.
 449
 450 Keep in mind that, if this program is used over a network (telnet), it
 451 is B<very> easy to spy out your passphrase!
 452
 453 =head1 BUGS
 454
 455 On many systems this program should be installed as setuid(root); this
 456 is necessary to lock some pages of memory. If you get no warning message
 457 about insecure memory your OS kernel supports locking without being root;
 458 setuid is dropped as soon as this memory is allocated.
 459