1! .TH PGP 1 "PGP Version 2.6.3i" 2! .\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection 3! .\" other parms are allowed: see man(7), man(1) 41 PGP 5 Pretty Good Privacy encryption system (PGP Version 2.6.3i). 6 7 SYNOPSIS 8 9 $ pgp [options] pgpfile 10 11 $ pgp -e [options] file user 12 13 DOCUMENTATION 14 15 Full documentation path: PGP$LIBRARY:[DOC] 16 Read PGPDOC1.TXT and PGPDOC2.TXT before to start using this product. 17 18 "THE BEGINNER'S GUIDE" and the "Frequently Asked Questions" can be found 19 in the same directory, the file names are: PGPBG11.ASC and PGP.FAQ 20! 212 Description 22 PGP (Pretty Good Privacy) is a public key encryption package to protect 23 E-mail and data files. It lets you communicate securely with people 24 you've never met, with no secure channels needed for prior exchange of 25 keys. It's well featured and fast, with sophisticated key management, 26 digital signatures, data compression, and good ergonomic design. If you 27 really want to learn how to use it properly, it's best to read the full 28 documentation that comes with the system, which is very complete. This 29 is a "quick start" guide and reference manual; it is necessarily 30 incomplete, and assumes you are already familiar with most of the basic 31 concepts, including the concepts behind public key cryptography. 32! 332 Terminology 34 user id: an ascii string used to identify a user. 35 36 User IDs tend to look like "John Q. Public <jqp@xyzcorp.com>"; please 37 try sticking to that format. When giving a user id to PGP, you may 38 specify any unique (case-insensitive) substring. E.g. john, or 39 jqp@xyz. 40 41 pass phrase: the secret string used to conventionally encipher your 42 private key. It's important that this be kept secret. 43 44 keyring: a file containing a set of public or secret keys. 45 46 Default names for public and secret rings are "pubring.pgp" and 47 "secring.pgp" respectively. 48 49 ascii armor: the ascii radix 64 format PGP uses for transmitting messages 50 over channels like E-Mail; similar in concept to uuencoding. 51! 522 Command_summary 53 54 To see a quick command usage summary for PGP, just type: 55 56 $ pgp -h 57 58 To encrypt a plaintext file with the recipient's public key: 59 60 $ pgp -e textfile her_userid [other userids] 61 62 To sign a plaintext file with your secret key: 63 64 $ pgp -s textfile [-u your_userid] 65 66 To sign a plaintext file with your secret key, and then encrypt it with 67 the recipient's public key: 68 69 $ pgp -es textfile her_userid [other userids] [-u your_userid] 70 71 To create a signature certificate that is detached from the document: 72 73 $ pgp -sb textfile [-u your_userid] 74 75 To encrypt a plaintext file with just conventional cryptography, type: 76 77 $ pgp -c textfile 78 79 To decrypt an encrypted file, or to check the signature integrity of a 80 signed file: 81 82 $ pgp ciphertextfile [-o plaintextfile] 83 84 To see a quick summary of PGP's key-management commands, just type: 85 86 $ pgp -k 87 88 To generate your own unique public/secret key pair: 89 90 $ pgp -kg 91 92 To add a public or secret key file's contents to your public or secret 93 key ring: 94 95 $ pgp -ka keyfile [keyring] 96 97 To remove a key from your public key ring: 98 99 $ pgp -kr userid [keyring] 100 101 To extract (copy) a key from your public or secret key ring: 102 103 $ pgp -kx[a] userid keyfile [keyring] 104 105 To view the contents of your public key ring: 106 107 $ pgp -kv[v] [userid] [keyring] 108 109 To view the "fingerprint" of a public key, to help verify it over the 110 telephone with its owner: 111 112 $ pgp -kvc [userid] [keyring] 113 114 To view the contents and check the certifying signatures of your public 115 key ring: 116 117 $ pgp -kc [userid] [keyring] 118 119 To edit the pass phrase for or add a userid to your secret key: 120 121 $ pgp -ke userid [keyring] 122 123 To edit the trust parameters for a public key: 124 125 $ pgp -ke userid [keyring] 126 127 To remove a key or just a userid from your public key ring: 128 129 $ pgp -kr userid [keyring] 130 131 To sign and certify someone else's public key on your public key ring: 132 133 $ pgp -ks her_userid [-u your_userid] [keyring] 134 135 To remove selected signatures from a userid on a keyring: 136 137 $ pgp -krs userid [keyring] 138 139 140 Command options that can be used in combination with other command 141 options (sometimes even spelling interesting words): 142 143 To produce a ciphertext file in ASCII radix-64 format, just add the -a 144 option when encrypting or signing a message or extracting a key: 145 146 $ pgp -sea textfile her_userid 147 148 $ pgp -kxa userid keyfile [keyring] 149 150 To wipe out the plaintext file after producing the ciphertext file, just 151 add the -w (wipe) option when encrypting or signing a message: 152 153 $ pgp -sew message.txt her_userid 154 155 To specify that a plaintext file contains ASCII text, not binary, and 156 should be converted to recipient's local text line conventions, add the 157 -t (text) option to other options: 158 159 $ pgp -seat message.txt her_userid 160 161 To view the decrypted plaintext output on your screen (like the 162 Unix-style "more" command), without writing it to a file, use the -m 163 (more) option while decrypting: 164 165 $ pgp -m ciphertextfile 166 167 To specify that the recipient's decrypted plaintext will be shown only on 168 her screen and cannot be saved to disk, add the -m option: 169 170 $ pgp -steam message.txt her_userid 171 172 To recover the original plaintext filename while decrypting, add the -p 173 option: 174 175 $ pgp -p ciphertextfile 176 177 To use a Unix-style filter mode, reading from standard input and writing 178 to standard output, add the -f option: 179 180 $ pgp -feast her_userid <inputfile >outputfile 181! 1822 The_Config_File 183 PGP uses a configuration database that is stored in the file 184 "config.txt"; please see the manual for complete details. Blank lines and 185 lines beginning with "#" are comments. Options take string, numeric, or 186 boolean values. The boolean values are "on" and "off". These options can 187 also be specified on the command line, using a syntax such as +armor=on. 188 Keywords can be abbreviated to unique prefixes. Keywords are not 189 case-sensitive. "=on" is assumed for boolean options if nothing is 190 specified. Some highlights: 1913 MYNAME 192 MYNAME - Default User ID for Making Signatures 193 194 Default setting: MYNAME = "" 195 196 The configuration parameter MYNAME specifies the default user ID to 197 use to select the secret key for making signatures. If MYNAME is not 198 defined, the most recent secret key you installed on your secret key 199 ring is used. The user may also override this setting by specifying a 200 user ID on the PGP command line with the -u option. 2013 TEXTMODE 202 TEXTMODE - Assuming Plaintext is a Text File 203 204 Default setting: TEXTMODE = off 205 206 The configuration parameter TEXTMODE is equivalent to the -t command 207 line option. If enabled, it causes PGP to assume the plaintext is a 208 text file, not a binary file, and converts it to "canonical text" 209 before encrypting it. Canonical text has a carriage return and a 210 linefeed at the end of each line of text. 211 212 This mode is automatically turned off if PGP detects that the 213 plaintext file contains 8-bit binary data. Thus, it is safe to leave 214 enabled at all times. 2153 ARMOR 216 ARMOR - Enable ASCII Armor Output 217 218 Default setting: ARMOR = off 219 220 The configuration parameter ARMOR is equivalent to the -a command 221 line option. If enabled, it causes PGP to emit ciphertext or keys in 222 ASCII Radix-64 format suitable for transporting through E-mail 223 channels. Output files are named with the ".asc" extension. 224 225 If you tend to use PGP mostly for E-mail, it may be a good idea to 226 enable this parameter. 2273 ARMORLINES 228 ARMORLINES - Size of ASCII Armor Multipart Files 229 230 Default setting: ARMORLINES = 720 231 232 For large ASCII armor files, PGP splits them into files named 233 ".asc1", ".asc2", ".asc3", etc. so as not to choke mailers, which 234 typically starts to happen around 50,000 bytes. This specifies the 235 number of (64-byte) lines to place in each file. If set to 0, PGP 236 will not split ASCII armor files. 2373 CLEARSIG 238 CLEARSIG - Enable Clear-Signed Output 239 240 Default setting: CLEARSIG = on 241 242 Normally, a signed and ASCII-armored PGP message is gibberish, even 243 though the text is not encrypted. This prevents munging by mailers, 244 but requires PGP to simply read the message. 245 246 If CLEARSIG is enabled, then when signing and ASCII-armoring a text 247 file, PGP uses a different format that includes the plaintext in 248 human-readable form. Lines beginning with "-" are quoted with "\-\ ". 249 To cope with some of the stupider mailers in the world, lines 250 beginning with "From" are also quoted, and trailing whitespace on 251 lines is stripped. PGP will remove the quoting if you use it to 252 decrypt the message, but the trailing whitespace is not recovered. 253 This is still useful enough to be enabled by default. 2543 ENCRYPTTOSELF 255 ENCRYPTTOSELF - Add MYNAME to Recipients List 256 257 Default setting: ENCRYPTTOSELF = off 258 259 If this is emabled, MYNAME will be implcitly added to the list of 260 recipients for any message you encrypt with a public key. Since in 261 this case, MYNAME is looked up in the public keyring, it is important 262 that it unambiguously specify the right key. 2633 LANGUAGE 264 LANGUAGE - Language To Use 265 266 Default setting: LANGUAGE = en 267 268 If you want to use a different language, and translations are in the 269 language.txt file, setting this option will cause PGP's messages to 270 appear in a different language. If a translation for a message is not 271 available, it appears in english. 272 273 If you look at the supplied language.txt file, the format should be 274 obvious. 2753 CHARSET 276 CHARSET - Character Set 277 278 Default setting: CHARSET = noconv 279 280 PGP tries to translate all text-mode messages into the ISO Latin-1 281 alphabet, or the KOI-8 alphabet for cyrillic alphabets. This setting 282 indicates the native character set, so PGP can do the translation. 283 Options are noconv, latin1 or koi8, indicating that no translation 284 should be done; cp850, indicating that IBM PC code page 850 mappings 285 should be used; ascii, indicating that a minimal ASCII subset should 286 be used; and alt_codes, indicating that the IBM PC alt codes should 287 be used for the cyrillic alphabet. 2883 KEEPBINARY 289 KEEPBINARY - Preserve Intermediate .pgp File 290 291 Default setting: KEEPBINARY = off 292 293 If KEEPBINARY is enabled, then PGP will produce a .pgp file in 294 addition to a .asc file when ASCII armor is enabled. 2953 TMP 296 TMP - Temporary file directory 297 298 Default setting: TMP = "" 299 300 PGP produces temporary files while decrypting a message. This is the 301 directory they are stored in. If not specified in the config file, 302 the environment variable TMP is used, or the current directory. It 303 helps security somewhat if this is not a publicly-readable directory. 304 A local file system is also a good idea. 3053 COMPRESS 306 COMPRESS - Compress Plaintext Before Encrypting 307 308 Default setting: COMPRESS = on 309 310 PGP usually compresses the plaintext before encrypting it, so it will 311 have less to encrypt and the file you send will be smaller. It also 312 makes cryptanalysis harder. This is usually only turned off for 313 debugging purposes. 3143 PAGER 315 PAGER - Select Shell Command to Display Pager Output 316 317 Default setting: PAGER = "" 318 319 If set, PGP uses this program to view files when the -m option is 320 specified. By default, PGP uses a simple builtin pager. 3213 SHOWPASS 322 SHOWPASS - Echo Pass Phrase During Entry 323 324 Default setting: SHOWPASS = off 325 326 If someone is unable to type a long pass phrase reliably without 327 seeing it, this can be turned on, at the cost of security. 3283 INTERACTIVE 329 INTERACTIVE - Prompt Before Adding Each Key 330 331 Default setting: INTERACTIVE = off 332 333 By default, when given a file containing new keys, PGP asks if you 334 would like to add them to your public key ring. Since adding keys 335 does not imply that you trust them, adding more just wakes up space. 336 If this option is set, PGP asks about each key in a key file. 3373 VERBOSE 338 VERBOSE - Level of Detail Printed 339 340 Default setting: VERBOSE = 1 341 342 When set to 0, PGP only prints messages that are necessary or 343 indicate an error. When set to 2, PGP prints a significant amount of 344 debugging information describing what it's doing. Values above 2 have 345 no effect. 3463 PUBRING 347 PUBRING - Public Key Ring Location 348 349 Default setting: PUBRING = $PGPPATH/pubring.pgp 350 351 This is the path name to the public key ring to use. 3523 SECRING 353 SECRING - Secret Key Ring Location 354 355 Default setting: SECRING = $PGPPATH/secring.pgp 356 357 This is the path name to the secret key ring to use. 3583 BAKRING 359 BAKRING - Backup Secret Key Ring 360 361 Default setting: BAKRING = "" 362 363 If this is set, when checking your key ring (pgp -kc), PGP will 364 compare the normal secret key ring against the given backup copy, 365 usually kept on write-protected removable media. This is to protect 366 against wholesale modifications to your key rings in a spoofing 367 attack. 3683 RANDSEED 369 RANDSEED - Random Number Seed File 370 371 Default setting: RANDSEED = $PGPPATH/randseed.bin 372 373 This is the path to a random seed file which is part of PGP's random 374 number generation algorithm, used to generate session keys. While PGP 375 goes to great lengths to use every available source of randomness in 376 generating session keys, this file is part of the process and 377 protecting it from disclosure is desirable. 3783 COMMENT 379 COMMENT - ASCII Armor Comment 380 381 Default setting: COMMENT = "" 382 383 If set to a non-empty string, the value of this variable is printed 384 in the header of ASCII armor files, preceded by "Comment: ". 3853 LEGAL_KLUDGE 386 LEGAL_KLUDGE - Incompatibility with PGP versions prior to 2.6 387 388 Default setting: LEGAL_KLUDGE = on 389 390 If set, PGP will generate keys and messages in a new format that 391 cannot be read by PGP 2.5 and earlier versions. 392! 3932 Key_certification 394 PGP employs a system where users specify trusted users who may sign other 395 people's public keys. It is important that you understand how this 396 mechanism works; a full description is in the manual. 397 398 Important: The manual also describes how to generate and send a "key 399 compromise" certificate that tells readers that your private 400 key has been compromised. If your key has been compromised, 401 please read the manual section on key compromise certificates 402 and how to create them; the faster you send out a key 403 compromise certificate, the smaller the window of opportunity 404 for "bad guys" to send forged messages. 405! 4062 Important_Hints 407 PGP automatically tries compressing your input file; there is little 408 point in precompressing input for transmission. 409 410 PGP "ascii armor" is only needed on the outer transmitted message; as an 411 example, if you are, say, sending a public key to someone else and you 412 are for some reason signing it, simply armor the outer message; it's 413 better to sign the binary form of the key. 414! 4152 Foreign_Languages 416 PGP is easily customized for foreign language help and error messages; 417 it has been translated into a number of non-english languages. See the 418 manual for details on the file "language.txt". 419! 4202 Environment 421 PGP uses several special files for its purposes, such as your standard 422 key ring files "pubring.pgp" and "secring.pgp", the random number seed 423 file "randseed.bin", the PGP configuration file "config.txt", and the 424 foreign language string translation file "language.txt". These special 425 files can be kept in any directory, by setting the environment variable 426 "PGPPATH" to the desired pathname. If PGPPATH remains undefined, these 427 special files are assumed to be in the current directory. 428 429 Normally, PGP prompts the user to type a pass phrase whenever PGP needs a 430 pass phrase to unlock a secret key. But it is possible to store the pass 431 phrase in an environment variable from your operating system's command 432 shell. The environment variable PGPPASS can be used to hold the pass 433 phrase that PGP attempts to use first. If the pass phrase stored in 434 PGPPASS is incorrect, PGP recovers by prompting the user for the correct 435 pass phrase. This dangerous feature makes your life more convenient if 436 you have to regularly deal with a large number of incoming messages 437 addressed to your secret key, by eliminating the need for you to 438 repeatedly type in your pass phrase every time you run PGP. 439 This is a very dangerous feature; on UNIX it is trivial to read someone 440 else's environment using the ps(1) command. If you are contemplating 441 using this feature, be sure to read the sections "How to Protect Secret 442 Keys from Disclosure" and "Exposure on Multi-user Systems" in the full 443 PGP manual. 444 445 If the environment variable PGPPASSFD is defined, it must have a numeric 446 value, which PGP uses as a file descriptor number to read a pass phrase 447 from. This is done before anything else, so it can be combined with an 448 input file on standard input. This is mainly for use by shell scripts, 449 since under Unix it is difficult to read the contents of other people's 450 pipes. 451! 4522 Return_Value 453 PGP returns a 0 to the shell on success, and a nonzero error code on 454 failure. See the source code for details on nonzero status return values. 455! 4562 Files 457 *.pgp ciphertext, signature, or key file 458 *.asc ascii armor file 459 /usr/local/lib/config.txt system-wide configuration file 460 $PGPPATH/config.txt per-user configuration file 461 $PGPPATH/pubring.pgp public key ring 462 $PGPPATH/secring.pgp secret key ring 463 $PGPPATH/randseed.bin random number seed file 464 /usr/local/lib/pgp/language.txt 465 $PGPPATH/language.txt foreign language translation file 466 /usr/local/lib/pgp/pgp.hlp 467 $PGPPATH/pgp/pgp.hlp online help text file 468 /usr/local/lib/pgp/pgpkey.hlp 469 $PGPPATH/pgp/pgpkey.hlp online key-management help text file 470! 4712 Note 472 The manual is really good, and it's really important in the long run that 473 you read it. PGP may be an unpickable lock, but you have to put in in the 474 door properly to keep out intruders. So read the manual and find out how! 475! 4762 Caveats 477 It is impossible to overemphasize the importance of protecting your 478 secret key. Anyone gaining access to it can forge messages from you or 479 read mail addressed to you. Be very cautious in using PGP on any 480 multi-user unix system. 481 482 PGP is believed by its authors to be the most secure cryptographic 483 software available to the public when used as directed, but then again 484 everyone always claims their pet encryption system is secure. Read the 485 section in the manual on "Trusting Snake Oil" and the section on 486 "Vulnerabilities" for caveats. 487! 4882 Diagnostics 489 490 Mostly self explanatory. 491! 4922 Bugs 493 PGP was initially written for the PC, and behaves very PCish. In 494 particular, its automagic file selection, file extensions, and the like 495 all make it somewhat alien in the UNIX environment. 496 497 This man page needs to be updated to reflect all the latest features. 498! 4992 Authors 500 Originally written by Philip R. Zimmermann. Later augmented by a cast of 501 thousands. 502! 5032 Legal_Restrictions 504 PGP 2.6.3i is freeware, and may be used for non-commercial purposes only. 505 This version of PGP is illegal to use within the USA but is fine 506 elsewhere in the world. US users should get a copy of MIT PGP 2.6.2 507 instead, or purchase the commercial version 2.7.1 from ViaCrypt. 508 509 For detailed information on PGP licensing, distribution, copyrights, 510 patents, trademarks, liability limitations, and export controls, see the 511 "Legal Issues" section in the "PGP User's Guide, Volume II: Special 512 Topics". 513 514 515