From abcd9ea5db1ae9c3d88053127fc7a2d5d798c2d5 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Mon, 1 Jul 2002 08:52:37 +0000 Subject: [PATCH] Better keep it in the CVS --- doc/gpg.texi | 1427 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1427 insertions(+) create mode 100644 doc/gpg.texi diff --git a/doc/gpg.texi b/doc/gpg.texi new file mode 100644 index 000000000..8adcc7bf7 --- /dev/null +++ b/doc/gpg.texi @@ -0,0 +1,1427 @@ +\input texinfo +@c This Texinfo document has been automatically generated by +@c docbook2texi from a DocBook documentation. The tool used +@c can be found at: +@c +@c Please send any bug reports, improvements, comments, +@c patches, etc. to Steve Cheng . + +@setfilename gpg.info +@dircategory GnuPG +@direntry +* gpg: (gpg). GnuPG encryption and signing tool. +@end direntry + +@node top +@top gpg +@menu +@end menu + +@majorheading Name +gpg ---- encryption and signing tool + +@majorheading Synopsis + +@majorheading DESCRIPTION +@code{gpg} is the main program for the GnuPG system. + +This man page only lists the commands and options available. +For more verbose documentation get the GNU Privacy Handbook (GPH) or +one of the other documents at http://www.gnupg.org/docs.html . + +Please remember that option parsing stops as soon as a non option is +encountered, you can explicitly stop option parsing by using the +special option "---". + +@majorheading COMMANDS +@code{gpg} recognizes these commands: + +@table @asis +@item -s, ---sign +Make a signature. This command may be combined +with ---encrypt. + +@item ---clearsign +Make a clear text signature. + +@item -b, ---detach-sign +Make a detached signature. + +@item -e, ---encrypt +Encrypt data. This option may be combined with ---sign. + +@item -c, ---symmetric +Encrypt with symmetric cipher only. +This command asks for a passphrase. + +@item ---store +Store only (make a simple RFC1991 packet). + +@item ---decrypt @code{file} +Decrypt @code{file} (or stdin if no file is specified) and +write it to stdout (or the file specified with +---output). If the decrypted file is signed, the +signature is also verified. This command differs +from the default operation, as it never writes to the +filename which is included in the file and it +rejects files which don't begin with an encrypted +message. + +@item ---verify @code{sigfile} @code{signed-files} +Assume that @code{sigfile} is a signature and verify it +without generating any output. With no arguments, +the signature packet is read from stdin. If +only a sigfile is given, it may be a complete +signature or a detached signature, in which case +the signed stuff is expected in a file without the +".sig" or ".asc" extension. +With more than +1 argument, the first should be a detached signature +and the remaining files are the signed stuff. To read the signed +stuff from stdin, use @samp{-} as the second filename. +For security reasons a detached signature cannot read the signed +material from stdin without denoting it in the above way. + +@item ---verify-files @code{files} +This is a special version of the ---verify command which does not work with +detached signatures. The command expects the files to be verified either +on the command line or reads the filenames from stdin; each name must be on +separate line. The command is intended for quick checking of many files. + +@item ---encrypt-files @code{files} +This is a special version of the ---encrypt command. The command expects +the files to be encrypted either on the command line or reads the filenames +from stdin; each name must be on separate line. The command is intended +for a quick encryption of multiple files. + +@item ---decrypt-files @code{files} +The same as ---encrypt-files with the difference that files will be +decrypted. The syntax or the filenames is the same. + +@item ---list-keys @code{names} +@itemx ---list-public-keys @code{names} +List all keys from the public keyrings, or just the +ones given on the command line. + +@item ---list-secret-keys @code{names} +List all keys from the secret keyrings, or just the +ones given on the command line. + +@item ---list-sigs @code{names} +Same as ---list-keys, but the signatures are listed too. + +@item ---check-sigs @code{names} +Same as ---list-sigs, but the signatures are verified. + +@item ---fingerprint @code{names} +List all keys with their fingerprints. This is the +same output as ---list-keys but with the additional output +of a line with the fingerprint. May also be combined +with ---list-sigs or --check-sigs. +If this command is given twice, the fingerprints of all +secondary keys are listed too. + +@item ---list-packets +List only the sequence of packets. This is mainly +useful for debugging. + +@item ---gen-key +Generate a new key pair. This command is normally only used +interactively. + +There is an experimental feature which allows you to create keys +in batch mode. See the file @file{doc/DETAILS} +in the source distribution on how to use this. + +@item ---edit-key @code{name} +Present a menu which enables you to do all key +related tasks: + +@table @asis +@item sign +Make a signature on key of user @code{name} +If the key is not yet signed by the default +user (or the users given with -u), the +program displays the information of the key +again, together with its fingerprint and +asks whether it should be signed. This +question is repeated for all users specified +with -u. + +@item lsign +Same as ---sign but the signature is marked as +non-exportable and will therefore never be used +by others. This may be used to make keys valid +only in the local environment. + +@item nrsign +Same as ---sign but the signature is marked as non-revocable and can +therefore never be revoked. + +@item nrlsign +Combines the functionality of nrsign and lsign to make a signature +that is both non-revocable and +non-exportable. + +@item revsig +Revoke a signature. GnuPG asks for every +signature which has been done by one of +the secret keys, whether a revocation +certificate should be generated. + +@item trust +Change the owner trust value. This updates the +trust-db immediately and no save is required. + +@item disable +@itemx enable +Disable or enable an entire key. A disabled key can normally not be used +for encryption. + +@item adduid +Create an alternate user id. + +@item addphoto +Create a photographic user id. + +@item deluid +Delete a user id. + +@item addkey +Add a subkey to this key. + +@item delkey +Remove a subkey. + +@item addrevoker +Add a designated revoker. + +@item revkey +Revoke a subkey. + +@item expire +Change the key expiration time. If a key is +selected, the time of this key will be changed. +With no selection the key expiration of the +primary key is changed. + +@item passwd +Change the passphrase of the secret key. + +@item primary +Flag the current user id as the primary one, removes the primary user +id flag from all other user ids and sets the timestamp of all affected +self-signatures one second ahead. Note that setting a photo user ID +as primary makes it primary over other photo user IDs, and setting a +regular user ID as primary makes it primary over other regular user +IDs. + +@item uid @code{n} +Toggle selection of user id with index @code{n}. +Use 0 to deselect all. + +@item key @code{n} +Toggle selection of subkey with index @code{n}. +Use 0 to deselect all. + +@item check +Check all selected user ids. + +@item showphoto +Display the selected photographic user +id. + +@item pref +List preferences. + +@item showpref +More verbose preferences listing. + +@item setpref @code{string} +Set the list of user ID preferences to @code{string}, this should be +a string similar to the one printed by "pref". Using an empty string +will set the default preference string, using "none" will set the +preferences to nil. Only available algorithms are allowed. This +command just initializes an internal list and does not change anything +unless another command which changes the self-signatures is used. + +@item updpref +Change the preferences of all user IDs (or just of the selected ones +to the current list of preferences. The timestamp of all affected +self-signatures fill be advanced by one second. + +@item toggle +Toggle between public and secret key listing. + +@item save +Save all changes to the key rings and quit. + +@item quit +Quit the program without updating the +key rings. + +@end table + +The listing shows you the key with its secondary +keys and all user ids. Selected keys or user ids +are indicated by an asterisk. The trust value is +displayed with the primary key: the first is the +assigned owner trust and the second is the calculated +trust value. Letters are used for the values: + +@table @asis +@item - +No ownertrust assigned / not yet calculated. + +@item e +Trust +calculation has failed; probably due to an expired key. + +@item q +Not enough information for calculation. + +@item n +Never trust this key. + +@item m +Marginally trusted. + +@item f +Fully trusted. + +@item u +Ultimately trusted. + +@end table + +@item ---sign-key @code{name} +Signs a public key with your secret key. This is a shortcut version of +the subcommand "sign" from ---edit. + +@item ---lsign-key @code{name} +Signs a public key with your secret key but marks it as +non-exportable. This is a shortcut version of the subcommand "lsign" +from ---edit. + +@item ---nrsign-key @code{name} +Signs a public key with your secret key but marks it as non-revocable. +This is a shortcut version of the subcommand "nrsign" from ---edit. + +@item ---delete-key @code{name} +Remove key from the public keyring + +@item ---delete-secret-key @code{name} +Remove key from the secret and public keyring + +@item ---delete-secret-and-public-key @code{name} +Same as ---delete-key, but if a secret key exists, it will be removed first. + +@item ---gen-revoke +Generate a revocation certificate for the complete key. To revoke +a subkey or a signature, use the ---edit command. + +@item ---desig-revoke +Generate a designated revocation certificate for a key. This allows a +user (with the permission of the keyholder) to revoke someone elses +key. + +@item ---export @code{names} +Either export all keys from all keyrings (default +keyrings and those registered via option ---keyring), +or if at least one name is given, those of the given +name. The new keyring is written to stdout or to +the file given with option "output". Use together +with ---armor to mail those keys. + +@item ---send-keys @code{names} +Same as ---export but sends the keys to a keyserver. +Option ---keyserver must be used to give the name +of this keyserver. Don't send your complete keyring +to a keyserver - select only those keys which are new +or changed by you. + +@item ---export-all @code{names} +Same as ---export, but also exports keys which +are not compatible with OpenPGP. + +@item ---export-secret-keys @code{names} +@itemx ---export-secret-subkeys @code{names} +Same as ---export, but exports the secret keys instead. +This is normally not very useful and a security risk. +The second form of the command has the special property to +render the secret part of the primary key useless; this is +a GNU extension to OpenPGP and other implementations can +not be expected to successfully import such a key. +See the option ---simple-sk-checksum if you want to import such an +exported key with an older OpenPGP implementation. + +@item ---import @code{files} +@itemx ---fast-import @code{files} +Import/merge keys. This adds the given keys to the +keyring. The fast version is currently just a synonym. + +There are a few other options which control how this command works. +Most notable here is the ---merge-only option which does not insert new keys +but does only the merging of new signatures, user-IDs and subkeys. + +@item ---recv-keys @code{key IDs} +Import the keys with the given key IDs from a keyserver. Option +---keyserver must be used to give the name of this keyserver. + +@item ---search-keys @code{names} +Search the keyserver for the given names. Multiple names given here +will be joined together to create the search string for the keyserver. +Option ---keyserver must be used to give the name of this keyserver. + +@item ---update-trustdb +Do trust DB maintenance. This command goes over all keys and builds +the Web-of-Trust. This is an interactive command because it may has to +ask for the "ownertrust" values of keys. The user has to give an +estimation in how far she trusts the owner of the displayed key to +correctly certify (sign) other keys. It does only ask for that value +if it has not yet been assigned to a key. Using the edit menu, that +value can be changed at any time later. + +@item ---check-trustdb +Do trust DB maintenance without user interaction. Form time to time +the trust database must be updated so that expired keys and resulting +changes in the Web-of-Trust can be tracked. GnuPG tries to figure +when this is required and then does it implicitly; this command can be +used to force such a check. The processing is identically to that of +---update-trustdb but it skips keys with a not yet defined "ownertrust". + +For use with cron jobs, this command can be used together with ---batch +in which case the check is only done when it is due. To force a run +even in batch mode add the option ---yes. + +@item ---export-ownertrust @code{file} +Store the ownertrust values into +@code{file} (or stdin if not given). This is useful for backup +purposes as these values are the only ones which can't be re-created +from a corrupted trust DB. + +@item ---import-ownertrust @code{files} +Update the trustdb with the ownertrust values stored +in @code{files} (or stdin if not given); existing +values will be overwritten. + +@item ---print-md @code{algo} @code{files} +@itemx ---print-mds @code{files} +Print message digest of algorithm ALGO for all given files or stdin. +With the second form (or a deprecated "*" as algo) digests for all +available algorithms are printed. + +@item ---gen-random @code{0|1|2} @code{count} +Emit COUNT random bytes of the given quality level. If count is not given +or zero, an endless sequence of random bytes will be emitted. +PLEASE, don't use this command unless you know what you are doing; it may +remove precious entropy from the system! + +@item ---gen-prime @code{mode} @code{bits} @code{qbits} +Use the source, Luke :-). The output format is still subject to change. + +@item ---version +Print version information along with a list +of supported algorithms. + +@item ---warranty +Print warranty information. + +@item -h, ---help +Print usage information. This is a really long list even though it doesn't list +all options. + +@end table + +@majorheading OPTIONS +Long options can be put in an options file (default "~/.gnupg/options"). +Do not write the 2 dashes, but simply the name of the option and any +required arguments. Lines with a hash as the first non-white-space +character are ignored. Commands may be put in this file too, but that +does not make sense. + +@code{gpg} recognizes these options: + +@table @asis +@item -a, ---armor +Create ASCII armored output. + +@item -o, ---output @code{file} +Write output to @code{file}. + +@item -u, ---local-user @code{name} +Use @code{name} as the user ID to sign. +This option is silently ignored for the list commands, +so that it can be used in an options file. + +@item ---default-key @code{name} +Use @code{name} as default user ID for signatures. If this +is not used the default user ID is the first user ID +found in the secret keyring. + +@item -r, ---recipient @code{name} +@itemx +Encrypt for user id @code{name}. If this option is not +specified, GnuPG asks for the user-id unless ---default-recipient is given + +@item ---default-recipient @code{name} +Use @code{name} as default recipient if option ---recipient is not used and +don't ask if this is a valid one. @code{name} must be non-empty. + +@item ---default-recipient-self +Use the default key as default recipient if option ---recipient is not used and +don't ask if this is a valid one. The default key is the first one from the +secret keyring or the one set with ---default-key. + +@item ---no-default-recipient +Reset ---default-recipient and --default-recipient-self. + +@item ---encrypt-to @code{name} +Same as ---recipient but this one is intended for use +in the options file and may be used with +your own user-id as an "encrypt-to-self". These keys +are only used when there are other recipients given +either by use of ---recipient or by the asked user id. +No trust checking is performed for these user ids and +even disabled keys can be used. + +@item ---no-encrypt-to +Disable the use of all ---encrypt-to keys. + +@item -v, ---verbose +Give more information during processing. If used +twice, the input data is listed in detail. + +@item -q, ---quiet +Try to be as quiet as possible. + +@item -z @code{n}, ---compress @code{n} +Set compression level to @code{n}. A value of 0 for @code{n} +disables compression. Default is to use the default +compression level of zlib (normally 6). + +@item -t, ---textmode +Use canonical text mode. If -t (but not +---textmode) is used together with armoring +and signing, this enables clearsigned messages. +This kludge is needed for PGP compatibility; +normally you would use ---sign or --clearsign +to selected the type of the signature. + +@item -n, ---dry-run +Don't make any changes (this is not completely implemented). + +@item -i, ---interactive +Prompt before overwriting any files. + +@item ---batch +Use batch mode. Never ask, do not allow interactive +commands. + +@item ---no-tty +Make sure that the TTY (terminal) is never used for any output. +This option is needed in some cases because GnuPG sometimes prints +warnings to the TTY if ---batch is used. + +@item ---no-batch +Disable batch mode. This may be of use if ---batch +is enabled from an options file. + +@item ---yes +Assume "yes" on most questions. + +@item ---no +Assume "no" on most questions. + +@item ---default-cert-check-level @code{n} +The default to use for the check level when signing a key. + +0 means you make no particular claim as to how carefully you verified +the key. + +1 means you believe the key is owned by the person who claims to own +it but you could not, or did not verify the key at all. This is +useful for a "persona" verification, where you sign the key of a +pseudonymous user. + +2 means you did casual verification of the key. For example, this +could mean that you verified that the key fingerprint and checked the +user ID on the key against a photo ID. + +3 means you did extensive verification of the key. For example, this +could mean that you verified the key fingerprint with the owner of the +key in person, and that you checked, by means of a hard to forge +document with a photo ID (such as a passport) that the name of the key +owner matches the name in the user ID on the key, and finally that you +verified (by exchange of email) that the email address on the key +belongs to the key owner. + +Note that the examples given above for levels 2 and 3 are just that: +examples. In the end, it is up to you to decide just what "casual" +and "extensive" mean to you. + +This option defaults to 0. + +@item ---trusted-key @code{long key ID} +Assume that the specified key (which must be given +as a full 8 byte key ID) is as trustworthy as one of +your own secret keys. This option is useful if you +don't want to keep your secret keys (or one of them) +online but still want to be able to check the validity of a given +recipient's or signator's key. + +@item ---always-trust +Skip key validation and assume that used keys are always fully trusted. +You won't use this unless you have installed some external validation +scheme. This option also suppresses the "[uncertain]" tag printed +with signature checks when there is no evidence that the user ID +is bound to the key. + +@item ---keyserver @code{name} +Use @code{name} as your keyserver. This is the server that ---recv-keys, +---send-keys, and --search-keys will communicate with to receive keys +from, send keys to, and search for keys on. The format of the +@code{name} is a URI: `scheme:[//]keyservername[:port]' The scheme is +the type of keyserver: "hkp" for the Horowitz (or compatible) +keyservers, "ldap" for the NAI LDAP keyserver, or "mailto" for the +Horowitz email keyserver. Note that your particular installation of +GnuPG may have other keyserver types available as well. + +Most keyservers synchronize with each other, so there is generally no +need to send keys to more than one server. Using the command "host -l +pgp.net | grep wwwkeys" gives you a list of HKP keyservers. When +using one of the wwwkeys servers, due to load balancing using +round-robin DNS you may notice that you get a different key server +each time. + +@item ---keyserver-options @code{parameters} +This is a space or comma delimited string that gives options for the +keyserver. Options can be prepended with a `no-' to give the opposite +meaning. While not all options are available for all keyserver types, +some common options are: + +@table @asis +@item include-revoked +When receiving or searching for a key, include keys that are marked on +the keyserver as revoked. Note that this option is always set when +using the NAI HKP keyserver, as this keyserver does not differentiate +between revoked and unrevoked keys. + +@item include-disabled +When receiving or searching for a key, include keys that are marked on +the keyserver as disabled. Note that this option is not used with HKP +keyservers, as they do not support disabling keys. + +@item use-temp-files +On most Unix-like platforms, GnuPG communicates with the keyserver +helper program via pipes, which is the most efficient method. This +option forces GnuPG to use temporary files to communicate. On some +platforms (such as Win32 and RISC OS), this option is always enabled. + +@item keep-temp-files +If using `use-temp-files', do not delete the temp files after using +them. This option is useful to learn the keyserver communication +protocol by reading the temporary files. + +@item verbose +Tell the keyserver helper program to be more verbose. This option can +be repeated multiple times to increase the verbosity level. + +@item honor-http-proxy +For keyserver schemes that use HTTP (such as HKP), try to access the +keyserver over the proxy set with the environment variable +"http_proxy". + +@item auto-key-retrieve +This option enables the automatic retrieving of keys from a keyserver +when verifying signatures made by keys that are not on the local +keyring. + +@end table + +@item ---show-photos +Causes ---list-keys, --list-sigs, --list-public-keys, and +---list-secret-keys to also display the photo ID attached to a key, if +any. +See also ---photo-viewer. + +@item ---no-show-photos +Resets the ---show-photos flag. + +@item ---photo-viewer @code{string} +This is the command line that should be run to view a photo ID. "%i" +will be expanded to a filename containing the photo. "%I" does the +same, except the file will not be deleted once the viewer exits. +Other flags are "%k" for the key ID, "%K" for the long key ID, "%f" +for the key fingerprint, "%t" for the extension of the image type +(e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"), +and "%%" for an actual percent sign. If neither %i or %I are present, +then the photo will be supplied to the viewer on standard input. + +The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k' +stdin" + +@item ---show-keyring +Causes ---list-keys, --list-public-keys, and --list-secret-keys to +display the name of the keyring a given key resides on. This is only +useful when you're listing a specific key or set of keys. It has no +effect when listing all keys. + +@item ---keyring @code{file} +Add @code{file} to the list of keyrings. +If @code{file} begins with a tilde and a slash, these +are replaced by the HOME directory. If the filename +does not contain a slash, it is assumed to be in the +home-directory ("~/.gnupg" if ---homedir is not used). +The filename may be prefixed with a scheme: + +"gnupg-ring:" is the default one. + +It might make sense to use it together with ---no-default-keyring. + +@item ---secret-keyring @code{file} +Same as ---keyring but for the secret keyrings. + +@item ---homedir @code{directory} +Set the name of the home directory to @code{directory} If this +option is not used it defaults to "~/.gnupg". It does +not make sense to use this in a options file. This +also overrides the environment variable "GNUPGHOME". + +@item ---charset @code{name} +Set the name of the native character set. This is used +to convert some strings to proper UTF-8 encoding. +Valid values for @code{name} are: + +@table @asis +@item iso-8859-1 +This is the default Latin 1 set. + +@item iso-8859-2 +The Latin 2 set. + +@item koi8-r +The usual Russian set (rfc1489). + +@item utf-8 +Bypass all translations and assume +that the OS uses native UTF-8 encoding. + +@end table + +@item ---utf8-strings +@itemx ---no-utf8-strings +Assume that the arguments are already given as UTF8 strings. The default +(---no-utf8-strings) +is to assume that arguments are encoded in the character set as specified +by ---charset. These options affect all following arguments. Both options may +be used multiple times. + +@item ---options @code{file} +Read options from @code{file} and do not try to read +them from the default options file in the homedir +(see ---homedir). This option is ignored if used +in an options file. + +@item ---no-options +Shortcut for "---options /dev/null". This option is +detected before an attempt to open an option file. +Using this option will also prevent the creation of a +"~./gnupg" homedir. + +@item ---load-extension @code{name} +Load an extension module. If @code{name} does not +contain a slash it is searched in "/usr/local/lib/gnupg" +See the manual for more information about extensions. + +@item ---debug @code{flags} +Set debugging flags. All flags are or-ed and @code{flags} may +be given in C syntax (e.g. 0x0042). + +@item ---debug-all +Set all useful debugging flags. + +@item ---status-fd @code{n} +Write special status strings to the file descriptor @code{n}. +See the file DETAILS in the documentation for a listing of them. + +@item ---logger-fd @code{n} +Write log output to file descriptor @code{n} and not to stderr. + +@item ---attribute-fd @code{n} +Write attribute subpackets to the file descriptor @code{n}. This is +most useful for use with ---status-fd, since the status messages are +needed to separate out the various subpackets from the stream +delivered to the file descriptor. + +@item ---sk-comments +Include secret key comment packets when exporting secret keys. This +is a GnuPG extension to the OpenPGP standard, and is off by default. +Please note that this has nothing to do with the comments in clear +text signatures or armor headers. + +@item ---no-sk-comments +Resets the ---sk-comments option. + +@item ---no-comment +See ---sk-comments. This option is deprecated and may be removed soon. + +@item ---comment @code{string} +Use @code{string} as comment string in clear text signatures. +The default is not do write a comment string. + +@item ---default-comment +Force to write the standard comment string in clear +text signatures. Use this to overwrite a ---comment +from a config file. This option is now obsolete because there is no +default comment string anymore. + +@item ---no-version +Omit the version string in clear text signatures. + +@item ---emit-version +Force to write the version string in clear text +signatures. Use this to overwrite a previous +---no-version from a config file. + +@item -N, ---notation-data @code{name=value} +Put the name value pair into the signature as notation data. +@code{name} must consist only of alphanumeric characters, digits +or the underscore; the first character must not be a digit. +@code{value} may be any printable string; it will be encoded in UTF8, +so you should check that your ---charset is set correctly. +If you prefix @code{name} with an exclamation mark, the notation +data will be flagged as critical (rfc2440:5.2.3.15). + +@item ---show-notation +Show key signature notations in the ---list-sigs or --check-sigs +listings. + +@item ---no-show-notation +Do not show key signature notations in the ---list-sigs or --check-sigs +listings. + +@item ---set-policy-url @code{string} +Use @code{string} as Policy URL for signatures (rfc2440:5.2.3.19). +If you prefix it with an exclamation mark, the policy URL +packet will be flagged as critical. + +@item ---show-policy-url +Show any policy URLs set in the ---list-sigs or --check-sigs listings. + +@item ---no-show-policy-url +Do not show any policy URLs set in the ---list-sigs or --check-sigs +listings. + +@item ---set-filename @code{string} +Use @code{string} as the name of file which is stored in +messages. + +@item ---for-your-eyes-only +Set the `for your eyes only' flag in the message. This causes GnuPG +to refuse to save the file unless the ---output option is given, and +PGP to use the "secure viewer" with a Tempest-resistant font to +display the message. This option overrides ---set-filename. + +@item ---no-for-your-eyes-only +Resets the ---for-your-eyes-only flag. + +@item ---use-embedded-filename +Try to create a file with a name as embedded in the data. +This can be a dangerous option as it allows to overwrite files. + +@item ---completes-needed @code{n} +Number of completely trusted users to introduce a new +key signer (defaults to 1). + +@item ---marginals-needed @code{n} +Number of marginally trusted users to introduce a new +key signer (defaults to 3) + +@item ---max-cert-depth @code{n} +Maximum depth of a certification chain (default is 5). + +@item ---cipher-algo @code{name} +Use @code{name} as cipher algorithm. Running the program +with the command ---version yields a list of supported +algorithms. If this is not used the cipher algorithm is +selected from the preferences stored with the key. + +@item ---digest-algo @code{name} +Use @code{name} as the message digest algorithm. Running the program +with the command ---version yields a list of supported algorithms. + +@item ---cert-digest-algo @code{name} +Use @code{name} as the message digest algorithm used when signing a +key. Running the program with the command ---version yields a list of +supported algorithms. Be aware that if you choose an algorithm that +GnuPG supports but other OpenPGP implementations do not, then some +users will not be able to use the key signatures you make, or quite +possibly your entire key. + +@item ---s2k-cipher-algo @code{name} +Use @code{name} as the cipher algorithm used to protect secret keys. +The default cipher is CAST5. This cipher is also used for +conventional encryption if ---cipher-algo is not given. + +@item ---s2k-digest-algo @code{name} +Use @code{name} as the digest algorithm used to mangle the +passphrases. The default algorithm is RIPE-MD-160. +This digest algorithm is also used for conventional +encryption if ---digest-algo is not given. + +@item ---s2k-mode @code{n} +Selects how passphrases are mangled. If @code{n} is 0 +a plain passphrase (which is not recommended) will be used, +a 1 (default) adds a salt to the passphrase and +a 3 iterates the whole process a couple of times. +Unless ---rfc1991 is used, this mode is also used +for conventional encryption. + +@item ---simple-sk-checksum +Secret keys are integrity protected by using a SHA-1 checksum. This +method will be part of an enhanced OpenPGP specification but GnuPG +already uses it as a countermeasure against certain attacks. Old +applications don't understand this new format, so this option may be +used to switch back to the old behaviour. Using this this option +bears a security risk. + +@item ---compress-algo @code{n} +Use compression algorithm @code{n}. Default is 2 which is RFC1950 +compression. You may use 1 to use the old zlib version (RFC1951) which +is used by PGP. 0 disables compression. The default algorithm may give +better results because the window size is not limited to 8K. If this +is not used the OpenPGP behavior is used, i.e. the compression +algorithm is selected from the preferences; note, that this can't be +done if you do not encrypt the data. + +@item ---disable-cipher-algo @code{name} +Never allow the use of @code{name} as cipher algorithm. +The given name will not be checked so that a later loaded algorithm +will still get disabled. + +@item ---disable-pubkey-algo @code{name} +Never allow the use of @code{name} as public key algorithm. +The given name will not be checked so that a later loaded algorithm +will still get disabled. + +@item ---no-sig-cache +Do not cache the verification status of key signatures. +Caching gives a much better performance in key listings. However, if +you suspect that your public keyring is not save against write +modifications, you can use this option to disable the caching. It +probably does not make sense to disable it because all kind of damage +can be done if someone else has write access to your public keyring. + +@item ---no-sig-create-check +GnuPG normally verifies each signature right after creation to protect +against bugs and hardware malfunctions which could leak out bits from +the secret key. This extra verification needs some time (about 115% +for DSA keys), and so this option can be used to disable it. +However, due to the fact that the signature creation needs manual +interaction, this performance penalty does not matter in most settings. + +@item ---auto-check-trustdb +If GnuPG feels that its information about the Web-of-Trust has to be +updated, it automatically runs the ---check-trustdb command +internally. This may be a time consuming process. + +@item ---no-auto-check-trustdb +Resets the ---auto-check-trustdb option. + +@item ---throw-keyid +Do not put the keyid into encrypted packets. This option +hides the receiver of the message and is a countermeasure +against traffic analysis. It may slow down the decryption +process because all available secret keys are tried. + +@item ---not-dash-escaped +This option changes the behavior of cleartext signatures +so that they can be used for patch files. You should not +send such an armored file via email because all spaces +and line endings are hashed too. You can not use this +option for data which has 5 dashes at the beginning of a +line, patch files don't have this. A special armor header +line tells GnuPG about this cleartext signature option. + +@item ---escape-from-lines +Because some mailers change lines starting with "From " +to " +Using an exact to match string. The equal sign indicates this. + +@item +Using the email address part which must match exactly. The left angle bracket +indicates this email address mode. + +@item +Heinrich Heine duesseldorf +All words must match exactly (not case sensitive) but can appear in +any order in the user ID. Words are any sequences of letters, +digits, the underscore and all characters with bit 7 set. + +@item Heine +@itemx *Heine +By case insensitive substring matching. This is the default mode but +applications may want to explicitly indicate this by putting the asterisk +in front. + +@end table + +Note that you can append an exclamation mark to key IDs or +fingerprints. This flag tells GnuPG to use exactly the given primary +or secondary key and not to try to figure out which secondary or +primary key to use. + +@majorheading RETURN VALUE +The program returns 0 if everything was fine, 1 if at least +a signature was bad, and other error codes for fatal errors. + +@majorheading EXAMPLES +@table @asis +@item gpg -se -r @code{Bob} @code{file} +sign and encrypt for user Bob + +@item gpg ---clearsign @code{file} +make a clear text signature + +@item gpg -sb @code{file} +make a detached signature + +@item gpg ---list-keys @code{user_ID} +show keys + +@item gpg ---fingerprint @code{user_ID} +show fingerprint + +@item gpg ---verify @code{pgpfile} +@itemx gpg ---verify @code{sigfile} @code{files} +Verify the signature of the file but do not output the data. The second form +is used for detached signatures, where @code{sigfile} is the detached +signature (either ASCII armored of binary) and @code{files} are the signed +data; if this is not given the name of the file holding the signed data is +constructed by cutting off the extension (".asc" or ".sig") of +@code{sigfile} or by asking the user for the filename. + +@end table + +@majorheading ENVIRONMENT +@table @asis +@item HOME +Used to locate the default home directory. + +@item GNUPGHOME +If set directory used instead of "~/.gnupg". + +@item GPG_AGENT_INFO +Used to locate the gpg-agent; only honored when +---use-agent is set. The value consists of 3 colon delimited fields: +The first is the path to the Unix Domain Socket, the second the PID of +the gpg-agent and the protocol version which should be set to 1. When +starting the gpg-agent as described in its documentation, this +variable is set to the correct value. The option ---gpg-agent-info can +be used to overide it. + +@item http_proxy +Only honored when the option ---honor-http-proxy is set. + +@end table + +@majorheading FILES +@table @asis +@item ~/.gnupg/secring.gpg +The secret keyring + +@item ~/.gnupg/secring.gpg.lock +and the lock file + +@item ~/.gnupg/pubring.gpg +The public keyring + +@item ~/.gnupg/pubring.gpg.lock +and the lock file + +@item ~/.gnupg/trustdb.gpg +The trust database + +@item ~/.gnupg/trustdb.gpg.lock +and the lock file + +@item ~/.gnupg/random_seed +used to preserve the internal random pool + +@item ~/.gnupg/options +May contain options + +@item /usr[/local]/share/gnupg/options.skel +Skeleton options file + +@item /usr[/local]/lib/gnupg/ +Default location for extensions + +@end table + +@majorheading WARNINGS +Use a *good* password for your user account and a *good* passphrase +to protect your secret key. This passphrase is the weakest part of the +whole system. Programs to do dictionary attacks on your secret keyring +are very easy to write and so you should protect your "~/.gnupg/" +directory very well. + +Keep in mind that, if this program is used over a network (telnet), it +is *very* easy to spy out your passphrase! + +If you are going to verify detached signatures, make sure that the +program knows about it; either be giving both filenames on the +commandline or using @samp{-} to specify stdin. + +@majorheading BUGS +On many systems this program should be installed as setuid(root). This +is necessary to lock memory pages. Locking memory pages prevents the +operating system from writing memory pages to disk. If you get no +warning message about insecure memory your operating system supports +locking without being root. The program drops root privileges as soon +as locked memory is allocated. + +@bye