1 @c Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2@c 2008, 2009, 2010 Free Software Foundation, Inc. 3@c This is part of the GnuPG manual. 4@c For copying conditions, see the file gnupg.texi. 5 6@node Invoking GPG 7@chapter Invoking GPG 8@cindex GPG command options 9@cindex command options 10@cindex options, GPG command 11 12@c Begin algorithm defaults 13 14@set DEFSYMENCALGO AES128 15 16@c End algorithm defaults 17 18 19@macro gpgname 20gpg 21@end macro 22@manpage gpg.1 23@ifset manverb 24.B gpg 25\- OpenPGP encryption and signing tool 26@end ifset 27 28@mansect synopsis 29@ifset manverb 30.B gpg 31.RB [ \-\-homedir 32.IR dir ] 33.RB [ \-\-options 34.IR file ] 35.RI [ options ] 36.I command 37.RI [ args ] 38@end ifset 39 40@mansect description 41@command{@gpgname} is the OpenPGP only version of the GNU Privacy 42Guard (GnuPG). It is a tool to provide digital encryption and signing 43services using the OpenPGP standard. @command{@gpgname} features 44complete key management and all bells and whistles you can expect from 45a decent OpenPGP implementation. 46 47This is the standalone version of @command{gpg}. For desktop use you 48should consider using @command{gpg2} from the GnuPG-2 package 49@footnote{On some platforms gpg2 is installed under the name 50@command{gpg}}. 51 52@manpause 53 54@xref{Option Index}, for an index to @command{@gpgname}'s commands and options. 55@mancont 56 57@menu 58* GPG Commands:: List of all commands. 59* GPG Options:: List of all options. 60* GPG Configuration:: Configuration files. 61* GPG Examples:: Some usage examples. 62 63Developer information: 64* Unattended Usage of GPG:: Using @command{gpg} from other programs. 65@end menu 66 67@c * GPG Protocol:: The protocol the server mode uses. 68 69 70@c ******************************************* 71@c *************** **************** 72@c *************** COMMANDS **************** 73@c *************** **************** 74@c ******************************************* 75@mansect commands 76@node GPG Commands 77@section Commands 78 79Commands are not distinguished from options except for the fact that 80only one command is allowed. 81 82@command{@gpgname} may be run with no commands, in which case it will 83perform a reasonable action depending on the type of file it is given 84as input (an encrypted message is decrypted, a signature is verified, 85a file containing keys is listed). 86 87Please remember that option as well as command parsing stops as soon as 88a non-option is encountered, you can explicitly stop parsing by 89using the special option @option{--}. 90 91 92@menu 93* General GPG Commands:: Commands not specific to the functionality. 94* Operational GPG Commands:: Commands to select the type of operation. 95* OpenPGP Key Management:: How to manage your keys. 96@end menu 97 98 99@c ******************************************* 100@c ********** GENERAL COMMANDS ************* 101@c ******************************************* 102@node General GPG Commands 103@subsection Commands not specific to the function 104 105@table @gnupgtabopt 106@item --version 107@opindex version 108Print the program version and licensing information. Note that you 109cannot abbreviate this command. 110 111@item --help 112@itemx -h 113@opindex help 114Print a usage message summarizing the most useful command line options. 115Note that you cannot abbreviate this command. 116 117@item --warranty 118@opindex warranty 119Print warranty information. 120 121@item --dump-options 122@opindex dump-options 123Print a list of all available options and commands. Note that you cannot 124abbreviate this command. 125@end table 126 127 128@c ******************************************* 129@c ******** OPERATIONAL COMMANDS *********** 130@c ******************************************* 131@node Operational GPG Commands 132@subsection Commands to select the type of operation 133 134 135@table @gnupgtabopt 136 137@item --sign 138@itemx -s 139@opindex sign 140Make a signature. This command may be combined with @option{--encrypt} 141(for a signed and encrypted message), @option{--symmetric} (for a 142signed and symmetrically encrypted message), or @option{--encrypt} and 143@option{--symmetric} together (for a signed message that may be 144decrypted via a secret key or a passphrase). The key to be used for 145signing is chosen by default or can be set with the 146@option{--local-user} and @option{--default-key} options. 147 148@item --clearsign 149@opindex clearsign 150Make a clear text signature. The content in a clear text signature is 151readable without any special software. OpenPGP software is only needed 152to verify the signature. Clear text signatures may modify end-of-line 153whitespace for platform independence and are not intended to be 154reversible. The key to be used for signing is chosen by default or 155can be set with the @option{--local-user} and @option{--default-key} 156options. 157 158 159@item --detach-sign 160@itemx -b 161@opindex detach-sign 162Make a detached signature. 163 164@item --encrypt 165@itemx -e 166@opindex encrypt 167Encrypt data. This option may be combined with @option{--sign} (for a 168signed and encrypted message), @option{--symmetric} (for a message that 169may be decrypted via a secret key or a passphrase), or @option{--sign} 170and @option{--symmetric} together (for a signed message that may be 171decrypted via a secret key or a passphrase). 172 173@item --symmetric 174@itemx -c 175@opindex symmetric 176Encrypt with a symmetric cipher using a passphrase. The default 177symmetric cipher used is @value{DEFSYMENCALGO}, but may be chosen with the 178@option{--cipher-algo} option. This option may be combined with 179@option{--sign} (for a signed and symmetrically encrypted message), 180@option{--encrypt} (for a message that may be decrypted via a secret key 181or a passphrase), or @option{--sign} and @option{--encrypt} together 182(for a signed message that may be decrypted via a secret key or a 183passphrase). 184 185@item --store 186@opindex store 187Store only (make a simple RFC1991 literal data packet). 188 189@item --decrypt 190@itemx -d 191@opindex decrypt 192Decrypt the file given on the command line (or STDIN if no file 193is specified) and write it to STDOUT (or the file specified with 194@option{--output}). If the decrypted file is signed, the signature is also 195verified. This command differs from the default operation, as it never 196writes to the filename which is included in the file and it rejects 197files which don't begin with an encrypted message. 198 199@item --verify 200@opindex verify 201Assume that the first argument is a signed file and verify it without 202generating any output. With no arguments, the signature packet is 203read from STDIN. If only a one argument is given, it is expected to 204be a complete signature. 205 206With more than 1 argument, the first should be a detached signature 207and the remaining files make up the the signed data. To read the signed 208data from STDIN, use @samp{-} as the second filename. For security 209reasons a detached signature cannot read the signed material from 210STDIN without denoting it in the above way. 211 212Note: If the option @option{--batch} is not used, @command{gpg} 213may assume that a single argument is a file with a detached signature 214and it will try to find a matching data file by stripping certain 215suffixes. Using this historical feature to verify a detached 216signature is strongly discouraged; always specify the data file too. 217 218Note: When verifying a cleartext signature, @command{gpg} verifies 219only what makes up the cleartext signed data and not any extra data 220outside of the cleartext signature or header lines following directly 221the dash marker line. The option @code{--output} may be used to write 222out the actual signed data; but there are other pitfalls with this 223format as well. It is suggested to avoid cleartext signatures in 224favor of detached signatures. 225 226 227@item --multifile 228@opindex multifile 229This modifies certain other commands to accept multiple files for 230processing on the command line or read from STDIN with each filename on 231a separate line. This allows for many files to be processed at 232once. @option{--multifile} may currently be used along with 233@option{--verify}, @option{--encrypt}, and @option{--decrypt}. Note that 234@option{--multifile --verify} may not be used with detached signatures. 235 236@item --verify-files 237@opindex verify-files 238Identical to @option{--multifile --verify}. 239 240@item --encrypt-files 241@opindex encrypt-files 242Identical to @option{--multifile --encrypt}. 243 244@item --decrypt-files 245@opindex decrypt-files 246Identical to @option{--multifile --decrypt}. 247 248@item --list-keys 249@itemx -k 250@itemx --list-public-keys 251@opindex list-keys 252List all keys from the public keyrings, or just the keys given on the 253command line. 254 255@option{-k} is slightly different from @option{--list-keys} in that it 256allows only for one argument and takes the second argument as the 257keyring to search. This is for command line compatibility with PGP 2 258and has been removed in @command{gpg2}. 259 260Avoid using the output of this command in scripts or other programs as 261it is likely to change as GnuPG changes. See @option{--with-colons} for a 262machine-parseable key listing command that is appropriate for use in 263scripts and other programs. 264 265@item --list-secret-keys 266@itemx -K 267@opindex list-secret-keys 268List all keys from the secret keyrings, or just the ones given on the 269command line. A @code{#} after the letters @code{sec} means that the 270secret key is not usable (for example, if it was created via 271@option{--export-secret-subkeys}). 272 273@item --list-sigs 274@opindex list-sigs 275Same as @option{--list-keys}, but the signatures are listed too. 276 277For each signature listed, there are several flags in between the "sig" 278tag and keyid. These flags give additional information about each 279signature. From left to right, they are the numbers 1-3 for certificate 280check level (see @option{--ask-cert-level}), "L" for a local or 281non-exportable signature (see @option{--lsign-key}), "R" for a 282nonRevocable signature (see the @option{--edit-key} command "nrsign"), 283"P" for a signature that contains a policy URL (see 284@option{--cert-policy-url}), "N" for a signature that contains a 285notation (see @option{--cert-notation}), "X" for an eXpired signature 286(see @option{--ask-cert-expire}), and the numbers 1-9 or "T" for 10 and 287above to indicate trust signature levels (see the @option{--edit-key} 288command "tsign"). 289 290@item --check-sigs 291@opindex check-sigs 292Same as @option{--list-sigs}, but the signatures are verified. Note 293that for performance reasons the revocation status of a signing key is 294not shown. 295 296The status of the verification is indicated by a flag directly following 297the "sig" tag (and thus before the flags described above for 298@option{--list-sigs}). A "!" indicates that the signature has been 299successfully verified, a "-" denotes a bad signature and a "%" is used 300if an error occurred while checking the signature (e.g. a non supported 301algorithm). 302 303 304@item --fingerprint 305@opindex fingerprint 306List all keys (or the specified ones) along with their 307fingerprints. This is the same output as @option{--list-keys} but with 308the additional output of a line with the fingerprint. May also be 309combined with @option{--list-sigs} or @option{--check-sigs}. If this 310command is given twice, the fingerprints of all secondary keys are 311listed too. 312 313@item --list-packets 314@opindex list-packets 315List only the sequence of packets. This is mainly 316useful for debugging. 317 318 319@item --card-edit 320@opindex card-edit 321Present a menu to work with a smartcard. The subcommand "help" provides 322an overview on available commands. For a detailed description, please 323see the Card HOWTO at 324https://gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO . 325 326@item --card-status 327@opindex card-status 328Show the content of the smart card. 329 330@item --change-pin 331@opindex change-pin 332Present a menu to allow changing the PIN of a smartcard. This 333functionality is also available as the subcommand "passwd" with the 334@option{--card-edit} command. 335 336@item --delete-key @code{name} 337@opindex delete-key 338Remove key from the public keyring. In batch mode either @option{--yes} is 339required or the key must be specified by fingerprint. This is a 340safeguard against accidental deletion of multiple keys. 341 342@item --delete-secret-key @code{name} 343@opindex delete-secret-key 344Remove key from the secret keyring. In batch mode the key 345must be specified by fingerprint. 346 347@item --delete-secret-and-public-key @code{name} 348@opindex delete-secret-and-public-key 349Same as @option{--delete-key}, but if a secret key exists, it will be 350removed first. In batch mode the key must be specified by fingerprint. 351 352@item --export 353@opindex export 354Either export all keys from all keyrings (default keyrings and those 355registered via option @option{--keyring}), or if at least one name is given, 356those of the given name. The exported keys are written to STDOUT or to the 357file given with option @option{--output}. Use together with 358@option{--armor} to mail those keys. 359 360@item --send-keys @code{key IDs} 361@opindex send-keys 362Similar to @option{--export} but sends the keys to a keyserver. 363Fingerprints may be used instead of key IDs. Option @option{--keyserver} 364must be used to give the name of this keyserver. Don't send your 365complete keyring to a keyserver --- select only those keys which are new 366or changed by you. If no key IDs are given, @command{gpg} does nothing. 367 368@item --export-secret-keys 369@itemx --export-secret-subkeys 370@opindex export-secret-keys 371@opindex export-secret-subkeys 372Same as @option{--export}, but exports the secret keys instead. The 373exported keys are written to STDOUT or to the file given with option 374@option{--output}. This command is often used along with the option 375@option{--armor} to allow easy printing of the key for paper backup; 376however the external tool @command{paperkey} does a better job for 377creating backups on paper. Note that exporting a secret key can be a 378security risk if the exported keys are send over an insecure channel. 379 380The second form of the command has the special property to render the 381secret part of the primary key useless; this is a GNU extension to 382OpenPGP and other implementations can not be expected to successfully 383import such a key. Its intended use is to generated a full key with 384an additional signing subkey on a dedicated machine and then using 385this command to export the key without the primary key to the main 386machine. 387 388See the option @option{--simple-sk-checksum} if you want to import an 389exported secret key into ancient OpenPGP implementations. 390 391@item --import 392@itemx --fast-import 393@opindex import 394Import/merge keys. This adds the given keys to the 395keyring. The fast version is currently just a synonym. 396 397There are a few other options which control how this command works. 398Most notable here is the @option{--import-options merge-only} option 399which does not insert new keys but does only the merging of new 400signatures, user-IDs and subkeys. 401 402@item --recv-keys @code{key IDs} 403@opindex recv-keys 404Import the keys with the given key IDs from a keyserver. Option 405@option{--keyserver} must be used to give the name of this keyserver. 406 407@item --refresh-keys 408@opindex refresh-keys 409Request updates from a keyserver for keys that already exist on the 410local keyring. This is useful for updating a key with the latest 411signatures, user IDs, etc. Calling this with no arguments will refresh 412the entire keyring. Option @option{--keyserver} must be used to give the 413name of the keyserver for all keys that do not have preferred keyservers 414set (see @option{--keyserver-options honor-keyserver-url}). 415 416@item --search-keys @code{names} 417@opindex search-keys 418Search the keyserver for the given names. Multiple names given here will 419be joined together to create the search string for the keyserver. 420Option @option{--keyserver} must be used to give the name of this 421keyserver. Keyservers that support different search methods allow using 422the syntax specified in "How to specify a user ID" below. Note that 423different keyserver types support different search methods. Currently 424only LDAP supports them all. 425 426@item --fetch-keys @code{URIs} 427@opindex fetch-keys 428Retrieve keys located at the specified URIs. Note that different 429installations of GnuPG may support different protocols (HTTP, FTP, 430LDAP, etc.) 431 432@item --update-trustdb 433@opindex update-trustdb 434Do trust database maintenance. This command iterates over all keys and 435builds the Web of Trust. This is an interactive command because it may 436have to ask for the "ownertrust" values for keys. The user has to give 437an estimation of how far she trusts the owner of the displayed key to 438correctly certify (sign) other keys. GnuPG only asks for the ownertrust 439value if it has not yet been assigned to a key. Using the 440@option{--edit-key} menu, the assigned value can be changed at any time. 441 442@item --check-trustdb 443@opindex check-trustdb 444Do trust database maintenance without user interaction. From time to 445time the trust database must be updated so that expired keys or 446signatures and the resulting changes in the Web of Trust can be 447tracked. Normally, GnuPG will calculate when this is required and do it 448automatically unless @option{--no-auto-check-trustdb} is set. This 449command can be used to force a trust database check at any time. The 450processing is identical to that of @option{--update-trustdb} but it 451skips keys with a not yet defined "ownertrust". 452 453For use with cron jobs, this command can be used together with 454@option{--batch} in which case the trust database check is done only if 455a check is needed. To force a run even in batch mode add the option 456@option{--yes}. 457 458@anchor{option --export-ownertrust} 459@item --export-ownertrust 460@opindex export-ownertrust 461Send the ownertrust values to STDOUT. This is useful for backup purposes 462as these values are the only ones which can't be re-created from a 463corrupted trustdb. Example: 464@c man:.RS 465@example 466 @gpgname{} --export-ownertrust > otrust.txt 467@end example 468@c man:.RE 469 470 471@item --import-ownertrust 472@opindex import-ownertrust 473Update the trustdb with the ownertrust values stored in @code{files} (or 474STDIN if not given); existing values will be overwritten. In case of a 475severely damaged trustdb and if you have a recent backup of the 476ownertrust values (e.g. in the file @file{otrust.txt}, you may re-create 477the trustdb using these commands: 478@c man:.RS 479@example 480 cd ~/.gnupg 481 rm trustdb.gpg 482 @gpgname{} --import-ownertrust < otrust.txt 483@end example 484@c man:.RE 485 486 487@item --rebuild-keydb-caches 488@opindex rebuild-keydb-caches 489When updating from version 1.0.6 to 1.0.7 this command should be used 490to create signature caches in the keyring. It might be handy in other 491situations too. 492 493@item --print-md @code{algo} 494@itemx --print-mds 495@opindex print-md 496Print message digest of algorithm ALGO for all given files or STDIN. 497With the second form (or a deprecated "*" as algo) digests for all 498available algorithms are printed. 499 500@item --gen-random @code{0|1|2} @code{count} 501@opindex gen-random 502Emit @var{count} random bytes of the given quality level 0, 1 or 2. If 503@var{count} is not given or zero, an endless sequence of random bytes 504will be emitted. If used with @option{--armor} the output will be 505base64 encoded. PLEASE, don't use this command unless you know what 506you are doing; it may remove precious entropy from the system! 507 508@item --gen-prime @code{mode} @code{bits} 509@opindex gen-prime 510Use the source, Luke :-). The output format is still subject to change. 511 512 513@item --enarmor 514@item --dearmor 515@opindex enarmor 516@opindex dearmor 517Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor. 518This is a GnuPG extension to OpenPGP and in general not very useful. 519 520@end table 521 522 523@c ******************************************* 524@c ******* KEY MANGEMENT COMMANDS ********** 525@c ******************************************* 526@node OpenPGP Key Management 527@subsection How to manage your keys 528 529This section explains the main commands for key management 530 531@table @gnupgtabopt 532 533@item --gen-key 534@opindex gen-key 535Generate a new key pair using the current default parameters. This is 536the standard command to create a new key. 537 538There is also a feature which allows you to create keys in batch 539mode. See the the manual section ``Unattended key generation'' on how 540to use this. 541 542@item --gen-revoke @code{name} 543@opindex gen-revoke 544Generate a revocation certificate for the complete key. To revoke 545a subkey or a signature, use the @option{--edit} command. 546 547@item --desig-revoke @code{name} 548@opindex desig-revoke 549Generate a designated revocation certificate for a key. This allows a 550user (with the permission of the keyholder) to revoke someone else's 551key. 552 553 554@item --edit-key 555@opindex edit-key 556Present a menu which enables you to do most of the key management 557related tasks. It expects the specification of a key on the command 558line. 559 560@c ******** Begin Edit-key Options ********** 561@table @asis 562 563 @item uid @code{n} 564 @opindex keyedit:uid 565 Toggle selection of user ID or photographic user ID with index @code{n}. 566 Use @code{*} to select all and @code{0} to deselect all. 567 568 @item key @code{n} 569 @opindex keyedit:key 570 Toggle selection of subkey with index @code{n}. 571 Use @code{*} to select all and @code{0} to deselect all. 572 573 @item sign 574 @opindex keyedit:sign 575 Make a signature on key of user @code{name} If the key is not yet 576 signed by the default user (or the users given with -u), the program 577 displays the information of the key again, together with its 578 fingerprint and asks whether it should be signed. This question is 579 repeated for all users specified with 580 -u. 581 582 @item lsign 583 @opindex keyedit:lsign 584 Same as "sign" but the signature is marked as non-exportable and will 585 therefore never be used by others. This may be used to make keys 586 valid only in the local environment. 587 588 @item nrsign 589 @opindex keyedit:nrsign 590 Same as "sign" but the signature is marked as non-revocable and can 591 therefore never be revoked. 592 593 @item tsign 594 @opindex keyedit:tsign 595 Make a trust signature. This is a signature that combines the notions 596 of certification (like a regular signature), and trust (like the 597 "trust" command). It is generally only useful in distinct communities 598 or groups. 599@end table 600 601@c man:.RS 602Note that "l" (for local / non-exportable), "nr" (for non-revocable, 603and "t" (for trust) may be freely mixed and prefixed to "sign" to 604create a signature of any type desired. 605@c man:.RE 606 607@table @asis 608 609 @item delsig 610 @opindex keyedit:delsig 611 Delete a signature. Note that it is not possible to retract a signature, 612 once it has been send to the public (i.e. to a keyserver). In that case 613 you better use @code{revsig}. 614 615 @item revsig 616 @opindex keyedit:revsig 617 Revoke a signature. For every signature which has been generated by 618 one of the secret keys, GnuPG asks whether a revocation certificate 619 should be generated. 620 621 @item check 622 @opindex keyedit:check 623 Check the signatures on all selected user IDs. 624 625 @item adduid 626 @opindex keyedit:adduid 627 Create an additional user ID. 628 629 @item addphoto 630 @opindex keyedit:addphoto 631 Create a photographic user ID. This will prompt for a JPEG file that 632 will be embedded into the user ID. Note that a very large JPEG will make 633 for a very large key. Also note that some programs will display your 634 JPEG unchanged (GnuPG), and some programs will scale it to fit in a 635 dialog box (PGP). 636 637 @item showphoto 638 @opindex keyedit:showphoto 639 Display the selected photographic user ID. 640 641 @item deluid 642 @opindex keyedit:deluid 643 Delete a user ID or photographic user ID. Note that it is not 644 possible to retract a user id, once it has been send to the public 645 (i.e. to a keyserver). In that case you better use @code{revuid}. 646 647 @item revuid 648 @opindex keyedit:revuid 649 Revoke a user ID or photographic user ID. 650 651 @item primary 652 @opindex keyedit:primary 653 Flag the current user id as the primary one, removes the primary user 654 id flag from all other user ids and sets the timestamp of all affected 655 self-signatures one second ahead. Note that setting a photo user ID 656 as primary makes it primary over other photo user IDs, and setting a 657 regular user ID as primary makes it primary over other regular user 658 IDs. 659 660 @item keyserver 661 @opindex keyedit:keyserver 662 Set a preferred keyserver for the specified user ID(s). This allows 663 other users to know where you prefer they get your key from. See 664 @option{--keyserver-options honor-keyserver-url} for more on how this 665 works. Setting a value of "none" removes an existing preferred 666 keyserver. 667 668 @item notation 669 @opindex keyedit:notation 670 Set a name=value notation for the specified user ID(s). See 671 @option{--cert-notation} for more on how this works. Setting a value of 672 "none" removes all notations, setting a notation prefixed with a minus 673 sign (-) removes that notation, and setting a notation name (without the 674 =value) prefixed with a minus sign removes all notations with that name. 675 676 @item pref 677 @opindex keyedit:pref 678 List preferences from the selected user ID. This shows the actual 679 preferences, without including any implied preferences. 680 681 @item showpref 682 @opindex keyedit:showpref 683 More verbose preferences listing for the selected user ID. This shows 684 the preferences in effect by including the implied preferences of 3DES 685 (cipher), SHA-1 (digest), and Uncompressed (compression) if they are 686 not already included in the preference list. In addition, the 687 preferred keyserver and signature notations (if any) are shown. 688 689 @item setpref @code{string} 690 @opindex keyedit:setpref 691 Set the list of user ID preferences to @code{string} for all (or just 692 the selected) user IDs. Calling setpref with no arguments sets the 693 preference list to the default (either built-in or set via 694 @option{--default-preference-list}), and calling setpref with "none" 695 as the argument sets an empty preference list. Use @command{@gpgname 696 --version} to get a list of available algorithms. Note that while you 697 can change the preferences on an attribute user ID (aka "photo ID"), 698 GnuPG does not select keys via attribute user IDs so these preferences 699 will not be used by GnuPG. 700 701 When setting preferences, you should list the algorithms in the order 702 which you'd like to see them used by someone else when encrypting a 703 message to your key. If you don't include 3DES, it will be 704 automatically added at the end. Note that there are many factors that 705 go into choosing an algorithm (for example, your key may not be the 706 only recipient), and so the remote OpenPGP application being used to 707 send to you may or may not follow your exact chosen order for a given 708 message. It will, however, only choose an algorithm that is present 709 on the preference list of every recipient key. See also the 710 INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below. 711 712 @item addkey 713 @opindex keyedit:addkey 714 Add a subkey to this key. 715 716 @item addcardkey 717 @opindex keyedit:addcardkey 718 Generate a subkey on a card and add it to this key. 719 720 @item keytocard 721 @opindex keyedit:keytocard 722 Transfer the selected secret subkey (or the primary key if no subkey 723 has been selected) to a smartcard. The secret key in the keyring will 724 be replaced by a stub if the key could be stored successfully on the 725 card and you use the save command later. Only certain key types may be 726 transferred to the card. A sub menu allows you to select on what card 727 to store the key. Note that it is not possible to get that key back 728 from the card - if the card gets broken your secret key will be lost 729 unless you have a backup somewhere. 730 731 @item bkuptocard @code{file} 732 @opindex keyedit:bkuptocard 733 Restore the given file to a card. This command may be used to restore a 734 backup key (as generated during card initialization) to a new card. In 735 almost all cases this will be the encryption key. You should use this 736 command only with the corresponding public key and make sure that the 737 file given as argument is indeed the backup to restore. You should then 738 select 2 to restore as encryption key. You will first be asked to enter 739 the passphrase of the backup key and then for the Admin PIN of the card. 740 741 @item delkey 742 @opindex keyedit:delkey 743 Remove a subkey (secondart key). Note that it is not possible to retract 744 a subkey, once it has been send to the public (i.e. to a keyserver). In 745 that case you better use @code{revkey}. 746 747 @item revkey 748 @opindex keyedit:revkey 749 Revoke a subkey. 750 751 @item expire 752 @opindex keyedit:expire 753 Change the key or subkey expiration time. If a subkey is selected, the 754 expiration time of this subkey will be changed. With no selection, the 755 key expiration of the primary key is changed. 756 757 @item trust 758 @opindex keyedit:trust 759 Change the owner trust value for the key. This updates the trust-db 760 immediately and no save is required. 761 762 @item disable 763 @itemx enable 764 @opindex keyedit:disable 765 @opindex keyedit:enable 766 Disable or enable an entire key. A disabled key can not normally be 767 used for encryption. 768 769 @item addrevoker 770 @opindex keyedit:addrevoker 771 Add a designated revoker to the key. This takes one optional argument: 772 "sensitive". If a designated revoker is marked as sensitive, it will 773 not be exported by default (see export-options). 774 775 @item passwd 776 @opindex keyedit:passwd 777 Change the passphrase of the secret key. 778 779 @item toggle 780 @opindex keyedit:toggle 781 Toggle between public and secret key listing. 782 783 @item clean 784 @opindex keyedit:clean 785 Compact (by removing all signatures except the selfsig) any user ID 786 that is no longer usable (e.g. revoked, or expired). Then, remove any 787 signatures that are not usable by the trust calculations. 788 Specifically, this removes any signature that does not validate, any 789 signature that is superseded by a later signature, revoked signatures, 790 and signatures issued by keys that are not present on the keyring. 791 792 @item minimize 793 @opindex keyedit:minimize 794 Make the key as small as possible. This removes all signatures from 795 each user ID except for the most recent self-signature. 796 797 @item cross-certify 798 @opindex keyedit:cross-certify 799 Add cross-certification signatures to signing subkeys that may not 800 currently have them. Cross-certification signatures protect against a 801 subtle attack against signing subkeys. See 802 @option{--require-cross-certification}. All new keys generated have 803 this signature by default, so this option is only useful to bring 804 older keys up to date. 805 806 @item save 807 @opindex keyedit:save 808 Save all changes to the key rings and quit. 809 810 @item quit 811 @opindex keyedit:quit 812 Quit the program without updating the 813 key rings. 814@end table 815 816@c man:.RS 817The listing shows you the key with its secondary keys and all user 818ids. The primary user id is indicated by a dot, and selected keys or 819user ids are indicated by an asterisk. The trust 820value is displayed with the primary key: the first is the assigned owner 821trust and the second is the calculated trust value. Letters are used for 822the values: 823@c man:.RE 824 825@table @asis 826 827 @item - 828 No ownertrust assigned / not yet calculated. 829 830 @item e 831 Trust 832 calculation has failed; probably due to an expired key. 833 834 @item q 835 Not enough information for calculation. 836 837 @item n 838 Never trust this key. 839 840 @item m 841 Marginally trusted. 842 843 @item f 844 Fully trusted. 845 846 @item u 847 Ultimately trusted. 848 849@end table 850@c ******** End Edit-key Options ********** 851 852@item --sign-key @code{name} 853@opindex sign-key 854Signs a public key with your secret key. This is a shortcut version of 855the subcommand "sign" from @option{--edit}. 856 857@item --lsign-key @code{name} 858@opindex lsign-key 859Signs a public key with your secret key but marks it as 860non-exportable. This is a shortcut version of the subcommand "lsign" 861from @option{--edit-key}. 862 863@end table 864 865 866@c ******************************************* 867@c *************** **************** 868@c *************** OPTIONS **************** 869@c *************** **************** 870@c ******************************************* 871@mansect options 872@node GPG Options 873@section Option Summary 874 875@command{@gpgname} features a bunch of options to control the exact 876behaviour and to change the default configuration. 877 878@menu 879* GPG Configuration Options:: How to change the configuration. 880* GPG Key related Options:: Key related options. 881* GPG Input and Output:: Input and Output. 882* OpenPGP Options:: OpenPGP protocol specific options. 883* Compliance Options:: Compliance options. 884* GPG Esoteric Options:: Doing things one usually don't want to do. 885* Deprecated Options:: Deprecated options. 886@end menu 887 888Long options can be put in an options file (default 889"~/.gnupg/gpg.conf"). Short option names will not work - for example, 890"armor" is a valid option for the options file, while "a" is not. Do not 891write the 2 dashes, but simply the name of the option and any required 892arguments. Lines with a hash ('#') as the first non-white-space 893character are ignored. Commands may be put in this file too, but that is 894not generally useful as the command will execute automatically with 895every execution of gpg. 896 897Please remember that option parsing stops as soon as a non-option is 898encountered, you can explicitly stop parsing by using the special option 899@option{--}. 900 901@c ******************************************* 902@c ******** CONFIGURATION OPTIONS ********** 903@c ******************************************* 904@node GPG Configuration Options 905@subsection How to change the configuration 906 907These options are used to change the configuration and are usually found 908in the option file. 909 910@table @gnupgtabopt 911 912@item --default-key @var{name} 913@opindex default-key 914Use @var{name} as the default key to sign with. If this option is not 915used, the default key is the first key found in the secret keyring. 916Note that @option{-u} or @option{--local-user} overrides this option. 917 918@item --default-recipient @var{name} 919@opindex default-recipient 920Use @var{name} as default recipient if option @option{--recipient} is 921not used and don't ask if this is a valid one. @var{name} must be 922non-empty. 923 924@item --default-recipient-self 925@opindex default-recipient-self 926Use the default key as default recipient if option @option{--recipient} is not 927used and don't ask if this is a valid one. The default key is the first 928one from the secret keyring or the one set with @option{--default-key}. 929 930@item --no-default-recipient 931@opindex no-default-recipient 932Reset @option{--default-recipient} and @option{--default-recipient-self}. 933 934@item -v, --verbose 935@opindex verbose 936Give more information during processing. If used 937twice, the input data is listed in detail. 938 939@item --no-verbose 940@opindex no-verbose 941Reset verbose level to 0. 942 943@item -q, --quiet 944@opindex quiet 945Try to be as quiet as possible. 946 947@item --batch 948@itemx --no-batch 949@opindex batch 950@opindex no-batch 951Use batch mode. Never ask, do not allow interactive commands. 952@option{--no-batch} disables this option. This option is commonly 953used for unattended operations. 954 955WARNING: Unattended operation bears a higher risk of being exposed to 956security attacks. In particular any unattended use of GnuPG which 957involves the use of secret keys should take care not to provide an 958decryption oracle. There are several standard pre-cautions against 959being used as an oracle. For example never return detailed error 960messages or any diagnostics printed by your software to the remote 961site. Consult with an expert in case of doubt. 962 963Note that even with a filename given on the command line, gpg might 964still need to read from STDIN (in particular if gpg figures that the 965input is a detached signature and no data file has been specified). 966Thus if you do not want to feed data via STDIN, you should connect 967STDIN to @file{/dev/null}. 968 969 970@item --no-tty 971@opindex no-tty 972Make sure that the TTY (terminal) is never used for any output. 973This option is needed in some cases because GnuPG sometimes prints 974warnings to the TTY even if @option{--batch} is used. 975 976@item --yes 977@opindex yes 978Assume "yes" on most questions. 979 980@item --no 981@opindex no 982Assume "no" on most questions. 983 984 985@item --list-options @code{parameters} 986@opindex list-options 987This is a space or comma delimited string that gives options used when 988listing keys and signatures (that is, @option{--list-keys}, 989@option{--list-sigs}, @option{--list-public-keys}, 990@option{--list-secret-keys}, and the @option{--edit-key} functions). 991Options can be prepended with a @option{no-} (after the two dashes) to 992give the opposite meaning. The options are: 993 994@table @asis 995 996 @item show-photos 997 @opindex list-options:show-photos 998 Causes @option{--list-keys}, @option{--list-sigs}, 999 @option{--list-public-keys}, and @option{--list-secret-keys} to 1000 display any photo IDs attached to the key. Defaults to no. See also 1001 @option{--photo-viewer}. Does not work with @option{--with-colons}: 1002 see @option{--attribute-fd} for the appropriate way to get photo data 1003 for scripts and other frontends. 1004 1005 @item show-usage 1006 @opindex list-options:show-usage 1007 Show usage information for keys and subkeys in the standard key 1008 listing. This is a list of letters indicating the allowed usage for a 1009 key (@code{E}=encryption, @code{S}=signing, @code{C}=certification, 1010 @code{A}=authentication). Defaults to no. 1011 1012 @item show-policy-urls 1013 @opindex list-options:show-policy-urls 1014 Show policy URLs in the @option{--list-sigs} or @option{--check-sigs} 1015 listings. Defaults to no. 1016 1017 @item show-notations 1018 @itemx show-std-notations 1019 @itemx show-user-notations 1020 @opindex list-options:show-notations 1021 @opindex list-options:show-std-notations 1022 @opindex list-options:show-user-notations 1023 Show all, IETF standard, or user-defined signature notations in the 1024 @option{--list-sigs} or @option{--check-sigs} listings. Defaults to no. 1025 1026 @item show-keyserver-urls 1027 @opindex list-options:show-keyserver-urls 1028 Show any preferred keyserver URL in the @option{--list-sigs} or 1029 @option{--check-sigs} listings. Defaults to no. 1030 1031 @item show-uid-validity 1032 @opindex list-options:show-uid-validity 1033 Display the calculated validity of user IDs during key listings. 1034 Defaults to no. 1035 1036 @item show-unusable-uids 1037 @opindex list-options:show-unusable-uids 1038 Show revoked and expired user IDs in key listings. Defaults to no. 1039 1040 @item show-unusable-subkeys 1041 @opindex list-options:show-unusable-subkeys 1042 Show revoked and expired subkeys in key listings. Defaults to no. 1043 1044 @item show-keyring 1045 @opindex list-options:show-keyring 1046 Display the keyring name at the head of key listings to show which 1047 keyring a given key resides on. Defaults to no. 1048 1049 @item show-sig-expire 1050 @opindex list-options:show-sig-expire 1051 Show signature expiration dates (if any) during @option{--list-sigs} or 1052 @option{--check-sigs} listings. Defaults to no. 1053 1054 @item show-sig-subpackets 1055 @opindex list-options:show-sig-subpackets 1056 Include signature subpackets in the key listing. This option can take an 1057 optional argument list of the subpackets to list. If no argument is 1058 passed, list all subpackets. Defaults to no. This option is only 1059 meaningful when using @option{--with-colons} along with 1060 @option{--list-sigs} or @option{--check-sigs}. 1061 1062@end table 1063 1064@item --verify-options @code{parameters} 1065@opindex verify-options 1066This is a space or comma delimited string that gives options used when 1067verifying signatures. Options can be prepended with a `no-' to give 1068the opposite meaning. The options are: 1069 1070@table @asis 1071 1072 @item show-photos 1073 @opindex verify-options:show-photos 1074 Display any photo IDs present on the key that issued the signature. 1075 Defaults to no. See also @option{--photo-viewer}. 1076 1077 @item show-policy-urls 1078 @opindex verify-options:show-policy-urls 1079 Show policy URLs in the signature being verified. Defaults to no. 1080 1081 @item show-notations 1082 @itemx show-std-notations 1083 @itemx show-user-notations 1084 @opindex verify-options:show-notations 1085 @opindex verify-options:show-std-notations 1086 @opindex verify-options:show-user-notations 1087 Show all, IETF standard, or user-defined signature notations in the 1088 signature being verified. Defaults to IETF standard. 1089 1090 @item show-keyserver-urls 1091 @opindex verify-options:show-keyserver-urls 1092 Show any preferred keyserver URL in the signature being verified. 1093 Defaults to no. 1094 1095 @item show-uid-validity 1096 @opindex verify-options:show-uid-validity 1097 Display the calculated validity of the user IDs on the key that issued 1098 the signature. Defaults to no. 1099 1100 @item show-unusable-uids 1101 @opindex verify-options:show-unusable-uids 1102 Show revoked and expired user IDs during signature verification. 1103 Defaults to no. 1104 1105 @item show-primary-uid-only 1106 @opindex verify-options:show-primary-uid-only 1107 Show only the primary user ID during signature verification. That is 1108 all the AKA lines as well as photo Ids are not shown with the signature 1109 verification status. 1110 1111 @item pka-lookups 1112 @opindex verify-options:pka-lookups 1113 Enable PKA lookups to verify sender addresses. Note that PKA is based 1114 on DNS, and so enabling this option may disclose information on when 1115 and what signatures are verified or to whom data is encrypted. This 1116 is similar to the "web bug" described for the auto-key-retrieve 1117 feature. 1118 1119 @item pka-trust-increase 1120 @opindex verify-options:pka-trust-increase 1121 Raise the trust in a signature to full if the signature passes PKA 1122 validation. This option is only meaningful if pka-lookups is set. 1123@end table 1124 1125@item --enable-large-rsa 1126@itemx --disable-large-rsa 1127@opindex enable-large-rsa 1128@opindex disable-large-rsa 1129With --gen-key and --batch, enable the creation of larger RSA secret 1130keys than is generally recommended (up to 8192 bits). These large 1131keys are more expensive to use, and their signatures and 1132certifications are also larger. 1133 1134@item --enable-dsa2 1135@itemx --disable-dsa2 1136@opindex enable-dsa2 1137@opindex disable-dsa2 1138Enable hash truncation for all DSA keys even for old DSA Keys up to 11391024 bit. This is also the default with @option{--openpgp}. Note 1140that older versions of GnuPG also required this flag to allow the 1141generation of DSA larger than 1024 bit. 1142 1143@item --photo-viewer @code{string} 1144@opindex photo-viewer 1145This is the command line that should be run to view a photo ID. "%i" 1146will be expanded to a filename containing the photo. "%I" does the 1147same, except the file will not be deleted once the viewer exits. 1148Other flags are "%k" for the key ID, "%K" for the long key ID, "%f" 1149for the key fingerprint, "%t" for the extension of the image type 1150(e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"), 1151"%v" for the single-character calculated validity of the image being 1152viewed (e.g. "f"), "%V" for the calculated validity as a string (e.g. 1153"full"), "%U" for a base32 encoded hash of the user ID, 1154and "%%" for an actual percent sign. If neither %i or %I are present, 1155then the photo will be supplied to the viewer on standard input. 1156 1157The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k' 1158STDIN". Note that if your image viewer program is not secure, then 1159executing it from GnuPG does not make it secure. 1160 1161@item --exec-path @code{string} 1162@opindex exec-path 1163Sets a list of directories to search for photo viewers and keyserver 1164helpers. If not provided, keyserver helpers use the compiled-in 1165default directory, and photo viewers use the $PATH environment 1166variable. 1167Note, that on W32 system this value is ignored when searching for 1168keyserver helpers. 1169 1170@item --keyring @code{file} 1171@opindex keyring 1172Add @code{file} to the current list of keyrings. If @code{file} begins 1173with a tilde and a slash, these are replaced by the $HOME directory. If 1174the filename does not contain a slash, it is assumed to be in the GnuPG 1175home directory ("~/.gnupg" if @option{--homedir} or $GNUPGHOME is not 1176used). 1177 1178Note that this adds a keyring to the current list. If the intent is to 1179use the specified keyring alone, use @option{--keyring} along with 1180@option{--no-default-keyring}. 1181 1182@item --secret-keyring @code{file} 1183@opindex secret-keyring 1184Same as @option{--keyring} but for the secret keyrings. 1185 1186@item --primary-keyring @code{file} 1187@opindex primary-keyring 1188Designate @code{file} as the primary public keyring. This means that 1189newly imported keys (via @option{--import} or keyserver 1190@option{--recv-from}) will go to this keyring. 1191 1192@item --trustdb-name @code{file} 1193@opindex trustdb-name 1194Use @code{file} instead of the default trustdb. If @code{file} begins 1195with a tilde and a slash, these are replaced by the $HOME directory. If 1196the filename does not contain a slash, it is assumed to be in the GnuPG 1197home directory (@file{~/.gnupg} if @option{--homedir} or $GNUPGHOME is 1198not used). 1199 1200@anchor{option --homedir} 1201@include opt-homedir.texi 1202 1203 1204@item --pcsc-driver @code{file} 1205@opindex pcsc-driver 1206Use @code{file} to access the smartcard reader. The current default is 1207`libpcsclite.so.1' for GLIBC based systems, 1208`/System/Library/Frameworks/PCSC.framework/PCSC' for MAC OS X, 1209`winscard.dll' for Windows and `libpcsclite.so' for other systems. 1210 1211@item --disable-ccid 1212@opindex disable-ccid 1213Disable the integrated support for CCID compliant readers. This 1214allows falling back to one of the other drivers even if the internal 1215CCID driver can handle the reader. Note, that CCID support is only 1216available if libusb was available at build time. 1217 1218@item --reader-port @code{number_or_string} 1219@opindex reader-port 1220This option may be used to specify the port of the card terminal. A 1221value of 0 refers to the first serial device; add 32768 to access USB 1222devices. The default is 32768 (first USB device). PC/SC or CCID 1223readers might need a string here; run the program in verbose mode to get 1224a list of available readers. The default is then the first reader 1225found. 1226 1227@item --display-charset @code{name} 1228@opindex display-charset 1229Set the name of the native character set. This is used to convert 1230some informational strings like user IDs to the proper UTF-8 encoding. 1231Note that this has nothing to do with the character set of data to be 1232encrypted or signed; GnuPG does not recode user-supplied data. If 1233this option is not used, the default character set is determined from 1234the current locale. A verbosity level of 3 shows the chosen set. 1235Valid values for @code{name} are: 1236 1237@table @asis 1238 1239 @item iso-8859-1 1240 @opindex display-charset:iso-8859-1 1241 This is the Latin 1 set. 1242 1243 @item iso-8859-2 1244 @opindex display-charset:iso-8859-2 1245 The Latin 2 set. 1246 1247 @item iso-8859-15 1248 @opindex display-charset:iso-8859-15 1249 This is currently an alias for 1250 the Latin 1 set. 1251 1252 @item koi8-r 1253 @opindex display-charset:koi8-r 1254 The usual Russian set (rfc1489). 1255 1256 @item utf-8 1257 @opindex display-charset:utf-8 1258 Bypass all translations and assume 1259 that the OS uses native UTF-8 encoding. 1260@end table 1261 1262@item --utf8-strings 1263@itemx --no-utf8-strings 1264@opindex utf8-strings 1265Assume that command line arguments are given as UTF8 strings. The 1266default (@option{--no-utf8-strings}) is to assume that arguments are 1267encoded in the character set as specified by 1268@option{--display-charset}. These options affect all following 1269arguments. Both options may be used multiple times. 1270 1271@anchor{gpg-option --options} 1272@item --options @code{file} 1273@opindex options 1274Read options from @code{file} and do not try to read them from the 1275default options file in the homedir (see @option{--homedir}). This 1276option is ignored if used in an options file. 1277 1278@item --no-options 1279@opindex no-options 1280Shortcut for @option{--options /dev/null}. This option is detected 1281before an attempt to open an option file. Using this option will also 1282prevent the creation of a @file{~/.gnupg} homedir. 1283 1284@item -z @code{n} 1285@itemx --compress-level @code{n} 1286@itemx --bzip2-compress-level @code{n} 1287@opindex compress-level 1288@opindex bzip2-compress-level 1289Set compression level to @code{n} for the ZIP and ZLIB compression 1290algorithms. The default is to use the default compression level of zlib 1291(normally 6). @option{--bzip2-compress-level} sets the compression level 1292for the BZIP2 compression algorithm (defaulting to 6 as well). This is a 1293different option from @option{--compress-level} since BZIP2 uses a 1294significant amount of memory for each additional compression level. 1295@option{-z} sets both. A value of 0 for @code{n} disables compression. 1296 1297@item --bzip2-decompress-lowmem 1298@opindex bzip2-decompress-lowmem 1299Use a different decompression method for BZIP2 compressed files. This 1300alternate method uses a bit more than half the memory, but also runs 1301at half the speed. This is useful under extreme low memory 1302circumstances when the file was originally compressed at a high 1303@option{--bzip2-compress-level}. 1304 1305 1306@item --mangle-dos-filenames 1307@itemx --no-mangle-dos-filenames 1308@opindex mangle-dos-filenames 1309@opindex no-mangle-dos-filenames 1310Older version of Windows cannot handle filenames with more than one 1311dot. @option{--mangle-dos-filenames} causes GnuPG to replace (rather 1312than add to) the extension of an output filename to avoid this 1313problem. This option is off by default and has no effect on non-Windows 1314platforms. 1315 1316@item --ask-cert-level 1317@itemx --no-ask-cert-level 1318@opindex ask-cert-level 1319When making a key signature, prompt for a certification level. If this 1320option is not specified, the certification level used is set via 1321@option{--default-cert-level}. See @option{--default-cert-level} for 1322information on the specific levels and how they are 1323used. @option{--no-ask-cert-level} disables this option. This option 1324defaults to no. 1325 1326@item --default-cert-level @code{n} 1327@opindex default-cert-level 1328The default to use for the check level when signing a key. 1329 13300 means you make no particular claim as to how carefully you verified 1331the key. 1332 13331 means you believe the key is owned by the person who claims to own 1334it but you could not, or did not verify the key at all. This is 1335useful for a "persona" verification, where you sign the key of a 1336pseudonymous user. 1337 13382 means you did casual verification of the key. For example, this 1339could mean that you verified the key fingerprint and checked the 1340user ID on the key against a photo ID. 1341 13423 means you did extensive verification of the key. For example, this 1343could mean that you verified the key fingerprint with the owner of the 1344key in person, and that you checked, by means of a hard to forge 1345document with a photo ID (such as a passport) that the name of the key 1346owner matches the name in the user ID on the key, and finally that you 1347verified (by exchange of email) that the email address on the key 1348belongs to the key owner. 1349 1350Note that the examples given above for levels 2 and 3 are just that: 1351examples. In the end, it is up to you to decide just what "casual" 1352and "extensive" mean to you. 1353 1354This option defaults to 0 (no particular claim). 1355 1356@item --min-cert-level 1357@opindex min-cert-level 1358When building the trust database, treat any signatures with a 1359certification level below this as invalid. Defaults to 2, which 1360disregards level 1 signatures. Note that level 0 "no particular 1361claim" signatures are always accepted. 1362 1363@item --trusted-key @code{long key ID} 1364@opindex trusted-key 1365Assume that the specified key (which must be given 1366as a full 8 byte key ID) is as trustworthy as one of 1367your own secret keys. This option is useful if you 1368don't want to keep your secret keys (or one of them) 1369online but still want to be able to check the validity of a given 1370recipient's or signator's key. 1371 1372@item --trust-model @code{pgp|classic|direct|always|auto} 1373@opindex trust-model 1374Set what trust model GnuPG should follow. The models are: 1375 1376@table @asis 1377 1378 @item pgp 1379 @opindex trust-mode:pgp 1380 This is the Web of Trust combined with trust signatures as used in PGP 1381 5.x and later. This is the default trust model when creating a new 1382 trust database. 1383 1384 @item classic 1385 @opindex trust-mode:classic 1386 This is the standard Web of Trust as introduced by PGP 2. 1387 1388 @item direct 1389 @opindex trust-mode:direct 1390 Key validity is set directly by the user and not calculated via the 1391 Web of Trust. 1392 1393 @item always 1394 @opindex trust-mode:always 1395 Skip key validation and assume that used keys are always fully 1396 valid. You generally won't use this unless you are using some 1397 external validation scheme. This option also suppresses the 1398 "[uncertain]" tag printed with signature checks when there is no 1399 evidence that the user ID is bound to the key. Note that this 1400 trust model still does not allow the use of expired, revoked, or 1401 disabled keys. 1402 1403 @item auto 1404 @opindex trust-mode:auto 1405 Select the trust model depending on whatever the internal trust 1406 database says. This is the default model if such a database already 1407 exists. 1408@end table 1409 1410@item --auto-key-locate @code{parameters} 1411@itemx --no-auto-key-locate 1412@opindex auto-key-locate 1413GnuPG can automatically locate and retrieve keys as needed using this 1414option. This happens when encrypting to an email address (in the 1415"user@@example.com" form), and there are no user@@example.com keys on 1416the local keyring. This option takes any number of the following 1417mechanisms, in the order they are to be tried: 1418 1419@table @asis 1420 1421 @item cert 1422 Locate a key using DNS CERT, as specified in rfc4398. 1423 1424 @item pka 1425 Locate a key using DNS PKA. 1426 1427 @item ldap 1428 Using DNS Service Discovery, check the domain in question for any LDAP 1429 keyservers to use. If this fails, attempt to locate the key using the 1430 PGP Universal method of checking @samp{ldap://keys.(thedomain)}. 1431 1432 @item keyserver 1433 Locate a key using whatever keyserver is defined using the 1434 @option{--keyserver} option. 1435 1436 @item keyserver-URL 1437 In addition, a keyserver URL as used in the @option{--keyserver} option 1438 may be used here to query that particular keyserver. 1439 1440 @item local 1441 Locate the key using the local keyrings. This mechanism allows the user to 1442 select the order a local key lookup is done. Thus using 1443 @samp{--auto-key-locate local} is identical to 1444 @option{--no-auto-key-locate}. 1445 1446 @item nodefault 1447 This flag disables the standard local key lookup, done before any of the 1448 mechanisms defined by the @option{--auto-key-locate} are tried. The 1449 position of this mechanism in the list does not matter. It is not 1450 required if @code{local} is also used. 1451 1452 @item clear 1453 Clear all defined mechanisms. This is useful to override 1454 mechanisms given in a config file. 1455 1456@end table 1457 1458@item --keyid-format @code{short|0xshort|long|0xlong} 1459@opindex keyid-format 1460Select how to display key IDs. "short" is the traditional 8-character 1461key ID. "long" is the more accurate (but less convenient) 146216-character key ID. Add an "0x" to either to include an "0x" at the 1463beginning of the key ID, as in 0x99242560. Note that this option is 1464ignored if the option --with-colons is used. 1465 1466@item --keyserver @code{name} 1467@opindex keyserver 1468Use @code{name} as your keyserver. This is the server that 1469@option{--recv-keys}, @option{--send-keys}, and @option{--search-keys} 1470will communicate with to receive keys from, send keys to, and search for 1471keys on. The format of the @code{name} is a URI: 1472`scheme:[//]keyservername[:port]' The scheme is the type of keyserver: 1473"hkp" for the HTTP (or compatible) keyservers, "ldap" for the LDAP 1474keyservers, or "mailto" for the Graff email keyserver. Note that your 1475particular installation of GnuPG may have other keyserver types 1476available as well. Keyserver schemes are case-insensitive. After the 1477keyserver name, optional keyserver configuration options may be 1478provided. These are the same as the global @option{--keyserver-options} 1479from below, but apply only to this particular keyserver. 1480 1481Most keyservers synchronize with each other, so there is generally no 1482need to send keys to more than one server. The keyserver 1483@code{hkp://keys.gnupg.net} uses round robin DNS to give a different 1484keyserver each time you use it. 1485 1486@item --keyserver-options @code{name=value1 } 1487@opindex keyserver-options 1488This is a space or comma delimited string that gives options for the 1489keyserver. Options can be prefixed with a `no-' to give the opposite 1490meaning. Valid import-options or export-options may be used here as 1491well to apply to importing (@option{--recv-key}) or exporting 1492(@option{--send-key}) a key from a keyserver. While not all options 1493are available for all keyserver types, some common options are: 1494 1495@table @asis 1496 1497 @item include-revoked 1498 When searching for a key with @option{--search-keys}, include keys that 1499 are marked on the keyserver as revoked. Note that not all keyservers 1500 differentiate between revoked and unrevoked keys, and for such 1501 keyservers this option is meaningless. Note also that most keyservers do 1502 not have cryptographic verification of key revocations, and so turning 1503 this option off may result in skipping keys that are incorrectly marked 1504 as revoked. 1505 1506 @item include-disabled 1507 When searching for a key with @option{--search-keys}, include keys that 1508 are marked on the keyserver as disabled. Note that this option is not 1509 used with HKP keyservers. 1510 1511 @item auto-key-retrieve 1512 This option enables the automatic retrieving of keys from a keyserver 1513 when verifying signatures made by keys that are not on the local 1514 keyring. 1515 1516 Note that this option makes a "web bug" like behavior possible. 1517 Keyserver operators can see which keys you request, so by sending you 1518 a message signed by a brand new key (which you naturally will not have 1519 on your local keyring), the operator can tell both your IP address and 1520 the time when you verified the signature. 1521 1522 @item honor-keyserver-url 1523 When using @option{--refresh-keys}, if the key in question has a preferred 1524 keyserver URL, then use that preferred keyserver to refresh the key 1525 from. In addition, if auto-key-retrieve is set, and the signature 1526 being verified has a preferred keyserver URL, then use that preferred 1527 keyserver to fetch the key from. Defaults to yes. 1528 1529 @item honor-pka-record 1530 If auto-key-retrieve is set, and the signature being verified has a 1531 PKA record, then use the PKA information to fetch the key. Defaults 1532 to yes. 1533 1534 @item include-subkeys 1535 When receiving a key, include subkeys as potential targets. Note that 1536 this option is not used with HKP keyservers, as they do not support 1537 retrieving keys by subkey id. 1538 1539 @item use-temp-files 1540 On most Unix-like platforms, GnuPG communicates with the keyserver 1541 helper program via pipes, which is the most efficient method. This 1542 option forces GnuPG to use temporary files to communicate. On some 1543 platforms (such as Win32 and RISC OS), this option is always enabled. 1544 1545 @item keep-temp-files 1546 If using `use-temp-files', do not delete the temp files after using 1547 them. This option is useful to learn the keyserver communication 1548 protocol by reading the temporary files. 1549 1550 @item verbose 1551 Tell the keyserver helper program to be more verbose. This option can 1552 be repeated multiple times to increase the verbosity level. 1553 1554 @item timeout 1555 Tell the keyserver helper program how long (in seconds) to try and 1556 perform a keyserver action before giving up. Note that performing 1557 multiple actions at the same time uses this timeout value per action. 1558 For example, when retrieving multiple keys via @option{--recv-keys}, the 1559 timeout applies separately to each key retrieval, and not to the 1560 @option{--recv-keys} command as a whole. Defaults to 30 seconds. 1561 1562 @item http-proxy=@code{value} 1563 Set the proxy to use for HTTP and HKP keyservers. This overrides the 1564 "http_proxy" environment variable, if any. 1565 1566 1567 @item max-cert-size 1568 When retrieving a key via DNS CERT, only accept keys up to this size. 1569 Defaults to 16384 bytes. 1570 1571 @item debug 1572 Turn on debug output in the keyserver helper program. Note that the 1573 details of debug output depends on which keyserver helper program is 1574 being used, and in turn, on any libraries that the keyserver helper 1575 program uses internally (libcurl, openldap, etc). 1576 1577 @item check-cert 1578 Enable certificate checking if the keyserver presents one (for hkps or 1579 ldaps). Defaults to on. 1580 1581 @item ca-cert-file 1582 Provide a certificate store to override the system default. Only 1583 necessary if check-cert is enabled, and the keyserver is using a 1584 certificate that is not present in a system default certificate list. 1585 1586 Note that depending on the SSL library that the keyserver helper is 1587 built with, this may actually be a directory or a file. 1588 1589@end table 1590 1591@item --completes-needed @code{n} 1592@opindex compliant-needed 1593Number of completely trusted users to introduce a new 1594key signer (defaults to 1). 1595 1596@item --marginals-needed @code{n} 1597@opindex marginals-needed 1598Number of marginally trusted users to introduce a new 1599key signer (defaults to 3) 1600 1601@item --max-cert-depth @code{n} 1602@opindex max-cert-depth 1603Maximum depth of a certification chain (default is 5). 1604 1605@item --simple-sk-checksum 1606@opindex simple-sk-checksum 1607Secret keys are integrity protected by using a SHA-1 checksum. This 1608method is part of the upcoming enhanced OpenPGP specification but 1609GnuPG already uses it as a countermeasure against certain attacks. 1610Old applications don't understand this new format, so this option may 1611be used to switch back to the old behaviour. Using this option bears 1612a security risk. Note that using this option only takes effect when 1613the secret key is encrypted - the simplest way to make this happen is 1614to change the passphrase on the key (even changing it to the same 1615value is acceptable). 1616 1617@item --no-sig-cache 1618@opindex no-sig-cache 1619Do not cache the verification status of key signatures. 1620Caching gives a much better performance in key listings. However, if 1621you suspect that your public keyring is not save against write 1622modifications, you can use this option to disable the caching. It 1623probably does not make sense to disable it because all kind of damage 1624can be done if someone else has write access to your public keyring. 1625 1626@item --no-sig-create-check 1627@opindex no-sig-create-check 1628This options is obsolete. It has no function. 1629 1630@item --auto-check-trustdb 1631@itemx --no-auto-check-trustdb 1632@opindex auto-check-trustdb 1633If GnuPG feels that its information about the Web of Trust has to be 1634updated, it automatically runs the @option{--check-trustdb} command 1635internally. This may be a time consuming 1636process. @option{--no-auto-check-trustdb} disables this option. 1637 1638@item --use-agent 1639@itemx --no-use-agent 1640@opindex use-agent 1641Try to use the GnuPG-Agent. With this option, GnuPG first tries to 1642connect to the agent before it asks for a 1643passphrase. @option{--no-use-agent} disables this option. Note, that 1644the tool @command{gpg-preset-passphrase}, which comes with GnuPG-2, 1645cannot be used to preset a passphrase for this version of GnuPG. 1646 1647@item --gpg-agent-info 1648@opindex gpg-agent-info 1649Override the value of the environment variable 1650@samp{GPG_AGENT_INFO}. This is only used when @option{--use-agent} has 1651been given. Given that this option is not anymore used by 1652@command{gpg2}, it should be avoided if possible. 1653 1654 1655@item --lock-once 1656@opindex lock-once 1657Lock the databases the first time a lock is requested 1658and do not release the lock until the process 1659terminates. 1660 1661@item --lock-multiple 1662@opindex lock-multiple 1663Release the locks every time a lock is no longer 1664needed. Use this to override a previous @option{--lock-once} 1665from a config file. 1666 1667@item --lock-never 1668@opindex lock-never 1669Disable locking entirely. This option should be used only in very 1670special environments, where it can be assured that only one process 1671is accessing those files. A bootable floppy with a stand-alone 1672encryption system will probably use this. Improper usage of this 1673option may lead to data and key corruption. 1674 1675@item --exit-on-status-write-error 1676@opindex exit-on-status-write-error 1677This option will cause write errors on the status FD to immediately 1678terminate the process. That should in fact be the default but it never 1679worked this way and thus we need an option to enable this, so that the 1680change won't break applications which close their end of a status fd 1681connected pipe too early. Using this option along with 1682@option{--enable-progress-filter} may be used to cleanly cancel long 1683running gpg operations. 1684 1685@item --limit-card-insert-tries @code{n} 1686@opindex limit-card-insert-tries 1687With @code{n} greater than 0 the number of prompts asking to insert a 1688smartcard gets limited to N-1. Thus with a value of 1 gpg won't at 1689all ask to insert a card if none has been inserted at startup. This 1690option is useful in the configuration file in case an application does 1691not know about the smartcard support and waits ad infinitum for an 1692inserted card. 1693 1694@item --no-random-seed-file 1695@opindex no-random-seed-file 1696GnuPG uses a file to store its internal random pool over invocations. 1697This makes random generation faster; however sometimes write operations 1698are not desired. This option can be used to achieve that with the cost of 1699slower random generation. 1700 1701@item --no-greeting 1702@opindex no-greeting 1703Suppress the initial copyright message. 1704 1705@item --no-secmem-warning 1706@opindex no-secmem-warning 1707Suppress the warning about "using insecure memory". 1708 1709@item --no-permission-warning 1710@opindex permission-warning 1711Suppress the warning about unsafe file and home directory (@option{--homedir}) 1712permissions. Note that the permission checks that GnuPG performs are 1713not intended to be authoritative, but rather they simply warn about 1714certain common permission problems. Do not assume that the lack of a 1715warning means that your system is secure. 1716 1717Note that the warning for unsafe @option{--homedir} permissions cannot be 1718suppressed in the gpg.conf file, as this would allow an attacker to 1719place an unsafe gpg.conf file in place, and use this file to suppress 1720warnings about itself. The @option{--homedir} permissions warning may only be 1721suppressed on the command line. 1722 1723@item --no-mdc-warning 1724@opindex no-mdc-warning 1725Suppress the warning about missing MDC integrity protection. 1726 1727@item --require-secmem 1728@itemx --no-require-secmem 1729@opindex require-secmem 1730Refuse to run if GnuPG cannot get secure memory. Defaults to no 1731(i.e. run, but give a warning). 1732 1733 1734@item --require-cross-certification 1735@itemx --no-require-cross-certification 1736@opindex require-cross-certification 1737When verifying a signature made from a subkey, ensure that the cross 1738certification "back signature" on the subkey is present and valid. This 1739protects against a subtle attack against subkeys that can sign. 1740Defaults to @option{--require-cross-certification} for 1741@command{@gpgname}. 1742 1743@item --expert 1744@itemx --no-expert 1745@opindex expert 1746Allow the user to do certain nonsensical or "silly" things like 1747signing an expired or revoked key, or certain potentially incompatible 1748things like generating unusual key types. This also disables certain 1749warning messages about potentially incompatible actions. As the name 1750implies, this option is for experts only. If you don't fully 1751understand the implications of what it allows you to do, leave this 1752off. @option{--no-expert} disables this option. 1753 1754@end table 1755 1756 1757@c ******************************************* 1758@c ******** KEY RELATED OPTIONS ************ 1759@c ******************************************* 1760@node GPG Key related Options 1761@subsection Key related options 1762 1763@table @gnupgtabopt 1764 1765@item --recipient @var{name} 1766@itemx -r 1767@opindex recipient 1768Encrypt for user id @var{name}. If this option or 1769@option{--hidden-recipient} is not specified, GnuPG asks for the user-id 1770unless @option{--default-recipient} is given. 1771 1772@item --hidden-recipient @var{name} 1773@itemx -R 1774@opindex hidden-recipient 1775Encrypt for user ID @var{name}, but hide the key ID of this user's 1776key. This option helps to hide the receiver of the message and is a 1777limited countermeasure against traffic analysis. If this option or 1778@option{--recipient} is not specified, GnuPG asks for the user ID unless 1779@option{--default-recipient} is given. 1780 1781@item --encrypt-to @code{name} 1782@opindex encrypt-to 1783Same as @option{--recipient} but this one is intended for use in the 1784options file and may be used with your own user-id as an 1785"encrypt-to-self". These keys are only used when there are other 1786recipients given either by use of @option{--recipient} or by the asked 1787user id. No trust checking is performed for these user ids and even 1788disabled keys can be used. 1789 1790@item --hidden-encrypt-to @code{name} 1791@opindex hidden-encrypt-to 1792Same as @option{--hidden-recipient} but this one is intended for use in the 1793options file and may be used with your own user-id as a hidden 1794"encrypt-to-self". These keys are only used when there are other 1795recipients given either by use of @option{--recipient} or by the asked user id. 1796No trust checking is performed for these user ids and even disabled 1797keys can be used. 1798 1799@item --no-encrypt-to 1800@opindex no-encrypt-to 1801Disable the use of all @option{--encrypt-to} and 1802@option{--hidden-encrypt-to} keys. 1803 1804@item --group @code{name=value1 } 1805@opindex group 1806Sets up a named group, which is similar to aliases in email programs. 1807Any time the group name is a recipient (@option{-r} or 1808@option{--recipient}), it will be expanded to the values 1809specified. Multiple groups with the same name are automatically merged 1810into a single group. 1811 1812The values are @code{key IDs} or fingerprints, but any key description 1813is accepted. Note that a value with spaces in it will be treated as 1814two different values. Note also there is only one level of expansion 1815--- you cannot make an group that points to another group. When used 1816from the command line, it may be necessary to quote the argument to 1817this option to prevent the shell from treating it as multiple 1818arguments. 1819 1820@item --ungroup @code{name} 1821@opindex ungroup 1822Remove a given entry from the @option{--group} list. 1823 1824@item --no-groups 1825@opindex no-groups 1826Remove all entries from the @option{--group} list. 1827 1828@item --local-user @var{name} 1829@itemx -u 1830@opindex local-user 1831Use @var{name} as the key to sign with. Note that this option overrides 1832@option{--default-key}. 1833 1834@item --try-all-secrets 1835@opindex try-all-secrets 1836Don't look at the key ID as stored in the message but try all secret 1837keys in turn to find the right decryption key. This option forces the 1838behaviour as used by anonymous recipients (created by using 1839@option{--throw-keyids} or @option{--hidden-recipient}) and might come 1840handy in case where an encrypted message contains a bogus key ID. 1841 1842 1843@end table 1844 1845@c ******************************************* 1846@c ******** INPUT AND OUTPUT *************** 1847@c ******************************************* 1848@node GPG Input and Output 1849@subsection Input and Output 1850 1851@table @gnupgtabopt 1852 1853@item --armor 1854@itemx -a 1855@opindex armor 1856Create ASCII armored output. The default is to create the binary 1857OpenPGP format. 1858 1859@item --no-armor 1860@opindex no-armor 1861Assume the input data is not in ASCII armored format. 1862 1863@item --output @var{file} 1864@itemx -o @var{file} 1865@opindex output 1866Write output to @var{file}. 1867 1868@item --max-output @code{n} 1869@opindex max-output 1870This option sets a limit on the number of bytes that will be generated 1871when processing a file. Since OpenPGP supports various levels of 1872compression, it is possible that the plaintext of a given message may be 1873significantly larger than the original OpenPGP message. While GnuPG 1874works properly with such messages, there is often a desire to set a 1875maximum file size that will be generated before processing is forced to 1876stop by the OS limits. Defaults to 0, which means "no limit". 1877 1878@item --import-options @code{parameters} 1879@opindex import-options 1880This is a space or comma delimited string that gives options for 1881importing keys. Options can be prepended with a `no-' to give the 1882opposite meaning. The options are: 1883 1884@table @asis 1885 1886 @item import-local-sigs 1887 Allow importing key signatures marked as "local". This is not 1888 generally useful unless a shared keyring scheme is being used. 1889 Defaults to no. 1890 1891 @item keep-ownertrust 1892 Normally possible still existing ownertrust values of a key are 1893 cleared if a key is imported. This is in general desirable so that 1894 a formerly deleted key does not automatically gain an ownertrust 1895 values merely due to import. On the other hand it is sometimes 1896 necessary to re-import a trusted set of keys again but keeping 1897 already assigned ownertrust values. This can be achieved by using 1898 this option. 1899 1900 @item repair-pks-subkey-bug 1901 During import, attempt to repair the damage caused by the PKS keyserver 1902 bug (pre version 0.9.6) that mangles keys with multiple subkeys. Note 1903 that this cannot completely repair the damaged key as some crucial data 1904 is removed by the keyserver, but it does at least give you back one 1905 subkey. Defaults to no for regular @option{--import} and to yes for 1906 keyserver @option{--recv-keys}. 1907 1908 @item merge-only 1909 During import, allow key updates to existing keys, but do not allow 1910 any new keys to be imported. Defaults to no. 1911 1912 @item import-clean 1913 After import, compact (remove all signatures except the 1914 self-signature) any user IDs from the new key that are not usable. 1915 Then, remove any signatures from the new key that are not usable. 1916 This includes signatures that were issued by keys that are not present 1917 on the keyring. This option is the same as running the @option{--edit-key} 1918 command "clean" after import. Defaults to no. 1919 1920 @item import-minimal 1921 Import the smallest key possible. This removes all signatures except 1922 the most recent self-signature on each user ID. This option is the 1923 same as running the @option{--edit-key} command "minimize" after import. 1924 Defaults to no. 1925@end table 1926 1927@item --export-options @code{parameters} 1928@opindex export-options 1929This is a space or comma delimited string that gives options for 1930exporting keys. Options can be prepended with a `no-' to give the 1931opposite meaning. The options are: 1932 1933@table @asis 1934 1935 @item export-local-sigs 1936 Allow exporting key signatures marked as "local". This is not 1937 generally useful unless a shared keyring scheme is being used. 1938 Defaults to no. 1939 1940 @item export-attributes 1941 Include attribute user IDs (photo IDs) while exporting. This is 1942 useful to export keys if they are going to be used by an OpenPGP 1943 program that does not accept attribute user IDs. Defaults to yes. 1944 1945 @item export-sensitive-revkeys 1946 Include designated revoker information that was marked as 1947 "sensitive". Defaults to no. 1948 1949 @item export-reset-subkey-passwd 1950 When using the @option{--export-secret-subkeys} command, this option resets 1951 the passphrases for all exported subkeys to empty. This is useful 1952 when the exported subkey is to be used on an unattended machine where 1953 a passphrase doesn't necessarily make sense. Defaults to no. 1954 1955 @item export-clean 1956 Compact (remove all signatures from) user IDs on the key being 1957 exported if the user IDs are not usable. Also, do not export any 1958 signatures that are not usable. This includes signatures that were 1959 issued by keys that are not present on the keyring. This option is 1960 the same as running the @option{--edit-key} command "clean" before export 1961 except that the local copy of the key is not modified. Defaults to 1962 no. 1963 1964 @item export-minimal 1965 Export the smallest key possible. This removes all signatures except the 1966 most recent self-signature on each user ID. This option is the same as 1967 running the @option{--edit-key} command "minimize" before export except 1968 that the local copy of the key is not modified. Defaults to no. 1969@end table 1970 1971@item --with-colons 1972@opindex with-colons 1973Print key listings delimited by colons. Note that the output will be 1974encoded in UTF-8 regardless of any @option{--display-charset} setting. This 1975format is useful when GnuPG is called from scripts and other programs 1976as it is easily machine parsed. The details of this format are 1977documented in the file @file{doc/DETAILS}, which is included in the GnuPG 1978source distribution. 1979 1980@item --fixed-list-mode 1981@opindex fixed-list-mode 1982Do not merge primary user ID and primary key in @option{--with-colon} 1983listing mode and print all timestamps as seconds since 1970-01-01. 1984 1985@item --with-fingerprint 1986@opindex with-fingerprint 1987Same as the command @option{--fingerprint} but changes only the format 1988of the output and may be used together with another command. 1989 1990@end table 1991 1992@c ******************************************* 1993@c ******** OPENPGP OPTIONS **************** 1994@c ******************************************* 1995@node OpenPGP Options 1996@subsection OpenPGP protocol specific options. 1997 1998@table @gnupgtabopt 1999 2000@item -t, --textmode 2001@itemx --no-textmode 2002@opindex textmode 2003Treat input files as text and store them in the OpenPGP canonical text 2004form with standard "CRLF" line endings. This also sets the necessary 2005flags to inform the recipient that the encrypted or signed data is text 2006and may need its line endings converted back to whatever the local 2007system uses. This option is useful when communicating between two 2008platforms that have different line ending conventions (UNIX-like to Mac, 2009Mac to Windows, etc). @option{--no-textmode} disables this option, and 2010is the default. 2011 2012If @option{-t} (but not @option{--textmode}) is used together with 2013armoring and signing, this enables clearsigned messages. This kludge is 2014needed for command-line compatibility with command-line versions of PGP; 2015normally you would use @option{--sign} or @option{--clearsign} to select 2016the type of the signature. 2017 2018@item --force-v3-sigs 2019@itemx --no-force-v3-sigs 2020@opindex force-v3-sigs 2021OpenPGP states that an implementation should generate v4 signatures 2022but PGP versions 5 through 7 only recognize v4 signatures on key 2023material. This option forces v3 signatures for signatures on data. 2024Note that this option implies @option{--no-ask-sig-expire}, and unsets 2025@option{--sig-policy-url}, @option{--sig-notation}, and 2026@option{--sig-keyserver-url}, as these features cannot be used with v3 2027signatures. @option{--no-force-v3-sigs} disables this option. 2028Defaults to no. 2029 2030@item --force-v4-certs 2031@itemx --no-force-v4-certs 2032@opindex force-v4-certs 2033Always use v4 key signatures even on v3 keys. This option also 2034changes the default hash algorithm for v3 RSA keys from MD5 to SHA-1. 2035@option{--no-force-v4-certs} disables this option. 2036 2037@item --force-mdc 2038@opindex force-mdc 2039Force the use of encryption with a modification detection code. This 2040is always used with the newer ciphers (those with a blocksize greater 2041than 64 bits), or if all of the recipient keys indicate MDC support in 2042their feature flags. 2043 2044@item --disable-mdc 2045@opindex disable-mdc 2046Disable the use of the modification detection code. Note that by 2047using this option, the encrypted message becomes vulnerable to a 2048message modification attack. 2049 2050@item --personal-cipher-preferences @code{string} 2051@opindex personal-cipher-preferences 2052Set the list of personal cipher preferences to @code{string}. Use 2053@command{@gpgname --version} to get a list of available algorithms, 2054and use @code{none} to set no preference at all. This allows the user 2055to safely override the algorithm chosen by the recipient key 2056preferences, as GPG will only select an algorithm that is usable by 2057all recipients. The most highly ranked cipher in this list is also 2058used for the @option{--symmetric} encryption command. 2059 2060@item --personal-digest-preferences @code{string} 2061@opindex personal-digest-preferences 2062Set the list of personal digest preferences to @code{string}. Use 2063@command{@gpgname --version} to get a list of available algorithms, 2064and use @code{none} to set no preference at all. This allows the user 2065to safely override the algorithm chosen by the recipient key 2066preferences, as GPG will only select an algorithm that is usable by 2067all recipients. The most highly ranked digest algorithm in this list 2068is also used when signing without encryption 2069(e.g. @option{--clearsign} or @option{--sign}). 2070 2071@item --personal-compress-preferences @code{string} 2072@opindex personal-compress-preferences 2073Set the list of personal compression preferences to @code{string}. 2074Use @command{@gpgname --version} to get a list of available 2075algorithms, and use @code{none} to set no preference at all. This 2076allows the user to safely override the algorithm chosen by the 2077recipient key preferences, as GPG will only select an algorithm that 2078is usable by all recipients. The most highly ranked compression 2079algorithm in this list is also used when there are no recipient keys 2080to consider (e.g. @option{--symmetric}). 2081 2082@item --s2k-cipher-algo @code{name} 2083@opindex s2k-cipher-algo 2084Use @code{name} as the cipher algorithm used to protect secret keys. 2085The default cipher is @value{DEFSYMENCALGO}. This cipher is also used for 2086conventional encryption if @option{--personal-cipher-preferences} and 2087@option{--cipher-algo} is not given. 2088 2089@item --s2k-digest-algo @code{name} 2090@opindex s2k-digest-algo 2091Use @code{name} as the digest algorithm used to mangle the passphrases. 2092The default algorithm is SHA-1. 2093 2094@item --s2k-mode @code{n} 2095@opindex s2k-mode 2096Selects how passphrases are mangled. If @code{n} is 0 a plain 2097passphrase (which is not recommended) will be used, a 1 adds a salt to 2098the passphrase and a 3 (the default) iterates the whole process a 2099number of times (see --s2k-count). Unless @option{--rfc1991} is used, 2100this mode is also used for conventional encryption. 2101 2102@item --s2k-count @code{n} 2103@opindex s2k-count 2104Specify how many times the passphrase mangling is repeated. This 2105value may range between 1024 and 65011712 inclusive. The default is 2106inquired from gpg-agent. Note that not all values in the 21071024-65011712 range are legal and if an illegal value is selected, 2108GnuPG will round up to the nearest legal value. This option is only 2109meaningful if @option{--s2k-mode} is 3. 2110 2111 2112@end table 2113 2114@c *************************** 2115@c ******* Compliance ******** 2116@c *************************** 2117@node Compliance Options 2118@subsection Compliance options 2119 2120These options control what GnuPG is compliant to. Only one of these 2121options may be active at a time. Note that the default setting of 2122this is nearly always the correct one. See the INTEROPERABILITY WITH 2123OTHER OPENPGP PROGRAMS section below before using one of these 2124options. 2125 2126@table @gnupgtabopt 2127 2128@item --gnupg 2129@opindex gnupg 2130Use standard GnuPG behavior. This is essentially OpenPGP behavior 2131(see @option{--openpgp}), but with some additional workarounds for common 2132compatibility problems in different versions of PGP. This is the 2133default option, so it is not generally needed, but it may be useful to 2134override a different compliance option in the gpg.conf file. 2135 2136@item --openpgp 2137@opindex openpgp 2138Reset all packet, cipher and digest options to strict OpenPGP 2139behavior. Use this option to reset all previous options like 2140@option{--s2k-*}, @option{--cipher-algo}, @option{--digest-algo} and 2141@option{--compress-algo} to OpenPGP compliant values. All PGP 2142workarounds are disabled. 2143 2144@item --rfc4880 2145@opindex rfc4880 2146Reset all packet, cipher and digest options to strict RFC-4880 2147behavior. Note that this is currently the same thing as 2148@option{--openpgp}. 2149 2150@item --rfc2440 2151@opindex rfc2440 2152Reset all packet, cipher and digest options to strict RFC-2440 2153behavior. 2154 2155@ifclear gpgtowone 2156@item --rfc1991 2157@opindex rfc1991 2158Try to be more RFC-1991 (PGP 2.x) compliant. This option is 2159deprecated will be removed in GnuPG 2.1. 2160 2161@item --pgp2 2162@opindex pgp2 2163Set up all options to be as PGP 2.x compliant as possible, and warn if 2164an action is taken (e.g. encrypting to a non-RSA key) that will create 2165a message that PGP 2.x will not be able to handle. Note that `PGP 21662.x' here means `MIT PGP 2.6.2'. There are other versions of PGP 2.x 2167available, but the MIT release is a good common baseline. 2168 2169This option implies 2170@option{--rfc1991 --disable-mdc --no-force-v4-certs 2171 --escape-from-lines --force-v3-sigs --allow-weak-digest-algos 2172 --cipher-algo IDEA --digest-algo MD5 --compress-algo ZIP}. 2173It also disables @option{--textmode} when encrypting. 2174 2175This option is deprecated will be removed in GnuPG 2.1. The reason 2176for dropping PGP-2 support is that the PGP 2 format is not anymore 2177considered safe (for example due to the use of the broken MD5 algorithm). 2178Note that the decryption of PGP-2 created messages will continue to work. 2179@end ifclear 2180 2181@item --pgp6 2182@opindex pgp6 2183Set up all options to be as PGP 6 compliant as possible. This 2184restricts you to the ciphers IDEA (if the IDEA plugin is installed), 21853DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160, and the 2186compression algorithms none and ZIP. This also disables 2187--throw-keyids, and making signatures with signing subkeys as PGP 6 2188does not understand signatures made by signing subkeys. 2189 2190This option implies @option{--disable-mdc --escape-from-lines 2191--force-v3-sigs}. 2192 2193@item --pgp7 2194@opindex pgp7 2195Set up all options to be as PGP 7 compliant as possible. This is 2196identical to @option{--pgp6} except that MDCs are not disabled, and the 2197list of allowable ciphers is expanded to add AES128, AES192, AES256, and 2198TWOFISH. 2199 2200@item --pgp8 2201@opindex pgp8 2202Set up all options to be as PGP 8 compliant as possible. PGP 8 is a lot 2203closer to the OpenPGP standard than previous versions of PGP, so all 2204this does is disable @option{--throw-keyids} and set 2205@option{--escape-from-lines}. All algorithms are allowed except for the 2206SHA224, SHA384, and SHA512 digests. 2207 2208@end table 2209 2210 2211@c ******************************************* 2212@c ******** ESOTERIC OPTIONS *************** 2213@c ******************************************* 2214@node GPG Esoteric Options 2215@subsection Doing things one usually doesn't want to do. 2216 2217@table @gnupgtabopt 2218 2219@item -n 2220@itemx --dry-run 2221@opindex dry-run 2222Don't make any changes (this is not completely implemented). 2223 2224@item --list-only 2225@opindex list-only 2226Changes the behaviour of some commands. This is like @option{--dry-run} but 2227different in some cases. The semantic of this command may be extended in 2228the future. Currently it only skips the actual decryption pass and 2229therefore enables a fast listing of the encryption keys. 2230 2231@item -i 2232@itemx --interactive 2233@opindex interactive 2234Prompt before overwriting any files. 2235 2236@item --debug-level @var{level} 2237@opindex debug-level 2238Select the debug level for investigating problems. @var{level} may be 2239a numeric value or by a keyword: 2240 2241@table @code 2242 @item none 2243 No debugging at all. A value of less than 1 may be used instead of 2244 the keyword. 2245 @item basic 2246 Some basic debug messages. A value between 1 and 2 may be used 2247 instead of the keyword. 2248 @item advanced 2249 More verbose debug messages. A value between 3 and 5 may be used 2250 instead of the keyword. 2251 @item expert 2252 Even more detailed messages. A value between 6 and 8 may be used 2253 instead of the keyword. 2254 @item guru 2255 All of the debug messages you can get. A value greater than 8 may be 2256 used instead of the keyword. The creation of hash tracing files is 2257 only enabled if the keyword is used. 2258@end table 2259 2260How these messages are mapped to the actual debugging flags is not 2261specified and may change with newer releases of this program. They are 2262however carefully selected to best aid in debugging. 2263 2264@item --debug @var{flags} 2265@opindex debug 2266Set debugging flags. All flags are or-ed and @var{flags} may 2267be given in C syntax (e.g. 0x0042). 2268 2269@item --debug-all 2270@opindex debug-all 2271Set all useful debugging flags. 2272 2273@item --debug-ccid-driver 2274@opindex debug-ccid-driver 2275Enable debug output from the included CCID driver for smartcards. 2276Note that this option is only available on some system. 2277 2278@item --enable-progress-filter 2279@opindex enable-progress-filter 2280Enable certain PROGRESS status outputs. This option allows frontends 2281to display a progress indicator while gpg is processing larger files. 2282There is a slight performance overhead using it. 2283 2284@item --status-fd @code{n} 2285@opindex status-fd 2286Write special status strings to the file descriptor @code{n}. 2287See the file DETAILS in the documentation for a listing of them. 2288 2289@item --status-file @code{file} 2290@opindex status-file 2291Same as @option{--status-fd}, except the status data is written to file 2292@code{file}. 2293 2294@item --logger-fd @code{n} 2295@opindex logger-fd 2296Write log output to file descriptor @code{n} and not to STDERR. 2297 2298@item --log-file @code{file} 2299@itemx --logger-file @code{file} 2300@opindex log-file 2301Same as @option{--logger-fd}, except the logger data is written to file 2302@code{file}. Note that @option{--log-file} is only implemented for 2303GnuPG-2. 2304 2305@item --attribute-fd @code{n} 2306@opindex attribute-fd 2307Write attribute subpackets to the file descriptor @code{n}. This is most 2308useful for use with @option{--status-fd}, since the status messages are 2309needed to separate out the various subpackets from the stream delivered 2310to the file descriptor. 2311 2312@item --attribute-file @code{file} 2313@opindex attribute-file 2314Same as @option{--attribute-fd}, except the attribute data is written to 2315file @code{file}. 2316 2317@item --comment @code{string} 2318@itemx --no-comments 2319@opindex comment 2320Use @code{string} as a comment string in clear text signatures and ASCII 2321armored messages or keys (see @option{--armor}). The default behavior is 2322not to use a comment string. @option{--comment} may be repeated multiple 2323times to get multiple comment strings. @option{--no-comments} removes 2324all comments. It is a good idea to keep the length of a single comment 2325below 60 characters to avoid problems with mail programs wrapping such 2326lines. Note that comment lines, like all other header lines, are not 2327protected by the signature. 2328 2329@item --emit-version 2330@itemx --no-emit-version 2331@opindex emit-version 2332Force inclusion of the version string in ASCII armored output. If 2333given once only the name of the program and the major number is 2334emitted, given twice the minor is also emitted, given triple 2335the micro is added, and given quad an operating system identification 2336is also emitted. @option{--no-emit-version} (default) disables the version 2337line. 2338 2339@item --sig-notation @code{name=value} 2340@itemx --cert-notation @code{name=value} 2341@itemx -N, --set-notation @code{name=value} 2342@opindex sig-notation 2343@opindex cert-notation 2344@opindex set-notation 2345Put the name value pair into the signature as notation data. 2346@code{name} must consist only of printable characters or spaces, and 2347must contain a '@@' character in the form keyname@@domain.example.com 2348(substituting the appropriate keyname and domain name, of course). This 2349is to help prevent pollution of the IETF reserved notation 2350namespace. The @option{--expert} flag overrides the '@@' 2351check. @code{value} may be any printable string; it will be encoded in 2352UTF8, so you should check that your @option{--display-charset} is set 2353correctly. If you prefix @code{name} with an exclamation mark (!), the 2354notation data will be flagged as critical 2355(rfc4880:5.2.3.16). @option{--sig-notation} sets a notation for data 2356signatures. @option{--cert-notation} sets a notation for key signatures 2357(certifications). @option{--set-notation} sets both. 2358 2359There are special codes that may be used in notation names. "%k" will 2360be expanded into the key ID of the key being signed, "%K" into the 2361long key ID of the key being signed, "%f" into the fingerprint of the 2362key being signed, "%s" into the key ID of the key making the 2363signature, "%S" into the long key ID of the key making the signature, 2364"%g" into the fingerprint of the key making the signature (which might 2365be a subkey), "%p" into the fingerprint of the primary key of the key 2366making the signature, "%c" into the signature count from the OpenPGP 2367smartcard, and "%%" results in a single "%". %k, %K, and %f are only 2368meaningful when making a key signature (certification), and %c is only 2369meaningful when using the OpenPGP smartcard. 2370 2371@item --sig-policy-url @code{string} 2372@itemx --cert-policy-url @code{string} 2373@itemx --set-policy-url @code{string} 2374@opindex sig-policy-url 2375@opindex cert-policy-url 2376@opindex set-policy-url 2377Use @code{string} as a Policy URL for signatures (rfc4880:5.2.3.20). If 2378you prefix it with an exclamation mark (!), the policy URL packet will 2379be flagged as critical. @option{--sig-policy-url} sets a policy url for 2380data signatures. @option{--cert-policy-url} sets a policy url for key 2381signatures (certifications). @option{--set-policy-url} sets both. 2382 2383The same %-expandos used for notation data are available here as well. 2384 2385@item --sig-keyserver-url @code{string} 2386@opindex sig-keyserver-url 2387Use @code{string} as a preferred keyserver URL for data signatures. If 2388you prefix it with an exclamation mark (!), the keyserver URL packet 2389will be flagged as critical. 2390 2391The same %-expandos used for notation data are available here as well. 2392 2393@item --set-filename @code{string} 2394@opindex set-filename 2395Use @code{string} as the filename which is stored inside messages. 2396This overrides the default, which is to use the actual filename of the 2397file being encrypted. 2398 2399@item --for-your-eyes-only 2400@itemx --no-for-your-eyes-only 2401@opindex for-your-eyes-only 2402Set the `for your eyes only' flag in the message. This causes GnuPG to 2403refuse to save the file unless the @option{--output} option is given, 2404and PGP to use a "secure viewer" with a claimed Tempest-resistant font 2405to display the message. This option overrides @option{--set-filename}. 2406@option{--no-for-your-eyes-only} disables this option. 2407 2408@item --use-embedded-filename 2409@itemx --no-use-embedded-filename 2410@opindex use-embedded-filename 2411Try to create a file with a name as embedded in the data. This can be 2412a dangerous option as it enables overwriting files. Defaults to no. 2413 2414@item --cipher-algo @code{name} 2415@opindex cipher-algo 2416Use @code{name} as cipher algorithm. Running the program with the 2417command @option{--version} yields a list of supported algorithms. If 2418this is not used the cipher algorithm is selected from the preferences 2419stored with the key. In general, you do not want to use this option as 2420it allows you to violate the OpenPGP standard. 2421@option{--personal-cipher-preferences} is the safe way to accomplish the 2422same thing. 2423 2424@item --digest-algo @code{name} 2425@opindex digest-algo 2426Use @code{name} as the message digest algorithm. Running the program 2427with the command @option{--version} yields a list of supported algorithms. In 2428general, you do not want to use this option as it allows you to 2429violate the OpenPGP standard. @option{--personal-digest-preferences} is the 2430safe way to accomplish the same thing. 2431 2432@item --compress-algo @code{name} 2433@opindex compress-algo 2434Use compression algorithm @code{name}. "zlib" is RFC-1950 ZLIB 2435compression. "zip" is RFC-1951 ZIP compression which is used by PGP. 2436"bzip2" is a more modern compression scheme that can compress some 2437things better than zip or zlib, but at the cost of more memory used 2438during compression and decompression. "uncompressed" or "none" 2439disables compression. If this option is not used, the default 2440behavior is to examine the recipient key preferences to see which 2441algorithms the recipient supports. If all else fails, ZIP is used for 2442maximum compatibility. 2443 2444ZLIB may give better compression results than ZIP, as the compression 2445window size is not limited to 8k. BZIP2 may give even better 2446compression results than that, but will use a significantly larger 2447amount of memory while compressing and decompressing. This may be 2448significant in low memory situations. Note, however, that PGP (all 2449versions) only supports ZIP compression. Using any algorithm other 2450than ZIP or "none" will make the message unreadable with PGP. In 2451general, you do not want to use this option as it allows you to 2452violate the OpenPGP standard. @option{--personal-compress-preferences} is the 2453safe way to accomplish the same thing. 2454 2455@item --cert-digest-algo @code{name} 2456@opindex cert-digest-algo 2457Use @code{name} as the message digest algorithm used when signing a 2458key. Running the program with the command @option{--version} yields a 2459list of supported algorithms. Be aware that if you choose an algorithm 2460that GnuPG supports but other OpenPGP implementations do not, then some 2461users will not be able to use the key signatures you make, or quite 2462possibly your entire key. 2463 2464@item --disable-cipher-algo @code{name} 2465@opindex disable-cipher-algo 2466Never allow the use of @code{name} as cipher algorithm. 2467The given name will not be checked so that a later loaded algorithm 2468will still get disabled. 2469 2470@item --disable-pubkey-algo @code{name} 2471@opindex disable-pubkey-algo 2472Never allow the use of @code{name} as public key algorithm. 2473The given name will not be checked so that a later loaded algorithm 2474will still get disabled. 2475 2476@item --throw-keyids 2477@itemx --no-throw-keyids 2478@opindex throw-keyids 2479Do not put the recipient key IDs into encrypted messages. This helps to 2480hide the receivers of the message and is a limited countermeasure 2481against traffic analysis.@footnote{Using a little social engineering 2482anyone who is able to decrypt the message can check whether one of the 2483other recipients is the one he suspects.} On the receiving side, it may 2484slow down the decryption process because all available secret keys must 2485be tried. @option{--no-throw-keyids} disables this option. This option 2486is essentially the same as using @option{--hidden-recipient} for all 2487recipients. 2488 2489@item --not-dash-escaped 2490@opindex not-dash-escaped 2491This option changes the behavior of cleartext signatures 2492so that they can be used for patch files. You should not 2493send such an armored file via email because all spaces 2494and line endings are hashed too. You can not use this 2495option for data which has 5 dashes at the beginning of a 2496line, patch files don't have this. A special armor header 2497line tells GnuPG about this cleartext signature option. 2498 2499@item --escape-from-lines 2500@itemx --no-escape-from-lines 2501@opindex escape-from-lines 2502Because some mailers change lines starting with "From " to ">From " it 2503is good to handle such lines in a special way when creating cleartext 2504signatures to prevent the mail system from breaking the signature. Note 2505that all other PGP versions do it this way too. Enabled by 2506default. @option{--no-escape-from-lines} disables this option. 2507 2508@item --passphrase-repeat @code{n} 2509@opindex passphrase-repeat 2510Specify how many times @command{@gpgname} will request a new 2511passphrase be repeated. This is useful for helping memorize a 2512passphrase. Defaults to 1 repetition. 2513 2514@item --passphrase-fd @code{n} 2515@opindex passphrase-fd 2516Read the passphrase from file descriptor @code{n}. Only the first line 2517will be read from file descriptor @code{n}. If you use 0 for @code{n}, 2518the passphrase will be read from STDIN. This can only be used if only 2519one passphrase is supplied. 2520 2521@item --passphrase-file @code{file} 2522@opindex passphrase-file 2523Read the passphrase from file @code{file}. Only the first line will 2524be read from file @code{file}. This can only be used if only one 2525passphrase is supplied. Obviously, a passphrase stored in a file is 2526of questionable security if other users can read this file. Don't use 2527this option if you can avoid it. 2528 2529@item --passphrase @code{string} 2530@opindex passphrase 2531Use @code{string} as the passphrase. This can only be used if only one 2532passphrase is supplied. Obviously, this is of very questionable 2533security on a multi-user system. Don't use this option if you can 2534avoid it. 2535 2536@item --command-fd @code{n} 2537@opindex command-fd 2538This is a replacement for the deprecated shared-memory IPC mode. 2539If this option is enabled, user input on questions is not expected 2540from the TTY but from the given file descriptor. It should be used 2541together with @option{--status-fd}. See the file doc/DETAILS in the source 2542distribution for details on how to use it. 2543 2544@item --command-file @code{file} 2545@opindex command-file 2546Same as @option{--command-fd}, except the commands are read out of file 2547@code{file} 2548 2549@item --allow-non-selfsigned-uid 2550@itemx --no-allow-non-selfsigned-uid 2551@opindex allow-non-selfsigned-uid 2552Allow the import and use of keys with user IDs which are not 2553self-signed. This is not recommended, as a non self-signed user ID is 2554trivial to forge. @option{--no-allow-non-selfsigned-uid} disables. 2555 2556@item --allow-freeform-uid 2557@opindex allow-freeform-uid 2558Disable all checks on the form of the user ID while generating a new 2559one. This option should only be used in very special environments as 2560it does not ensure the de-facto standard format of user IDs. 2561 2562@item --ignore-time-conflict 2563@opindex ignore-time-conflict 2564GnuPG normally checks that the timestamps associated with keys and 2565signatures have plausible values. However, sometimes a signature 2566seems to be older than the key due to clock problems. This option 2567makes these checks just a warning. See also @option{--ignore-valid-from} for 2568timestamp issues on subkeys. 2569 2570@item --ignore-valid-from 2571@opindex ignore-valid-from 2572GnuPG normally does not select and use subkeys created in the future. 2573This option allows the use of such keys and thus exhibits the 2574pre-1.0.7 behaviour. You should not use this option unless there 2575is some clock problem. See also @option{--ignore-time-conflict} for timestamp 2576issues with signatures. 2577 2578@item --ignore-crc-error 2579@opindex ignore-crc-error 2580The ASCII armor used by OpenPGP is protected by a CRC checksum against 2581transmission errors. Occasionally the CRC gets mangled somewhere on 2582the transmission channel but the actual content (which is protected by 2583the OpenPGP protocol anyway) is still okay. This option allows GnuPG 2584to ignore CRC errors. 2585 2586@item --ignore-mdc-error 2587@opindex ignore-mdc-error 2588This option changes a MDC integrity protection failure into a warning. 2589This can be useful if a message is partially corrupt, but it is 2590necessary to get as much data as possible out of the corrupt message. 2591However, be aware that a MDC protection failure may also mean that the 2592message was tampered with intentionally by an attacker. 2593 2594@item --allow-weak-digest-algos 2595@opindex allow-weak-digest-algos 2596Signatures made with known-weak digest algorithms are normally 2597rejected with an ``invalid digest algorithm'' message. This option 2598allows the verification of signatures made with such weak algorithms. 2599MD5 is the only digest algorithm considered weak by default. See also 2600@option{--weak-digest} to reject other digest algorithms. 2601 2602@item --weak-digest @code{name} 2603@opindex weak-digest 2604Treat the specified digest algorithm as weak. Signatures made over 2605weak digests algorithms are normally rejected. This option can be 2606supplied multiple times if multiple algorithms should be considered 2607weak. See also @option{--allow-weak-digest-algos} to disable 2608rejection of weak digests. MD5 is always considered weak, and does 2609not need to be listed explicitly. 2610 2611 2612@item --no-default-keyring 2613@opindex no-default-keyring 2614Do not add the default keyrings to the list of keyrings. Note that 2615GnuPG will not operate without any keyrings, so if you use this option 2616and do not provide alternate keyrings via @option{--keyring} or 2617@option{--secret-keyring}, then GnuPG will still use the default public or 2618secret keyrings. 2619 2620@item --skip-verify 2621@opindex skip-verify 2622Skip the signature verification step. This may be 2623used to make the decryption faster if the signature 2624verification is not needed. 2625 2626@item --with-key-data 2627@opindex with-key-data 2628Print key listings delimited by colons (like @option{--with-colons}) and 2629print the public key data. 2630 2631@item --fast-list-mode 2632@opindex fast-list-mode 2633Changes the output of the list commands to work faster; this is achieved 2634by leaving some parts empty. Some applications don't need the user ID 2635and the trust information given in the listings. By using this options 2636they can get a faster listing. The exact behaviour of this option may 2637change in future versions. If you are missing some information, don't 2638use this option. 2639 2640@item --no-literal 2641@opindex no-literal 2642This is not for normal use. Use the source to see for what it might be useful. 2643 2644@item --set-filesize 2645@opindex set-filesize 2646This is not for normal use. Use the source to see for what it might be useful. 2647 2648@item --show-session-key 2649@opindex show-session-key 2650Display the session key used for one message. See 2651@option{--override-session-key} for the counterpart of this option. 2652 2653We think that Key Escrow is a Bad Thing; however the user should have 2654the freedom to decide whether to go to prison or to reveal the content 2655of one specific message without compromising all messages ever 2656encrypted for one secret key. DON'T USE IT UNLESS YOU ARE REALLY 2657FORCED TO DO SO. 2658 2659@item --override-session-key @code{string} 2660@opindex override-session-key 2661Don't use the public key but the session key @code{string}. The format 2662of this string is the same as the one printed by 2663@option{--show-session-key}. This option is normally not used but comes 2664handy in case someone forces you to reveal the content of an encrypted 2665message; using this option you can do this without handing out the 2666secret key. 2667 2668@item --ask-sig-expire 2669@itemx --no-ask-sig-expire 2670@opindex ask-sig-expire 2671When making a data signature, prompt for an expiration time. If this 2672option is not specified, the expiration time set via 2673@option{--default-sig-expire} is used. @option{--no-ask-sig-expire} 2674disables this option. 2675 2676@item --default-sig-expire 2677@opindex default-sig-expire 2678The default expiration time to use for signature expiration. Valid 2679values are "0" for no expiration, a number followed by the letter d 2680(for days), w (for weeks), m (for months), or y (for years) (for 2681example "2m" for two months, or "5y" for five years), or an absolute 2682date in the form YYYY-MM-DD. Defaults to "0". 2683 2684@item --ask-cert-expire 2685@itemx --no-ask-cert-expire 2686@opindex ask-cert-expire 2687When making a key signature, prompt for an expiration time. If this 2688option is not specified, the expiration time set via 2689@option{--default-cert-expire} is used. @option{--no-ask-cert-expire} 2690disables this option. 2691 2692@item --default-cert-expire 2693@opindex default-cert-expire 2694The default expiration time to use for key signature expiration. 2695Valid values are "0" for no expiration, a number followed by the 2696letter d (for days), w (for weeks), m (for months), or y (for years) 2697(for example "2m" for two months, or "5y" for five years), or an 2698absolute date in the form YYYY-MM-DD. Defaults to "0". 2699 2700@item --allow-secret-key-import 2701@opindex allow-secret-key-import 2702This is an obsolete option and is not used anywhere. 2703 2704@item --allow-multiple-messages 2705@item --no-allow-multiple-messages 2706@opindex allow-multiple-messages 2707Allow processing of multiple OpenPGP messages contained in a single file 2708or stream. Some programs that call GPG are not prepared to deal with 2709multiple messages being processed together, so this option defaults to 2710no. Note that versions of GPG prior to 1.4.7 always allowed multiple 2711messages. 2712 2713Warning: Do not use this option unless you need it as a temporary 2714workaround! 2715 2716 2717@item --enable-special-filenames 2718@opindex enable-special-filenames 2719This options enables a mode in which filenames of the form 2720@file{-&n}, where n is a non-negative decimal number, 2721refer to the file descriptor n and not to a file with that name. 2722 2723@item --no-expensive-trust-checks 2724@opindex no-expensive-trust-checks 2725Experimental use only. 2726 2727@item --preserve-permissions 2728@opindex preserve-permissions 2729Don't change the permissions of a secret keyring back to user 2730read/write only. Use this option only if you really know what you are doing. 2731 2732@item --default-preference-list @code{string} 2733@opindex default-preference-list 2734Set the list of default preferences to @code{string}. This preference 2735list is used for new keys and becomes the default for "setpref" in the 2736edit menu. 2737 2738@item --default-keyserver-url @code{name} 2739@opindex default-keyserver-url 2740Set the default keyserver URL to @code{name}. This keyserver will be 2741used as the keyserver URL when writing a new self-signature on a key, 2742which includes key generation and changing preferences. 2743 2744@item --list-config 2745@opindex list-config 2746Display various internal configuration parameters of GnuPG. This option 2747is intended for external programs that call GnuPG to perform tasks, and 2748is thus not generally useful. See the file @file{doc/DETAILS} in the 2749source distribution for the details of which configuration items may be 2750listed. @option{--list-config} is only usable with 2751@option{--with-colons} set. 2752 2753@item --gpgconf-list 2754@opindex gpgconf-list 2755This command is similar to @option{--list-config} but in general only 2756internally used by the @command{gpgconf} tool. 2757 2758@item --gpgconf-test 2759@opindex gpgconf-test 2760This is more or less dummy action. However it parses the configuration 2761file and returns with failure if the configuration file would prevent 2762@command{gpg} from startup. Thus it may be used to run a syntax check 2763on the configuration file. 2764 2765@end table 2766 2767@c ******************************* 2768@c ******* Deprecated ************ 2769@c ******************************* 2770@node Deprecated Options 2771@subsection Deprecated options 2772 2773@table @gnupgtabopt 2774 2775@item --load-extension @code{name} 2776@opindex load-extension 2777Load an extension module. If @code{name} does not contain a slash it is 2778searched for in the directory configured when GnuPG was built 2779(generally "/usr/local/lib/gnupg"). Extensions are not generally 2780useful anymore, and the use of this option is deprecated. 2781 2782@item --show-photos 2783@itemx --no-show-photos 2784@opindex show-photos 2785Causes @option{--list-keys}, @option{--list-sigs}, 2786@option{--list-public-keys}, @option{--list-secret-keys}, and verifying 2787a signature to also display the photo ID attached to the key, if 2788any. See also @option{--photo-viewer}. These options are deprecated. Use 2789@option{--list-options [no-]show-photos} and/or @option{--verify-options 2790[no-]show-photos} instead. 2791 2792@item --show-keyring 2793@opindex show-keyring 2794Display the keyring name at the head of key listings to show which 2795keyring a given key resides on. This option is deprecated: use 2796@option{--list-options [no-]show-keyring} instead. 2797 2798@item --ctapi-driver @code{file} 2799@opindex ctapi-driver 2800Use @code{file} to access the smartcard reader. The current default 2801is `libtowitoko.so'. Note that the use of this interface is 2802deprecated; it may be removed in future releases. 2803 2804@item --always-trust 2805@opindex always-trust 2806Identical to @option{--trust-model always}. This option is deprecated. 2807 2808@item --show-notation 2809@itemx --no-show-notation 2810@opindex show-notation 2811Show signature notations in the @option{--list-sigs} or @option{--check-sigs} listings 2812as well as when verifying a signature with a notation in it. These 2813options are deprecated. Use @option{--list-options [no-]show-notation} 2814and/or @option{--verify-options [no-]show-notation} instead. 2815 2816@item --show-policy-url 2817@itemx --no-show-policy-url 2818@opindex show-policy-url 2819Show policy URLs in the @option{--list-sigs} or @option{--check-sigs} 2820listings as well as when verifying a signature with a policy URL in 2821it. These options are deprecated. Use @option{--list-options 2822[no-]show-policy-url} and/or @option{--verify-options 2823[no-]show-policy-url} instead. 2824 2825 2826@end table 2827 2828 2829@c ******************************************* 2830@c *************** **************** 2831@c *************** FILES **************** 2832@c *************** **************** 2833@c ******************************************* 2834@mansect files 2835@node GPG Configuration 2836@section Configuration files 2837 2838There are a few configuration files to control certain aspects of 2839@command{@gpgname}'s operation. Unless noted, they are expected in the 2840current home directory (@pxref{option --homedir}). 2841 2842@table @file 2843 2844 @item gpg.conf 2845 @cindex gpg.conf 2846 This is the standard configuration file read by @command{@gpgname} on 2847 startup. It may contain any valid long option; the leading two dashes 2848 may not be entered and the option may not be abbreviated. This default 2849 name may be changed on the command line (@pxref{gpg-option --options}). 2850 You should backup this file. 2851 2852@end table 2853 2854@c man:.RE 2855Note that on larger installations, it is useful to put predefined files 2856into the directory @file{/etc/skel/.gnupg/} so that newly created users 2857start up with a working configuration. 2858 2859For internal purposes @command{@gpgname} creates and maintains a few other 2860files; They all live in in the current home directory (@pxref{option 2861--homedir}). Only the @command{@gpgname} may modify these files. 2862 2863 2864@table @file 2865 @item ~/.gnupg/pubring.gpg 2866 The public keyring. You should backup this file. 2867 2868 @item ~/.gnupg/pubring.gpg.lock 2869 The lock file for the public keyring. 2870 2871 @item ~/.gnupg/pubring.kbx 2872 @itemx ~/.gnupg/pubring.kbx.lock 2873 A public keyring and its lock file used by GnuPG versions >= 2. 2874 It is ignored by GnuPG 1.x 2875 2876 @item ~/.gnupg/secring.gpg 2877 The secret keyring. You should backup this file. 2878 2879 @item ~/.gnupg/trustdb.gpg 2880 The trust database. There is no need to backup this file; it is better 2881 to backup the ownertrust values (@pxref{option --export-ownertrust}). 2882 2883 @item ~/.gnupg/trustdb.gpg.lock 2884 The lock file for the trust database. 2885 2886 @item ~/.gnupg/random_seed 2887 A file used to preserve the state of the internal random pool. 2888 2889 @item ~/.gnupg/secring.gpg.lock 2890 The lock file for the secret keyring. 2891 2892 @item ~/.gnupg/openpgp-revocs.d/ 2893 This is the directory where gpg stores pre-generated revocation 2894 certificates. The file name corresponds to the OpenPGP fingerprint of 2895 the respective key. It is suggested to backup those certificates and 2896 if the primary private key is not stored on the disk to move them to 2897 an external storage device. Anyone who can access theses files is 2898 able to revoke the corresponding key. You may want to print them out. 2899 You should backup all files in this directory and take care to keep 2900 this backup closed away. 2901 2902 @item /usr[/local]/share/gnupg/options.skel 2903 The skeleton options file. 2904 2905 @item /usr[/local]/lib/gnupg/ 2906 Default location for extensions. 2907 2908@end table 2909 2910@c man:.RE 2911Operation is further controlled by a few environment variables: 2912 2913@table @asis 2914 2915 @item HOME 2916 Used to locate the default home directory. 2917 2918 @item GNUPGHOME 2919 If set directory used instead of "~/.gnupg". 2920 2921 @item GPG_AGENT_INFO 2922 Used to locate the gpg-agent. 2923 This is only honored when @option{--use-agent} is set. 2924 2925 The value consists of 3 colon delimited fields: The first is the path 2926 to the Unix Domain Socket, the second the PID of the gpg-agent and the 2927 protocol version which should be set to 1. When starting the gpg-agent 2928 as described in its documentation, this variable is set to the correct 2929 value. The option @option{--gpg-agent-info} can be used to override it. 2930 2931 @item PINENTRY_USER_DATA 2932 This value is passed via gpg-agent to pinentry. It is useful to convey 2933 extra information to a custom pinentry. 2934 2935 @item COLUMNS 2936 @itemx LINES 2937 Used to size some displays to the full size of the screen. 2938 2939 2940 @item LANGUAGE 2941 Apart from its use by GNU, it is used in the W32 version to override the 2942 language selection done through the Registry. If used and set to a 2943 valid and available language name (@var{langid}), the file with the 2944 translation is loaded from 2945 2946 @code{@var{gpgdir}/gnupg.nls/@var{langid}.mo}. Here @var{gpgdir} is the 2947 directory out of which the gpg binary has been loaded. If it can't be 2948 loaded the Registry is tried and as last resort the native Windows 2949 locale system is used. 2950 2951@end table 2952 2953 2954@c ******************************************* 2955@c *************** **************** 2956@c *************** EXAMPLES **************** 2957@c *************** **************** 2958@c ******************************************* 2959@mansect examples 2960@node GPG Examples 2961@section Examples 2962 2963@table @asis 2964 2965@item gpg -se -r @code{Bob} @code{file} 2966sign and encrypt for user Bob 2967 2968@item gpg --clearsign @code{file} 2969make a clear text signature 2970 2971@item gpg -sb @code{file} 2972make a detached signature 2973 2974@item gpg -u 0x12345678 -sb @code{file} 2975make a detached signature with the key 0x12345678 2976 2977@item gpg --list-keys @code{user_ID} 2978show keys 2979 2980@item gpg --fingerprint @code{user_ID} 2981show fingerprint 2982 2983@item gpg --verify @code{pgpfile} 2984@itemx gpg --verify @code{sigfile} 2985Verify the signature of the file but do not output the data. The 2986second form is used for detached signatures, where @code{sigfile} 2987is the detached signature (either ASCII armored or binary) and 2988are the signed data; if this is not given, the name of 2989the file holding the signed data is constructed by cutting off the 2990extension (".asc" or ".sig") of @code{sigfile} or by asking the 2991user for the filename. 2992@end table 2993 2994 2995@c ******************************************* 2996@c *************** **************** 2997@c *************** USER ID **************** 2998@c *************** **************** 2999@c ******************************************* 3000@mansect how to specify a user id 3001@ifset isman 3002@include specify-user-id.texi 3003@end ifset 3004 3005@mansect return value 3006@chapheading RETURN VALUE 3007 3008The program returns 0 if everything was fine, 1 if at least 3009a signature was bad, and other error codes for fatal errors. 3010 3011@mansect warnings 3012@chapheading WARNINGS 3013 3014Use a *good* password for your user account and a *good* passphrase 3015to protect your secret key. This passphrase is the weakest part of the 3016whole system. Programs to do dictionary attacks on your secret keyring 3017are very easy to write and so you should protect your "~/.gnupg/" 3018directory very well. 3019 3020Keep in mind that, if this program is used over a network (telnet), it 3021is *very* easy to spy out your passphrase! 3022 3023If you are going to verify detached signatures, make sure that the 3024program knows about it; either give both filenames on the command line 3025or use @samp{-} to specify STDIN. 3026 3027@mansect interoperability 3028@chapheading INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS 3029 3030GnuPG tries to be a very flexible implementation of the OpenPGP 3031standard. In particular, GnuPG implements many of the optional parts 3032of the standard, such as the SHA-512 hash, and the ZLIB and BZIP2 3033compression algorithms. It is important to be aware that not all 3034OpenPGP programs implement these optional algorithms and that by 3035forcing their use via the @option{--cipher-algo}, 3036@option{--digest-algo}, @option{--cert-digest-algo}, or 3037@option{--compress-algo} options in GnuPG, it is possible to create a 3038perfectly valid OpenPGP message, but one that cannot be read by the 3039intended recipient. 3040 3041There are dozens of variations of OpenPGP programs available, and each 3042supports a slightly different subset of these optional algorithms. 3043For example, until recently, no (unhacked) version of PGP supported 3044the BLOWFISH cipher algorithm. A message using BLOWFISH simply could 3045not be read by a PGP user. By default, GnuPG uses the standard 3046OpenPGP preferences system that will always do the right thing and 3047create messages that are usable by all recipients, regardless of which 3048OpenPGP program they use. Only override this safe default if you 3049really know what you are doing. 3050 3051If you absolutely must override the safe default, or if the preferences 3052on a given key are invalid for some reason, you are far better off using 3053the @option{--pgp6}, @option{--pgp7}, or @option{--pgp8} options. These 3054options are safe as they do not force any particular algorithms in 3055violation of OpenPGP, but rather reduce the available algorithms to a 3056"PGP-safe" list. 3057 3058@mansect bugs 3059@chapheading BUGS 3060 3061On older systems this program should be installed as setuid(root). This 3062is necessary to lock memory pages. Locking memory pages prevents the 3063operating system from writing memory pages (which may contain 3064passphrases or other sensitive material) to disk. If you get no 3065warning message about insecure memory your operating system supports 3066locking without being root. The program drops root privileges as soon 3067as locked memory is allocated. 3068 3069Note also that some systems (especially laptops) have the ability to 3070``suspend to disk'' (also known as ``safe sleep'' or ``hibernate''). 3071This writes all memory to disk before going into a low power or even 3072powered off mode. Unless measures are taken in the operating system 3073to protect the saved memory, passphrases or other sensitive material 3074may be recoverable from it later. 3075 3076Before you report a bug you should first search the mailing list 3077archives for similar problems and second check whether such a bug has 3078already been reported to our bug tracker at http://bugs.gnupg.org . 3079 3080@c ******************************************* 3081@c *************** ************** 3082@c *************** UNATTENDED ************** 3083@c *************** ************** 3084@c ******************************************* 3085@manpause 3086@node Unattended Usage of GPG 3087@section Unattended Usage 3088 3089@command{gpg} is often used as a backend engine by other software. To help 3090with this a machine interface has been defined to have an unambiguous 3091way to do this. The options @option{--status-fd} and @option{--batch} 3092are almost always required for this. 3093 3094@menu 3095* Unattended GPG key generation:: Unattended key generation 3096@end menu 3097 3098 3099@node Unattended GPG key generation 3100@subsection Unattended key generation 3101 3102The command @option{--gen-key} may be used along with the option 3103@option{--batch} for unattended key generation. The parameters are 3104either read from stdin or given as a file on the command line. 3105The format of the parameter file is as follows: 3106 3107@itemize @bullet 3108 @item Text only, line length is limited to about 1000 characters. 3109 @item UTF-8 encoding must be used to specify non-ASCII characters. 3110 @item Empty lines are ignored. 3111 @item Leading and trailing while space is ignored. 3112 @item A hash sign as the first non white space character indicates 3113 a comment line. 3114 @item Control statements are indicated by a leading percent sign, the 3115 arguments are separated by white space from the keyword. 3116 @item Parameters are specified by a keyword, followed by a colon. Arguments 3117 are separated by white space. 3118 @item 3119 The first parameter must be @samp{Key-Type}; control statements may be 3120 placed anywhere. 3121 @item 3122 The order of the parameters does not matter except for @samp{Key-Type} 3123 which must be the first parameter. The parameters are only used for 3124 the generated keyblock (primary and subkeys); parameters from previous 3125 sets are not used. Some syntactically checks may be performed. 3126 @item 3127 Key generation takes place when either the end of the parameter file 3128 is reached, the next @samp{Key-Type} parameter is encountered or at the 3129 control statement @samp{%commit} is encountered. 3130@end itemize 3131 3132@noindent 3133Control statements: 3134 3135@table @asis 3136 3137@item %echo @var{text} 3138Print @var{text} as diagnostic. 3139 3140@item %dry-run 3141Suppress actual key generation (useful for syntax checking). 3142 3143@item %commit 3144Perform the key generation. Note that an implicit commit is done at 3145the next @asis{Key-Type} parameter. 3146 3147@item %pubring @var{filename} 3148@itemx %secring @var{filename} 3149Do not write the key to the default or commandline given keyring but 3150to @var{filename}. This must be given before the first commit to take 3151place, duplicate specification of the same filename is ignored, the 3152last filename before a commit is used. The filename is used until a 3153new filename is used (at commit points) and all keys are written to 3154that file. If a new filename is given, this file is created (and 3155overwrites an existing one). For GnuPG versions prior to 2.1, both 3156control statements must be given. For GnuPG 2.1 and later 3157@samp{%secring} is a no-op. 3158 3159@item %ask-passphrase 3160@itemx %no-ask-passphrase 3161Enable (or disable) a mode where the command @option{passphrase} is 3162ignored and instead the usual passphrase dialog is used. This does 3163not make sense for batch key generation; however the unattended key 3164generation feature is also used by GUIs and this feature relinquishes 3165the GUI from implementing its own passphrase entry code. These are 3166global control statements and affect all future key genrations. 3167 3168@item %no-protection 3169Since GnuPG version 2.1 it is not anymore possible to specify a 3170passphrase for unattended key generation. The passphrase command is 3171simply ignored and @samp{%ask-passpharse} is thus implicitly enabled. 3172Using this option allows the creation of keys without any passphrase 3173protection. This option is mainly intended for regression tests. 3174 3175@item %transient-key 3176If given the keys are created using a faster and a somewhat less 3177secure random number generator. This option may be used for keys 3178which are only used for a short time and do not require full 3179cryptographic strength. It takes only effect if used together with 3180the control statement @samp{%no-protection}. 3181 3182@end table 3183 3184@noindent 3185General Parameters: 3186 3187@table @asis 3188 3189@item Key-Type: @var{algo} 3190Starts a new parameter block by giving the type of the primary 3191key. The algorithm must be capable of signing. This is a required 3192parameter. @var{algo} may either be an OpenPGP algorithm number or a 3193string with the algorithm name. The special value @samp{default} may 3194be used for @var{algo} to create the default key type; in this case a 3195@samp{Key-Usage} shall not be given and @samp{default} also be used 3196for @samp{Subkey-Type}. 3197 3198@item Key-Length: @var{nbits} 3199The requested length of the generated key in bits. The default is 3200returned by running the command @samp{gpg2 --gpgconf-list}. 3201 3202@item Key-Grip: @var{hexstring} 3203This is optional and used to generate a CSR or certificate for an 3204already existing key. Key-Length will be ignored when given. 3205 3206@item Key-Usage: @var{usage-list} 3207Space or comma delimited list of key usages. Allowed values are 3208@samp{encrypt}, @samp{sign}, and @samp{auth}. This is used to 3209generate the key flags. Please make sure that the algorithm is 3210capable of this usage. Note that OpenPGP requires that all primary 3211keys are capable of certification, so no matter what usage is given 3212here, the @samp{cert} flag will be on. If no @samp{Key-Usage} is 3213specified and the @samp{Key-Type} is not @samp{default}, all allowed 3214usages for that particular algorithm are used; if it is not given but 3215@samp{default} is used the usage will be @samp{sign}. 3216 3217@item Subkey-Type: @var{algo} 3218This generates a secondary key (subkey). Currently only one subkey 3219can be handled. See also @samp{Key-Type} above. 3220 3221@item Subkey-Length: @var{nbits} 3222Length of the secondary key (subkey) in bits. The default is returned 3223by running the command @samp{gpg2 --gpgconf-list}". 3224 3225@item Subkey-Usage: @var{usage-list} 3226Key usage lists for a subkey; similar to @samp{Key-Usage}. 3227 3228@item Passphrase: @var{string} 3229If you want to specify a passphrase for the secret key, 3230enter it here. Default is not to use any passphrase. 3231 3232@item Name-Real: @var{name} 3233@itemx Name-Comment: @var{comment} 3234@itemx Name-Email: @var{email} 3235The three parts of a user name. Remember to use UTF-8 encoding here. 3236If you don't give any of them, no user ID is created. 3237 3238@item Expire-Date: @var{iso-date}|(@var{number}[d|w|m|y]) 3239Set the expiration date for the key (and the subkey). It may either 3240be entered in ISO date format (e.g. "20000815T145012") or as number of 3241days, weeks, month or years after the creation date. The special 3242notation "seconds=N" is also allowed to specify a number of seconds 3243since creation. Without a letter days are assumed. Note that there 3244is no check done on the overflow of the type used by OpenPGP for 3245timestamps. Thus you better make sure that the given value make 3246sense. Although OpenPGP works with time intervals, GnuPG uses an 3247absolute value internally and thus the last year we can represent is 32482105. 3249 3250@item Creation-Date: @var{iso-date} 3251Set the creation date of the key as stored in the key information and 3252which is also part of the fingerprint calculation. Either a date like 3253"1986-04-26" or a full timestamp like "19860426T042640" may be used. 3254The time is considered to be UTC. The special notation "seconds=N" 3255may be used to directly specify a the number of seconds since Epoch 3256(Unix time). If it is not given the current time is used. 3257 3258@item Preferences: @var{string} 3259Set the cipher, hash, and compression preference values for this key. 3260This expects the same type of string as the sub-command @samp{setpref} 3261in the @option{--edit-key} menu. 3262 3263@item Revoker: @var{algo}:@var{fpr} [sensitive] 3264Add a designated revoker to the generated key. Algo is the public key 3265algorithm of the designated revoker (i.e. RSA=1, DSA=17, etc.) 3266@var{fpr} is the fingerprint of the designated revoker. The optional 3267@samp{sensitive} flag marks the designated revoker as sensitive 3268information. Only v4 keys may be designated revokers. 3269 3270@item Keyserver: @var{string} 3271This is an optional parameter that specifies the preferred keyserver 3272URL for the key. 3273 3274@item Handle: @var{string} 3275This is an optional parameter only used with the status lines 3276KEY_CREATED and KEY_NOT_CREATED. @var{string} may be up to 100 3277characters and should not contain spaces. It is useful for batch key 3278generation to associate a key parameter block with a status line. 3279 3280@end table 3281 3282@noindent 3283Here is an example on how to create a key: 3284@smallexample 3285$ cat >foo <<EOF 3286 %echo Generating a basic OpenPGP key 3287 Key-Type: DSA 3288 Key-Length: 1024 3289 Subkey-Type: ELG-E 3290 Subkey-Length: 1024 3291 Name-Real: Joe Tester 3292 Name-Comment: with stupid passphrase 3293 Name-Email: joe@@foo.bar 3294 Expire-Date: 0 3295 Passphrase: abc 3296 %pubring foo.pub 3297 %secring foo.sec 3298 # Do a commit here, so that we can later print "done" :-) 3299 %commit 3300 %echo done 3301EOF 3302$ gpg2 --batch --gen-key foo 3303 [...] 3304$ gpg2 --no-default-keyring --secret-keyring ./foo.sec \ 3305 --keyring ./foo.pub --list-secret-keys 3306/home/wk/work/gnupg-stable/scratch/foo.sec 3307------------------------------------------ 3308sec 1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@@foo.bar> 3309ssb 1024g/8F70E2C0 2000-03-09 3310@end smallexample 3311 3312 3313@noindent 3314If you want to create a key with the default algorithms you would use 3315these parameters: 3316@smallexample 3317 %echo Generating a default key 3318 Key-Type: default 3319 Subkey-Type: default 3320 Name-Real: Joe Tester 3321 Name-Comment: with stupid passphrase 3322 Name-Email: joe@@foo.bar 3323 Expire-Date: 0 3324 Passphrase: abc 3325 %pubring foo.pub 3326 %secring foo.sec 3327 # Do a commit here, so that we can later print "done" :-) 3328 %commit 3329 %echo done 3330@end smallexample 3331 3332 3333 3334 3335@mansect see also 3336@ifset isman 3337@command{gpgv}(1), 3338@end ifset 3339@include see-also-note.texi 3340