diff --git a/web/documentation/manpage.org b/web/documentation/manpage.org new file mode 100644 index 0000000..de5dcab --- /dev/null +++ b/web/documentation/manpage.org @@ -0,0 +1,795 @@ +#+TITLE: GnuPG - gpg man page +#+STARTUP: showall +#+SETUPFILE: "../share/setup.inc" +#+OPTIONS: -:nil + +* Old Man Page + +This is a very old version of the gpg man page. Please see the latest +release or software package for your operating system to find an up to +date version ("man gpg2"). + +* gpg + +** Name + +gpg -- encryption and signing tool + +** Synopsis + +#+BEGIN_EXAMPLE + gpg + [--homedir name] + [--options file] + [options] + command + [args] + +#+END_EXAMPLE + +** DESCRIPTION + +*gpg* is the main program for the GnuPG system. + +This man page does only list the commands and options available. For a +more verbose documentation get the GNU Privacy Handbook (GPH), which is +available at https://www.gnupg.org/gph/ . You will find a list of HOWTO +documents at https://www.gnupg.org/docs.html . + +** COMMANDS + +*gpg* recognizes these commands: + +- -s, --sign :: Make a signature. This command may be combined with + --encrypt. + +- --clearsign :: Make a clear text signature. + +- -b, --detach-sign :: Make a detached signature. + +- -e, --encrypt :: Encrypt data. This option may be combined with + --sign. + +- -c, --symmetric :: Encrypt with symmetric cipher only This command + asks for a passphrase. + +- --store :: Store only (make a simple RFC1991 packet). + +- --decrypt [ =file= ] :: Decrypt =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. + +- --verify [[ =sigfile= ] [ =signed-files= ]] :: Assume that =sigfile= is a + signature and verify it without generating any output. With no + arguments, the signature packet is read from stdin (it may be a + detached signature when not used in batch mode). 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 (if such a file does not exist it is expected at + stdin; use a single dash ("-") as filename to force a read from + stdin). With more than 1 argument, the first should be a detached + signature and the remaining files are the signed stuff. + +- --verify-files [ =files= ] :: This is a special version of the --verify + command which does not work with detached signatures. The command + expects the files to bee verified either on the commandline or reads + the filenames from stdin; each anem muts be on separate line. The + command is intended for quick checking of many files. + +- --list-keys [ =names= ], --list-public-keys [ =names= ] :: List all keys + from the public keyrings, or just the ones given on the command line. + +- --list-secret-keys [ =names= ] :: List all keys from the secret + keyrings, or just the ones given on the command line. + +- --list-sigs [ =names= ] :: Same as --list-keys, but the signatures are + listed too. + +- --check-sigs [ =names= ] :: Same as --list-sigs, but the signatures are + verified. + +- --fingerprint [ =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. + +- --list-packets :: List only the sequence of packets. This is mainly + useful for debugging. + +- --gen-key :: Generate a new key pair. This command is normally only + used interactive. + + There is an experimental feature which allows to create keys in batch + mode. See the file =doc/DETAILS= in the source distribution on how to + use this. + +- --edit-key =name= :: Present a menu which enables you to do all key + related tasks: + + - sign :: Make a signature on key of user =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. + + - 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. + + - 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. + + - trust :: Change the owner trust value. This updates the trust-db + immediately and no save is required. + + - disable, enable :: Disable or enable an entire key. A disabled key + can normally not be used for encryption. + + - adduid :: Create an alternate user id. + + - deluid :: Delete an user id. + + - addkey :: Add a subkey to this key. + + - delkey :: Remove a subkey. + + - revkey :: Revoke a subkey. + + - 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. + + - passwd :: Change the passphrase of the secret key. + + - uid =n= :: Toggle selection of user id with index =n=. Use 0 to + deselect all. + + - key =n= :: Toggle selection of subkey with index =n=. Use 0 to + deselect all. + + - check :: Check all selected user ids. + + - pref :: List preferences. + + - toggle :: Toggle between public and secret key listing. + + - save :: Save all changes to the key rings and quit. + + - quit :: Quit the program without updating the key rings. + + 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: + + - - :: No ownertrust assigned / not yet calculated. + + - e :: Trust calculation has failed. + + - q :: Not enough information for calculation. + + - n :: Never trust this key. + + - m :: Marginally trusted. + + - f :: Fully trusted. + + - u :: Ultimately trusted. + +- --sign-key =name= :: Sign a public key with you secret key. This is a + shortcut version of the subcommand "sign" from --edit. + +- --lsign-key =name= :: Sign a public key with you secret key but mark + it as non-exportable. This is a shortcut version of the subcommand + "lsign" from --edit. + +- --trusted-key =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 be able to check + the validity of a given recipient's or signator's key. + +- --delete-key =name= :: Remove key from the public keyring + +- --delete-secret-key =name= :: Remove key from the secret and public + keyring + +- --gen-revoke :: Generate a revocation certificate for the complete + key. To revoke a subkey or a signature, use the --edit command. + +- --export [ =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. + +- --send-keys [ =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. + +- --export-all [ =names= ] :: Same as --export, but does also export keys + which are not compatible to OpenPGP. + +- --export-secret-keys [ =names= ], --export-secret-subkeys + [ =names= ] :: Same as --export, but does export the secret keys. 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 successful import such a key. + +- --import [ =files= ], --fast-import [ =files= ] :: Import/merge keys. + This adds the given keys to the keyring. The fast version does not + build the trustdb; this can be done at any time with the command + --update-trustdb. + + There are a few other options which control how this command works. + Most notable here is the --merge-only options which does not insert + new keys but does only the merging of new signatures, user-IDs and + subkeys. + +- --recv-keys =key IDs= :: Import the keys with the given key IDs from + a HKP keyserver. Option --keyserver must be used to give the name of + this keyserver. + +- --export-ownertrust :: List the assigned ownertrust values in ASCII + format for backup purposes + +- --import-ownertrust [ =files= ] :: Update the trustdb with the + ownertrust values stored in =files= (or stdin if not given); existing + values will be overwritten. + +- --print-md =algo= [ =files= ] :: Print message digest of algorithm ALGO + for all given files of stdin. If "*" is used for the algorithm, + digests for all available algorithms are printed. + +- --gen-random =0|1|2= [ =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! + +- --gen-prime =mode= =bits= [ =qbits= ] :: Use the source, Luke :-). The + output format is still subject to change. + +- --version :: Print version information along with a list of supported + algorithms. + +- --warranty :: Print warranty information. + +- -h, --help :: Print usage information. This is a really long list + even it does list not all options. + +** 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. + +*gpg* recognizes these options: + +- -a, --armor :: Create ASCII armored output. + +- -o, --output =file= :: Write output to =file=. + +- -u, --local-user =name= :: Use =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. + +- --default-key =name= :: Use =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. + +- -r, --recipient =name=, :: Encrypt for user id =name=. If this + option is not specified, GnuPG asks for the user-id unless + --default-recipient is given + +- --default-recipient =name= :: Use =name= as default recipient if + option --recipient is not used and don't ask if this is a valid one. + =name= must be a non empty. + +- --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. + +- --no-default-recipient :: Reset --default-recipient and + --default-recipient-self. + +- --encrypt-to =name= :: Same as --recipient but this one is intended + for in the options file and may be used together with an 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. + +- --no-encrypt-to :: Disable the use of all --encrypt-to keys. + +- -v, --verbose :: Give more information during processing. If used + twice, the input data is listed in detail. + +- -q, --quiet :: Try to be as quiet as possible. + +- -z =n= :: Set compression level to =n=. A value of 0 for =n= disables + compression. Default is to use the default compression level of zlib + (normally 6). + +- -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. + +- -n, --dry-run :: Don't make any changes (this is not completely + implemented). + +- -i, --interactive :: Prompt before overwriting any files. + +- --batch :: Use batch mode. Never ask, do not allow interactive + commands. + +- --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 if --batch is used. + +- --no-batch :: Disable batch mode. This may be of use if --batch is + enabled from an options file. + +- --yes :: Assume "yes" on most questions. + +- --no :: Assume "no" on most questions. + +- --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. + +- --keyserver =name= :: Use =name= to lookup keys which are not yet in + your keyring. This is only done while verifying messages with + signatures. The option is also required for the command --send-keys + to specify the keyserver to where the keys should be send. All + keyservers synchronize with each other - so there is no need to send + keys to more than one server. Using the command "host -l pgp.net | + grep wwwkeys" gives you a list of keyservers. Because there is load + balancing using round-robin DNS you may notice that you get different + key servers. + +- --no-auto-key-retrieve :: This option disables the automatic + retrieving of keys from a keyserver while verifying signatures. This + option allows to keep a keyserver in the options file or the + --send-keys and --recv-keys commands. + +- --honor-http-proxy :: Try to access the keyserver over the proxy set + with the variable "http\_proxy". + +- --keyring =file= :: Add =file= to the list of keyrings. If =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. + + "gnupg-gdbm:" may be used for a GDBM ring. Note that GDBM is + experimental and likely to be removed in future versions. + + It might make sense to use it together with --no-default-keyring. + +- --secret-keyring =file= :: Same as --keyring but for the secret + keyrings. + +- --homedir =directory= :: Set the name of the home directory to + =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". + +- --charset =name= :: Set the name of the native character set. This is + used to convert some strings to proper UTF-8 encoding. Valid values + for =name= are: + + - iso-8859-1 :: This is the default Latin 1 set. + + - iso-8859-2 :: The Latin 2 set. + + - koi8-r :: The usual Russian set (rfc1489). + +- --utf8-strings, --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 effects all following arguments. Both + options may used multiple times. + +- --options =file= :: Read options from =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. + +- --no-options :: Shortcut for "--options /dev/null". This option is + detected before an attempt to open an option file. + +- --load-extension =name= :: Load an extension module. If =name= does + not contain a slash it is searched in "/usr/local/lib/gnupg" See the + manual for more information about extensions. + +- --debug =flags= :: Set debugging flags. All flags are or-ed and + =flags= may be given in C syntax (e.g. 0x0042). + +- --debug-all :: Set all useful debugging flags. + +- --status-fd =n= :: Write special status strings to the file + descriptor =n=. See the file DETAILS in the documentation for a + listing of them. + +- --logger-fd =n= :: Write log output to file descriptor =n= and not to + stderr. + +- --no-comment :: Do not write comment packets. This option affects + only the generation of secret keys. Please note, that this has + nothing to do with the comments in clear text signatures. + +- --comment =string= :: Use =string= as comment string in clear text + signatures. To suppress those comment strings entirely, use an empty + string here. + +- --default-comment :: Force to write the standard comment string in + clear text signatures. Use this to overwrite a --comment from a + config file. + +- --no-version :: Omit the version string in clear text signatures. + +- --emit-version :: Force to write the version string in clear text + signatures. Use this to overwrite a previous --no-version from a + config file. + +- -N, --notation-data =name=value= :: Put the name value pair into the + signature as notation data. =name= must consists only of alphanumeric + characters, digits or the underscore; the first character must not be + a digit. =value= may be any printable string; it will encoded in + UTF8, so sou should have check that your --charset is set right. If + you prefix =name= with an exclamation mark, the notation data will be + flagged as critical (rfc2440:5.2.3.15). + +- --set-policy-url =string= :: Use =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. + +- --set-filename =string= :: Use =string= as the name of file which is + stored in messages. + +- --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. + +- --completes-needed =n= :: Number of completely trusted users to + introduce a new key signer (defaults to 1). + +- --marginals-needed =n= :: Number of marginally trusted users to + introduce a new key signer (defaults to 3) + +- --max-cert-depth =n= :: Maximum depth of a certification chain + (default is 5). + +- --cipher-algo =name= :: Use =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. + +- --digest-algo =name= :: Use =name= as message digest algorithm. + Running the program with the command --version yields a list of + supported algorithms. Please note that using this option may violate + the OpenPGP requirement, that a 160 bit hash is to be used for DSA. + +- --s2k-cipher-algo =name= :: Use =name= as the cipher algorithm used + to protect secret keys. The default cipher is BLOWFISH. This cipher + is also used for conventional encryption if --cipher-algo is not + given. + +- --s2k-digest-algo =name= :: Use =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. + +- --s2k-mode =n= :: Selects how passphrases are mangled. If =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. + +- --compress-algo =n= :: Use compress algorithm =n=. Default is 2 which + is RFC1950 compression. You may use 1 to use the old zlib version + (RFC1951) which is used by PGP. 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. + +- --disable-cipher-algo =name= :: Never allow the use of =name= as + cipher algorithm. The given name will not be checked so that a later + loaded algorithm will still get disabled. + +- --disable-pubkey-algo =name= :: Never allow the use of =name= as + public key algorithm. The given name will not be checked so that a + later loaded algorithm will still get disabled. + +- --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. + +- --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. + +- --escape-from-lines :: Because some mailers change lines starting + with "From " to " :: Using an exact to + match string. The equal sign indicates this. + +- :: Using the email address part which + must match exactly. The left angle bracket indicates this email + address mode. + +- +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. + +- #34 :: Using the Local ID. This is a very low level method and should + only be used by applications which really need it. The hash character + indicates this method. An application should not assume that this is + only a number. + +- Heine, *Heine :: By case insensitive substring matching. This is the + default mode but applications may want to explicitely indicate this + by putting the asterisk in front. + +** 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. + +** EXAMPLES + +- gpg -se -r =Bob= =file= :: sign and encrypt for user Bob + +- gpg --clearsign =file= :: make a clear text signature + +- gpg -sb =file= :: make a detached signature + +- gpg --list-keys =user_ID= :: show keys + +- gpg --fingerprint =user_ID= :: show fingerprint + +- gpg --verify =pgpfile=, gpg --verify =sigfile= [ =files= ] :: Verify + the signature of the file but do not output the data. The second form + is used for detached signatures, where =sigfile= is the detached + signature (either ASCII armored of binary) and [ =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 =sigfile= or by asking the user for the filename. + +** ENVIRONMENT + +- HOME :: Used to locate the default home directory. + +- GNUPGHOME :: If set directory used instead of "~/.gnupg". + +- http\_proxy :: Only honored when the option --honor-http-proxy is + set. + +** FILES + +- ~/.gnupg/secring.gpg :: The secret keyring + +- ~/.gnupg/secring.gpg.lock :: and the lock file + +- ~/.gnupg/pubring.gpg :: The public keyring + +- ~/.gnupg/pubring.gpg.lock :: and the lock file + +- ~/.gnupg/trustdb.gpg :: The trust database + +- ~/.gnupg/trustdb.gpg.lock :: and the lock file + +- ~/.gnupg/random\_seed :: used to preserve the internal random pool + +- ~/.gnupg/options :: May contain options + +- /usr[/local]/share/gnupg/options.skel :: Skeleton options file + +- /usr[/local]/lib/gnupg/ :: Default location for extensions + +** 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! + +** 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 3our operating system supports +locking without being root. The program drops root privileges as soon as +locked memory is allocated.