Phil's Pretty Good Software Presents ======= PGP(tm) ======= Pretty Good(tm) Privacy Public Key Encryption for the Masses ------------------------- PGP(tm) User's Guide Volume II: Special Topics ------------------------- by Philip Zimmermann Revised 11 October 94 PGP Version 2.6.2 - 11 Oct 94 Software by Philip Zimmermann, and many others. Synopsis: PGP(tm) uses public-key encryption to protect E-mail and data files. Communicate securely with people you've never met, with no secure channels needed for prior exchange of keys. PGP is well featured and fast, with sophisticated key management, digital signatures, data compression, and good ergonomic design. Software and documentation (c) Copyright 1990-1994 Philip Zimmermann. All rights reserved. For information on PGP licensing, distribution, copyrights, patents, trademarks, liability limitations, and export controls, see the "Legal Issues" section. Distributed by the Massachusetts Institute of Technology. Contents ======== Quick Overview Special Topics Selecting Keys via Key ID Separating Signatures from Messages Decrypting the Message and Leaving the Signature on it Sending ASCII Text Files Across Different Machine Environments Using PGP as a Better Uuencode Leaving No Traces of Plaintext on the Disk Displaying Decrypted Plaintext on Your Screen Making a Message For Her Eyes Only Preserving the Original Plaintext Filename Editing Your User ID or Pass Phrase Editing the Trust Parameters for a Public Key Checking If Everything is OK on Your Public Key Ring Verifying a Public Key Over the Phone Handling Large Public Keyrings Using PGP as a Unix-style Filter Suppressing Unnecessary Questions: BATCHMODE Force "Yes" Answer to Confirmation Questions: FORCE PGP Returns Exit Status to the Shell Environmental Variable for Pass Phrase Setting Parameters in the PGP Configuration File TMP - Directory Pathname for Temporary Files LANGUAGE - Foreign Language Selector MYNAME - Default User ID for Making Signatures TEXTMODE - Assuming Plaintext is a Text File CHARSET - Specifies Local Character Set for Text Files ARMOR - Enable ASCII Armor Output ARMORLINES - Size of ASCII Armor Multipart Files KEEPBINARY - Keep Binary Ciphertext Files After Decrypting COMPRESS - Enable Compression COMPLETES_NEEDED - Number of Completely Trusted Introducers Needed MARGINALS_NEEDED - Number of Marginally Trusted Introducers Needed CERT_DEPTH - How Deep May Introducers Be Nested BAKRING - Filename for Backup Secret Keyring PUBRING - Filename for Your Public Keyring SECRING - Filename for Your Secret Keyring RANDSEED - Filename for Random Number Seed PAGER - Selects Shell Command to Display Plaintext Output SHOWPASS - Echo Pass Phrase to User TZFIX - Timezone Adjustment CLEARSIG - Enable Signed Messages to be Encapsulated as Clear Text VERBOSE - Quiet, Normal, or Verbose Messages INTERACTIVE - Ask for Confirmation for Key Adds NOMANUAL - Let PGP Generate Keys Without the Manual A Peek Under the Hood Random Numbers PGP's Conventional Encryption Algorithm Data Compression Message Digests and Digital Signatures Compatibility with Previous and Future Versions of PGP Vulnerabilities Compromised Pass Phrase and Secret Key Public Key Tampering "Not Quite Deleted" Files Viruses and Trojan Horses Physical Security Breach Tempest Attacks Exposure on Multi-user Systems Traffic Analysis Protecting Against Bogus Timestamps Cryptanalysis Legal Issues Trademarks, Copyrights, and Warranties Patent Rights on the Algorithms Freeware Status and Restrictions Restrictions on Commercial Use of PGP Other Licensing Restrictions Distribution Export Controls Philip Zimmermann's Legal Situation Other Sources of Information on PGP Where to Get a Commercial Version of PGP Reporting PGP Bugs Fan Mail, Updates, and News Computer-Related Political Groups Recommended Readings To Contact the Author Appendix A: Where to Get PGP Quick Overview ============== Pretty Good(tm) Privacy (PGP), from Phil's Pretty Good Software, is a high security cryptographic software application for MSDOS, Unix, VAX/VMS, and other computers. PGP combines the convenience of the Rivest-Shamir-Adleman (RSA) public key cryptosystem with the speed of conventional cryptography, message digests for digital signatures, data compression before encryption, good ergonomic design, and sophisticated key management. This volume II of the PGP User's Guide covers advanced topics about PGP that were not covered in the "PGP User's Guide, Volume I: Essential Topics". You should first read the Essential Topics volume, or this manual won't make much sense to you. Reading this Special Topics volume is optional, except for the legal issues section, which everyone should read. Special Topics =============== Selecting Keys via Key ID ------------------------- In all commands that let the user type a user ID or fragment of a user ID to select a key, the hexadecimal key ID may be used instead. Just use the key ID, with a prefix of "0x", in place of the user ID. For example: pgp -kv 0x67F7 This would display all keys that had 67F7 as part of their key IDs. This feature is particularly useful if you have two different keys from the same person, with the same user ID. You can unambiguously pick which key you want by specifying the key ID. Separating Signatures from Messages ----------------------------------- Normally, signature certificates are physically attached to the text they sign. This makes it convenient in simple cases to check signatures. It is desirable in some circumstances to have signature certificates stored separately from the messages they sign. It is possible to generate signature certificates that are detached from the text they sign. To do this, combine the 'b' (break) option with the 's' (sign) option. For example: pgp -sb letter.txt This example produces an isolated signature certificate in a file called "letter.sig". The contents of letter.txt are not appended to the signature certificate. After creating the signature certificate file (letter.sig in the above example), send it along with the original text file to the recipient. The recipient must have both files to check the signature integrity. When the recipient attempts to process the signature file, PGP notices that there is no text in the same file with the signature and prompts the user for the filename of the text. Only then can PGP properly check the signature integrity. If the recipient knows in advance that the signature is detached from the text file, she can specify both filenames on the command line: pgp letter.sig letter.txt or: pgp letter letter.txt PGP will not have to prompt for the text file name in this case. A detached signature certificate is useful if you want to keep the signature certificate in a separate certificate log. A detached signature of an executable program is also useful for detecting a subsequent virus infection. It is also useful if more than one party must sign a document such as a legal contract, without nesting signatures. Each person's signature is independent. If you receive a ciphertext file that has the signature certificate glued to the message, you can still pry the signature certificate away from the message during the decryption. You can do this with the -b option during decrypt, like so: pgp -b letter This decrypts the letter.pgp file and if there is a signature in it, PGP checks the signature and detaches it from the rest of the message, storing it in the file letter.sig. Decrypting the Message and Leaving the Signature on it ------------------------------------------------------ Usually, you want PGP to completely unravel a ciphertext file, decrypting it and checking the nested signature if there is one, peeling away the layers until you are left with only the original plaintext file. But sometimes you want to decrypt an encrypted file, and leave the inner signature still attached, so that you are left with a decrypted signed message. This may be useful if you want to send a copy of a signed document to a third party, perhaps re-enciphering it. For example, suppose you get a message signed by Charlie, encrypted to you. You want to decrypt it, and, leaving Charlie's signature on it, you want to send it to Alice, perhaps re-enciphering it with Alice's public key. No problem. PGP can handle that. To simply decrypt a message and leave the signature on it intact, type: pgp -d letter This decrypts letter.pgp, and if there is an inner signature, it is left intact with the decrypted plaintext in the output file. Now you can archive it, or maybe re-encrypt it and send it to someone else. Sending ASCII Text Files Across Different Machine Environments -------------------------------------------------------------- You may use PGP to encrypt any kind of plaintext file, binary 8-bit data or ASCII text. Probably the most common usage of PGP will be for E-mail, when the plaintext is ASCII text. ASCII text is sometimes represented differently on different machines. For example, on an MSDOS system, all lines of ASCII text are terminated with a carriage return followed by a linefeed. On a Unix system, all lines end with just a linefeed. On a Macintosh, all lines end with just a carriage return. This is a sad fact of life. Normal unencrypted ASCII text messages are often automatically translated to some common "canonical" form when they are transmitted from one machine to another. Canonical text has a carriage return and a linefeed at the end of each line of text. For example, the popular KERMIT communication protocol can convert text to canonical form when transmitting it to another system. This gets converted back to local text line terminators by the receiving KERMIT. This makes it easy to share text files across different systems. But encrypted text cannot be automatically converted by a communication protocol, because the plaintext is hidden by encipherment. To remedy this inconvenience, PGP lets you specify that the plaintext should be treated as ASCII text (not binary data) and should be converted to canonical text form before it gets encrypted. At the receiving end, the decrypted plaintext is automatically converted back to whatever text form is appropriate for the local environment. To make PGP assume the plaintext is text that should be converted to canonical text before encryption, just add the "t" option when encrypting or signing a message, like so: pgp -et message.txt her_userid This mode is automatically turned off if PGP detects that the plaintext file contains what it thinks is non-text binary data. If you need to use the -t option a lot, you can just turn on the TEXTMODE flag in the PGP configuration file. That's what I do. For PGP users that use non-English 8-bit character sets, when PGP converts text to canonical form, it may convert data from the local character set into the LATIN1 (ISO 8859-1 Latin Alphabet 1) character set, depending on the setting of the CHARSET parameter in the PGP configuration file. LATIN1 is a superset of ASCII, with extra characters added for many European languages. Using PGP as a Better Uuencode ------------------------------ A lot of people in the Unix world send binary data files through E-mail channels by using the Unix "uuencode" utility to convert the file into printable ASCII characters that can be sent via email. No encryption is involved, so neither the sender nor the recipient need any special keys. The uuencode format was designed for a similar purpose as PGP's radix-64 ASCII transport armor format described in the "Sending Ciphertext Through E-mail Channels: Radix-64 Format" section, but not as good. A different radix-64 character set is used. Uuencode has its problems, such as 1) several slightly incompatible character sets for different versions of uuencode in the MSDOS and Unix worlds, and 2) the data can be corrupted by some E-mail gateways that strip trailing blanks or do other modifications to the character set used by uuencode. PGP may be used in a manner that offers the same general features as uuencode, and then some. You can get PGP to just convert a file into PGP's radix-64 ASCII transport armor format, but you don't have to encrypt the file or sign it, so no keys are needed by either party. Simply use the -a option alone. For example: pgp -a filename This would produce a radix-64 armored file called "filename.asc". If you read the "Sending Ciphertext Through E-mail Channels: Radix-64 Format" section, you will see that PGP's approach offers several important advantages over the uuencode approach: * PGP will break big files up into chunks small enough to E-mail. * PGP will append a CRC error detection code to each chunk. * PGP will attempt to compress the data before converting it to radix-64 armor. * PGP's radix-64 character set is more resilient to E-mail character conversions than the one used by uuencode. * Textfiles can be converted by the sender to canonical text format, as explained in the "Sending ASCII Text Files Across Different Machine Environments" section. The recipient can restore the sender's original filename by unwrapping the message with PGP's -p option. You can use "pgp -a" in any situation in which you could have used uuencode, if the recipient also has PGP. PGP is a better uuencode than uuencode. Leaving No Traces of Plaintext on the Disk ------------------------------------------ After PGP makes a ciphertext file for you, you can have PGP automatically overwrite the plaintext file and delete it, leaving no trace of plaintext on the disk so that no one can recover it later using a disk block scanning utility. This is useful if the plaintext file contains sensitive information that you don't want to keep around. To wipe out the plaintext file after producing the ciphertext file, just add the "w" (wipe) option when encrypting or signing a message, like so: pgp -esw message.txt her_userid This example creates the ciphertext file "message.pgp", and the plaintext file "message.txt" is destroyed beyond recovery. Obviously, you should be careful with this option. Also note that this will not wipe out any fragments of plaintext that your word processor might have created on the disk while you were editing the message before running PGP. Most word processors create backup files, scratch files, or both. Also, it overwrites the file only once, which is enough to thwart conventional disk recovery efforts, but not enough to withstand a determined and sophisticated effort to recover the faint magnetic traces of the data using special disk recovery hardware. Displaying Decrypted Plaintext on Your Screen --------------------------------------------- To view the decrypted plaintext output on your screen (like the Unix-style "more" command), without writing it to a file, use the -m (more) option while decrypting: pgp -m ciphertextfile This displays the decrypted plaintext display on your screen one screenful at a time. Making a Message For Her Eyes Only ---------------------------------- To specify that the recipient's decrypted plaintext will be shown ONLY on her screen and will not be saved to disk, add the -m option: pgp -sem message.txt her_userid Later, when the recipient decrypts the ciphertext with her secret key and pass phrase, the plaintext will be displayed on her screen but will not be saved to disk. The text will be displayed as it would if she used the Unix "more" command, one screenful at a time. If she wants to read the message again, she will have to decrypt the ciphertext again. This feature is the safest way for you to prevent your sensitive message from being inadvertently left on the recipient's disk. This feature was added at the request of a user who wanted to send intimate messages to his lover, but was afraid she might accidentally leave the decrypted messages on her husband's computer. Note that this feature will not prevent a clever and determined person from finding a way to save the decrypted plaintext to disk-- it's to help prevent a casual user from doing it inadvertently. Preserving the Original Plaintext Filename ------------------------------------------ Normally, PGP names the decrypted plaintext output file with a name similar to the input ciphertext filename, but dropping the extension. Or, you can override that convention by specifying an output plaintext filename on the command line with the -o option. For most E-mail, this is a reasonable way to name the plaintext file, because you get to decide its name when you decipher it, and your typical E-mail messages often come from useless original plaintext filenames like "to_phil.txt". But when PGP encrypts a plaintext file, it always saves the original filename and attaches it to the plaintext before it compresses and encrypts the plaintext. Normally, this hidden original filename is discarded by PGP when it decrypts, but you can tell PGP you want to preserve the original plaintext filename and use it as the name of the decrypted plaintext output file. This is useful if PGP is used on files whose names are important to preserve. To recover the original plaintext filename while decrypting, add the -p option, like so: pgp -p ciphertextfile I usually don't use this option, because if I did, about half of my incoming E-mail would decrypt to the same plaintext filenames of "to_phil.txt" or "prz.txt". Editing Your User ID or Pass Phrase ----------------------------------- Sometimes you may need to change your pass phrase, perhaps because someone looked over your shoulder while you typed it in. Or you may need to change your user ID, because you got married and changed your name, or maybe you changed your E-mail address. Or maybe you want to add a second or third user ID to your key, because you may be known by more than one name or E-mail address or job title. PGP lets you attach more than one user ID to your key, any one of which may be used to look up your key on the key ring. To edit your own userid or pass phrase for your secret key: pgp -ke userid [keyring] PGP prompts you for a new user ID or a new pass phrase. If you edit your user ID, PGP actually adds a new user ID, without deleting the old one. If you want to delete an old user ID, you will have to do that in a separate operation. The optional [keyring] parameter, if specified, must be a public keyring, not a secret keyring. The userid field must be your own userid, which PGP knows is yours because it appears on both your public keyring and your secret keyring. Both keyrings will be updated, even though you only specified the public keyring. The -ke command works differently depending on whether you use it on a public or secret key. It can also be used to edit the trust parameters for a public key. Editing the Trust Parameters for a Public Key --------------------------------------------- Sometimes you need to alter the trust parameters for a public key on your public key ring. For a discussion on what these trust parameters mean, see the section "How Does PGP Keep Track of Which Keys are Valid?" in the Essential Topics volume of the PGP User's Guide. To edit the trust parameters for a public key: pgp -ke userid [keyring] The optional [keyring] parameter, if specified, must be a public keyring, not a secret keyring. Checking If Everything is OK on Your Public Key Ring ---------------------------------------------------- Normally, PGP automatically checks any new keys or signatures on your public key ring and updates all the trust parameters and validity scores. In theory, it keeps all the key validity status information up to date as material is added to or deleted from your public key ring. But perhaps you may want to explicitly force PGP to perform a comprehensive analysis of your public key ring, checking all the certifying signatures, checking the trust parameters, updating all the validity scores, and checking your own ultimately-trusted key against a backup copy on a write-protected floppy disk. It may be a good idea to do this hygienic maintenance periodically to make sure nothing is wrong with your public key ring. To force PGP to perform a full analysis of your public key ring, use the -kc (key ring check) command: pgp -kc You can also make PGP check all the signatures for just a single selected public key by: pgp -kc userid [keyring] For further information on how the backup copy of your own key is checked, see the description of the BAKRING parameter in the configuration file section of this manual. Verifying a Public Key Over the Phone ------------------------------------- If you get a public key from someone that is not certified by anyone you trust, how can you tell if it's really their key? The best way to verify an uncertified key is to verify it over some independent channel other than the one you received the key through. One convenient way to tell, if you know this person and would recognize them on the phone, is to call them and verify their key over the telephone. Rather than reading their whole tiresome (ASCII-armored) key to them over the phone, you can just read their key's "fingerprint" to them. To see this fingerprint, use the -kvc command: pgp -kvc userid [keyring] This will display the key with the 16-byte digest of the public key components. Read this 16-byte fingerprint to the key's owner on the phone, while she checks it against her own, using the same -kvc command at her end. You can both verify each other's keys this way, and then you can sign each other's keys with confidence. This is a safe and convenient way to get the key trust network started for your circle of friends. Note that sending a key fingerprint via E-mail is not the best way to verify the key, because E-mail can be intercepted and modified. It's best to use a different channel than the one that was used to send the key itself. A good combination is to send the key via E-mail, and the key fingerprint via a voice telephone conversation. Some people distribute their key fingerprint on their business cards, which looks really cool. For current versions of PGP, the key fingerprint is computed using the MD5 hash function. A future version of PGP will optionally use a new and different hash function, SHA, instead of MD5. If you don't know me, please don't call me to verify my key over the phone-- I get too many calls like that. Since every PGP user has a copy of my public key, no one could tamper with all the copies that are out there. The discrepancy would soon be noticed by someone who checked it from more than one source, and word would soon get out on the Internet. For those of you who want to verify my public key (included in the standard PGP release package), here are the particulars: UserID: "Philip R. Zimmermann " Key Size: 1024 bits; Creation date: 21 May 1993; KeyID: C7A966DD Key fingerprint: 9E 94 45 13 39 83 5F 70 7B E7 D8 ED C4 BE 5A A6 The information printed above conceivably could still be tampered with in the electronic distribution of the PGP User's Guide. But if you read this in the printed version of the manual, available in bookstores from MIT Press, it's a safe bet that it really is my own key's fingerprint. Handling Large Public Keyrings ------------------------------ PGP was originally designed for handling small personal keyrings for keeping all your friends on, like a personal rolodex. A couple hundred keys is a reasonable size for such a keyring. But as PGP has become more popular, people are now trying to add other large keyrings to their own keyring. Sometimes this involves adding thousands of keys to your keyring. PGP, in its present form, cannot perform this operation in a reasonable period of time, while you wait at your keyboard. Not for huge keyrings. You may want to add a huge "imported" keyring to your own keyring, because you are only interested in a few dozen keys on the bigger keyring you are bringing in. If that's all you want from the other keyring, it would be more efficient if you extract the few keys you need from the big foreign keyring, and then add just these few keys to your own keyring. Use the -kx command to extract them from the foreign keyring, specifying the keyring name on the command line. Then add these extracted keys to your own keyring. The real solution is to improve PGP to use advanced database techniques to manage large keyrings efficiently. We are working on this, and should have it done Real Soon Now. Until this happens, you will just have to use smaller keyrings, or be patient. Using PGP as a Unix-style Filter -------------------------------- Unix fans are accustomed to using Unix "pipes" to make two applications work together. The output of one application can be directly fed through a pipe to be read as input to another application. For this to work, the applications must be capable of reading the raw material from "standard input" and writing the finished output to "standard output". PGP can operate in this mode. If you don't understand what this means, then you probably don't need this feature. To use a Unix-style filter mode, reading from standard input and writing to standard output, add the -f option, like so: pgp -feast her_userid outputfile This feature makes it easier to make PGP work with electronic mail applications. When using PGP in filter mode to decrypt a ciphertext file, you may find it useful to use the PGPPASS environmental variable to hold the pass phrase, so that you won't be prompted for it. The PGPPASS feature is explained below. Suppressing Unnecessary Questions: BATCHMODE ---------------------------------------------- With the BATCHMODE flag enabled on the command line, PGP will not ask any unnecessary questions or prompt for alternate filenames. Here is an example of how to set this flag: pgp +batchmode cipherfile This is useful for running PGP non-interactively from Unix shell scripts or MSDOS batch files. Some key management commands still need user interaction even when BATCHMODE is on, so shell scripts may need to avoid them. BATCHMODE may also be enabled to check the validity of a signature on a file. If there was no signature on the file, the exit code is 1. If it had a signature that was good, the exit code is 0. Force "Yes" Answer to Confirmation Questions: FORCE ---------------------------------------------------- This command-line flag makes PGP assume "yes" for the user response to the confirmation request to overwrite an existing file, or when removing a key from the keyring via the -kr command. Here is an example of how to set this flag: pgp +force cipherfile or: pgp -kr +force Smith This feature is useful for running PGP non-interactively from a Unix shell script or MSDOS batch file. PGP Returns Exit Status to the Shell ------------------------------------ To facilitate running PGP in "batch" mode, such as from an MSDOS ".bat" file or from a Unix shell script, PGP returns an error exit status to the shell. An exit status code of zero means normal exit, while a nonzero exit status indicates some kind of error occurred. Different error exit conditions return different exit status codes to the shell. Environmental Variable for Pass Phrase -------------------------------------- Normally, PGP prompts the user to type a pass phrase whenever PGP needs a pass phrase to unlock a secret key. But it is possible to store the pass phrase in an environmental variable from your operating system's command shell. The environmental variable PGPPASS can be used to hold the pass phrase that PGP will attempt to use first. If the pass phrase stored in PGPPASS is incorrect, PGP recovers by prompting the user for the correct pass phrase. For example, on MSDOS, the shell command: SET PGPPASS=zaphod beeblebrox for president would eliminate the prompt for the pass phrase if the pass phrase were indeed "zaphod beeblebrox for president". This dangerous feature makes your life more convenient if you have to regularly deal with a large number of incoming messages addressed to your secret key, by eliminating the need for you to repeatedly type in your pass phrase every time you run PGP. I added this feature because of popular demand. However, this is a somewhat dangerous feature, because it keeps your precious pass phrase stored somewhere other than just in your brain. Even worse, if you are particularly reckless, it may even be stored on a disk on the same computer as your secret key. It would be particularly dangerous and stupid if you were to install this command in a batch or script file, such as the MSDOS AUTOEXEC.BAT file. Someone could come along on your lunch hour and steal both your secret key ring and the file containing your pass phrase. I can't emphasize the importance of this risk enough. If you are contemplating using this feature, be sure to read the sections "Exposure on Multi-user Systems" and "How to Protect Secret Keys from Disclosure" in this volume and in the Essential Topics volume of the PGP User's Guide. If you must use this feature, the safest way to do it would be to just manually type in the shell command to set PGPPASS every time you boot your machine to start using PGP, and then erase it or turn off your machine when you are done. And you should definitely never do it in an environment where someone else may have access to your machine. Someone could come along and simply ask your computer to display the contents of PGPPASS. Sometimes you want to pass the pass phrase into PGP from another application, such as an E-mail package. In some cases, it may not always be desirable to use the PGPPASS variable for that purpose. There is another way to pass your pass phrase into PGP from another application. Use the "-z" command line option. This option is designed primarily for invoking PGP from inside an E-mail package. The pass phrase follows the -z option on the command line. There are risks associated with using this approach, similar to those risks described above for using the PGPPASS variable. Setting Parameters in the PGP Configuration File ================================================ PGP has a number of user-settable parameters that can be defined in a special PGP configuration text file called "config.txt", in the directory pointed to by the shell environmental variable PGPPATH. Having a configuration file enables the user to define various flags and parameters for PGP without the burden of having to always define these parameters in the PGP command line. The filename "config.txt" has been in use for a long time by PGP, but some folks have pointed out that it may be at odds with naming conventions for configuration files for specific operating systems. Accordingly, PGP now tries to open this filename only after first trying to open the file ".pgprc" on Unix platforms, and "pgp.ini" on other platforms, in the same directory that PGP would look for "config.txt". Configuration parameters may be assigned integer values, character string values, or on/off values, depending on what kind of configuration parameter it is. A sample configuration file is provided with PGP, so you can see some examples. In the configuration file, blank lines are ignored, as is anything following the '#' comment character. Keywords are not case-sensitive. Here is a short sample fragment of a typical configuration file: # TMP is the directory for PGP scratch files, such as a RAM disk. TMP = "e:\" # Can be overridden by environment variable TMP. Armor = on # Use -a flag for ASCII armor whenever applicable. # CERT_DEPTH is how deeply introducers may introduce introducers. cert_depth = 3 If some configuration parameters are not defined in the configuration file, or if there is no configuration file, or if PGP can't find the configuration file, the values for the configuration parameters default to some reasonable value. Note that it is also possible to set these same configuration parameters directly from the PGP command line, by preceding the parameter setting with a "+" character. For example, the following two PGP commands produce the same effect: pgp -e +armor=on message.txt smith or: pgp -ea message.txt smith The following is a summary of the various parameters than may be defined in the configuration file. TMP - Directory Pathname for Temporary Files -------------------------------------------- Default setting: TMP = "" The configuration parameter TMP specifies what directory to use for PGP's temporary scratch files. The best place to put them is on a RAM disk, if you have one. That speeds things up quite a bit, and increases security somewhat. If TMP is undefined, the temporary files go in the current directory. If the shell environmental variable TMP is defined, PGP instead uses that to specify where the temporary files should go. LANGUAGE - Foreign Language Selector ------------------------------------ Default setting: LANGUAGE = "en" PGP displays various prompts, warning messages, and advisories to the user on the screen. For example, messages such as "File not found.", or "Please enter your pass phrase:". These messages are normally in English. But it is possible to get PGP to display its messages to the user in other languages, without having to modify the PGP executable program. A number of people in various countries have translated all of PGP's display messages, warnings, and prompts into their native languages. These hundreds of translated message strings have been placed in a special text file called "language.txt", distributed with the PGP release. The messages are stored in this file in English, Spanish, Dutch, German, French, Italian, Russian, Latvian, and Lithuanian. Other languages may be added later. The configuration parameter LANGUAGE specifies what language to display these messages in. LANGUAGE may be set to "en" for English, "es" for Spanish, "de" for German, "nl" for Dutch, "fr" for French, "it" for Italian, "ru" for Russian, "lt3" for Lithuanian, "lv" for Latvian, "esp" for Esperanto. For example, if this line appeared in the configuration file: LANGUAGE = "fr" PGP would select French as the language for its display messages. The default setting is English. When PGP needs to display a message to the user, it looks in the "language.txt" file for the equivalent message string in the selected foreign language and displays that translated message to the user. If PGP can't find the language string file, or if the selected language is not in the file, or if that one phrase is not translated into the selected language in the file, or if that phrase is missing entirely from the file, PGP displays the message in English. To conserve disk space, most foreign translations are not included in the standard PGP release package, but are available separately. MYNAME - Default User ID for Making Signatures ---------------------------------------------- Default setting: MYNAME = "" The configuration parameter MYNAME specifies the default user ID to use to select the secret key for making signatures. If MYNAME is not defined, the most recent secret key you installed on your secret key ring will be used. The user may also override this setting by specifying a user ID on the PGP command line with the -u option. TEXTMODE - Assuming Plaintext is a Text File -------------------------------------------- Default setting: TEXTMODE = off The configuration parameter TEXTMODE is equivalent to the -t command line option. If enabled, it causes PGP to assume the plaintext is a text file, not a binary file, and converts it to "canonical text" before encrypting it. Canonical text has a carriage return and a linefeed at the end of each line of text. This mode will be automatically turned off if PGP detects that the plaintext file contains what it thinks is non-text binary data. If you intend to use PGP primarily for E-mail purposes, you should turn TEXTMODE=ON. For VAX/VMS systems, the current version of PGP defaults TEXTMODE=ON. For further details, see the section "Sending ASCII Text Files Across Different Machine Environments". CHARSET - Specifies Local Character Set for Text Files ------------------------------------------------------ Default setting: CHARSET = NOCONV Because PGP must process messages in many non-English languages with non-ASCII character sets, you may have a need to tell PGP what local character set your machine uses. This determines what character conversions are performed when converting plaintext files to and from canonical text format. This is only a concern if you are in a non-English non-ASCII environment. The configuration parameter CHARSET selects the local character set. The choices are NOCONV (no conversion), LATIN1 (ISO 8859-1 Latin Alphabet 1), KOI8 (used by most Russian Unix systems), ALT_CODES (used by Russian MSDOS systems), ASCII, and CP850 (used by most western European languages on standard MSDOS PCs). LATIN1 is the internal representation used by PGP for canonical text, so if you select LATIN1, no conversion is done. Note also that PGP treats KOI8 as LATIN1, even though it is a completely different character set (Russian), because trying to convert KOI8 to either LATIN1 or CP850 would be futile anyway. This means that setting CHARSET to NOCONV, LATIN1, or KOI8 are all equivalent to PGP. If you use MSDOS and expect to send or receive traffic in western European languages, set CHARSET = "CP850". This will make PGP convert incoming canonical text messages from LATIN1 to CP850 after decryption. If you use the -t (textmode) option to convert to canonical text, PGP will convert your CP850 text to LATIN1 before encrypting it. For further details, see the section "Sending ASCII Text Files Across Different Machine Environments". ARMOR - Enable ASCII Armor Output --------------------------------- Default setting: ARMOR = off The configuration parameter ARMOR is equivalent to the -a command line option. If enabled, it causes PGP to emit ciphertext or keys in ASCII Radix-64 format suitable for transporting through E-mail channels. Output files are named with the ".asc" extension. If you intend to use PGP primarily for E-mail purposes, you should turn ARMOR=ON. For further details, see the section "Sending Ciphertext Through E-mail Channels: Radix-64 Format" in the Essential Topics volume. ARMORLINES - Size of ASCII Armor Multipart Files ------------------------------------------------ Default setting: ARMORLINES = 720 When PGP creates a very large ".asc" radix-64 file for sending ciphertext or keys through the E-mail, it breaks the file up into separate chunks small enough to send through Internet mail utilities. Normally, Internet mailers prohibit files larger than about 50000 bytes, which means that if we restrict the number of lines to about 720, we'll be well within the limit. The file chunks are named with suffixes ".as1", ".as2", ".as3", ... The configuration parameter ARMORLINES specifies the maximum number of lines to make each chunk in a multipart ".asc" file sequence. If you set it to zero, PGP will not break up the file into chunks. Fidonet E-mail files usually have an upper limit of about 32K bytes, so 450 lines would be appropriate for Fidonet environments. For further details, see the section "Sending Ciphertext Through E-mail Channels: Radix-64 Format" in the Essential Topics volume. KEEPBINARY - Keep Binary Ciphertext Files After Decrypting ---------------------------------------------------------- Default setting: KEEPBINARY = off When PGP reads a ".asc" file, it recognizes that the file is in radix-64 format and will convert it back to binary before processing as it normally does, producing as a by-product a ".pgp" ciphertext file in binary form. After further processing to decrypt the ".pgp" file, the final output file will be in normal plaintext form. You may want to delete the binary ".pgp" intermediate file, or you may want PGP to delete it for you automatically. You can still rerun PGP on the original ".asc" file. The configuration parameter KEEPBINARY enables or disables keeping the intermediate ".pgp" file during decryption. For further details, see the section "Sending Ciphertext Through E-mail Channels: Radix-64 Format" in the Essential Topics volume. COMPRESS - Enable Compression ----------------------------- Default setting: COMPRESS = on The configuration parameter COMPRESS enables or disables data compression before encryption. It is used mainly for debugging PGP. Normally, PGP attempts to compress the plaintext before it encrypts it. Generally, you should leave this alone and let PGP attempt to compress the plaintext. COMPLETES_NEEDED - Number of Completely Trusted Introducers Needed ------------------------------------------------------------------ Default setting: COMPLETES_NEEDED = 1 The configuration parameter COMPLETES_NEEDED specifies the minimum number of completely trusted introducers required to fully certify a public key on your public key ring. This gives you a way of tuning PGP's skepticism. For further details, see the section "How Does PGP Keep Track of Which Keys are Valid?" in the Essential Topics volume. MARGINALS_NEEDED - Number of Marginally Trusted Introducers Needed ------------------------------------------------------------------ Default setting: MARGINALS_NEEDED = 2 The configuration parameter MARGINALS_NEEDED specifies the minimum number of marginally trusted introducers required to fully certify a public key on your public key ring. This gives you a way of tuning PGP's skepticism. For further details, see the section "How Does PGP Keep Track of Which Keys are Valid?" in the Essential Topics volume. CERT_DEPTH - How Deep May Introducers Be Nested ----------------------------------------------- Default setting: CERT_DEPTH = 4 The configuration parameter CERT_DEPTH specifies how many levels deep you may nest introducers to certify other introducers to certify public keys on your public key ring. For example, If CERT_DEPTH is set to 1, there may only be one layer of introducers below your own ultimately-trusted key. If that were the case, you would be required to directly certify the public keys of all trusted introducers on your key ring. If you set CERT_DEPTH to 0, you could have no introducers at all, and you would have to directly certify each and every key on your public key ring in order to use it. The minimum CERT_DEPTH is 0, the maximum is 8. For further details, see the section "How Does PGP Keep Track of Which Keys are Valid?" in the Essential Topics volume. BAKRING - Filename for Backup Secret Keyring -------------------------------------------- Default setting: BAKRING = "" All of the key certification that PGP does on your public key ring ultimately depends on your own ultimately-trusted public key (or keys). To detect any tampering of your public key ring, PGP must check that your own key has not been tampered with. To do this, PGP must compare your public key against a backup copy of your secret key on some tamper-resistant media, such as a write-protected floppy disk. A secret key contains all the information that your public key has, plus some secret components. This means PGP can check your public key against a backup copy of your secret key. The configuration parameter BAKRING specifies what pathname to use for PGP's trusted backup copy of your secret key ring. On MSDOS, you could set it to "a:\secring.pgp" to point it at a write-protected backup copy of your secret key ring on your floppy drive. This check is performed only when you execute the PGP -kc option to check your whole public key ring. If BAKRING is not defined, PGP will not check your own key against any backup copy. For further details, see the sections "How to Protect Public Keys from Tampering" and "How Does PGP Keep Track of Which Keys are Valid?" in the Essential Topics volume. PUBRING - Filename for Your Public Keyring ------------------------------------------ Default setting: PUBRING = "$PGPPATH/pubring.pgp" You may want to keep your public keyring in a directory separate from your PGP configuration file in the directory specified by your $PGPPATH environmental variable. You may specify the full path and filename for your public keyring by setting the PUBRING parameter. For example, on an MSDOS system, you might want to keep your public keyring on a floppy disk by: PUBRING = "a:pubring.pgp" This feature is especially handy for specifying an alternative keyring on the command line. SECRING - Filename for Your Secret Keyring ------------------------------------------ Default setting: SECRING = "$PGPPATH/secring.pgp" You may want to keep your secret keyring in a directory separate from your PGP configuration file in the directory specified by your $PGPPATH environmental variable. This comes in handy for putting your secret keyring in a directory or device that is more protected than your public keyring. You may specify the full path and filename for your secret keyring by setting the SECRING parameter. For example, on an MSDOS system, you might want to keep your secret keyring on a floppy disk by: SECRING = "a:secring.pgp" RANDSEED - Filename for Random Number Seed ------------------------------------------ Default setting: RANDSEED = "$PGPPATH/randseed.bin" You may want to keep your random number seed file (for generation of session keys) in a directory separate from your PGP configuration file in the directory specified by your $PGPPATH environmental variable. This comes in handy for putting your random number seed file in a directory or device that is more protected than your public keyring. You may specify the full path and filename for your random seed file by setting the RANDSEED parameter. For example, on an MSDOS system, you might want to keep it on a floppy disk by: RANDSEED = "a:randseed.bin" PAGER - Selects Shell Command to Display Plaintext Output --------------------------------------------------------- Default setting: PAGER = "" PGP lets you view the decrypted plaintext output on your screen (like the Unix-style "more" command), without writing it to a file, if you use the -m (more) option while decrypting. This displays the decrypted plaintext display on your screen one screenful at a time. If you prefer to use a fancier page display utility, rather than PGP's built-in one, you can specify the name of a shell command that PGP will invoke to display your plaintext output file. The configuration parameter PAGER specifies the shell command to invoke to display the file. For example, on MSDOS systems, you might want to use the popular shareware program "list.com" to display your plaintext message. Assuming you have a copy of "list.com", you may set PAGER accordingly: PAGER = "list" However, if the sender specified that this file is for your eyes only, and may not be written to disk, PGP always uses its own built-in display function. For further details, see the section "Displaying Decrypted Plaintext on Your Screen". SHOWPASS - Echo Pass Phrase to User ----------------------------------- Default setting: SHOWPASS = off Normally, PGP does not let you see your pass phrase as you type it in. This makes it harder for someone to look over your shoulder while you type and learn your pass phrase. But some typing-impaired people have problems typing their pass phrase without seeing what they are typing, and they may be typing in the privacy of their own homes. So they asked if PGP can be configured to let them see what they type when they type in their pass phrase. The configuration parameter SHOWPASS enables PGP to echo your typing during pass phrase entry. TZFIX - Timezone Adjustment --------------------------- Default setting: TZFIX = 0 PGP provides timestamps for keys and signature certificates in Greenwich Mean Time (GMT), or Coordinated Universal Time (UTC), which means the same thing for our purposes. When PGP asks the system for the time of day, the system is supposed to provide it in GMT. But sometimes, because of improperly configured MSDOS systems, the system time is returned in US Pacific Standard Time time plus 8 hours. Sounds weird, doesn't it? Perhaps because of some sort of US west-coast jingoism, MSDOS presumes local time is US Pacific time, and pre-corrects Pacific time to GMT. This adversely affects the behavior of the internal MSDOS GMT time function that PGP calls. However, if your MSDOS environmental variable TZ is already properly defined for your timezone, this corrects the misconception MSDOS has that the whole world lives on the US west coast. The configuration parameter TZFIX specifies the number of hours to add to the system time function to get GMT, for GMT timestamps on keys and signatures. If the MSDOS environmental variable TZ is defined properly, you can leave TZFIX=0. Unix systems usually shouldn't need to worry about setting TZFIX at all. But if you are using some other obscure operating system that doesn't know about GMT, you may have to use TZFIX to adjust the system time to GMT. On MSDOS systems that do not have TZ defined in the environment, you should make TZFIX=0 for California, -1 for Colorado, -2 for Chicago, -3 for New York, -8 for London, -9 for Amsterdam. In the summer, TZFIX should be manually decremented from these values. What a mess. It would be much cleaner to set your MSDOS environmental variable TZ in your AUTOEXEC.BAT file, and not use the TZFIX correction. Then MSDOS gives you good GMT timestamps, and will handle daylight savings time adjustments for you. Here are some sample lines to insert into AUTOEXEC.BAT, depending on your time zone: For Los Angeles: SET TZ=PST8PDT For Denver: SET TZ=MST7MDT For Arizona: SET TZ=MST7 (Arizona never uses daylight savings time) For Chicago: SET TZ=CST6CDT For New York: SET TZ=EST5EDT For London: SET TZ=GMT0BST For Amsterdam: SET TZ=MET-1DST For Moscow: SET TZ=MSK-3MSD For Aukland: SET TZ=NZT-13 CLEARSIG - Enable Signed Messages to be Encapsulated as Clear Text ------------------------------------------------------------------ Default setting: CLEARSIG = on Normally, unencrypted PGP signed messages have a signature certificate prepended in binary form. Also, the signed message is compressed, rendering the message unreadable to casual human eyes, even though the message is not actually encrypted. To send this binary data through a 7-bit E-mail channel, radix-64 ASCII armor is applied (see the ARMOR parameter). Even if PGP didn't compress the message, the ASCII armor would still render the message unreadable to human eyes. The recipient must use PGP to strip the armor off and decompress it before reading the message. If the original plaintext message is in text (not binary) form, there is a way to send a signed message through an E-mail channel in such a way that the signed message is not compressed and the ASCII armor is applied only to the binary signature certificate, but not to the plaintext message. The CLEARSIG flag provides this useful feature, making it possible to generate a signed message that can be read with human eyes, without the aid of PGP. Of course, you still need PGP to actually check the signature. The CLEARSIG flag is preset to "on" beginning with PGP version 2.5. To enable the full CLEARSIG behavior, the ARMOR and TEXTMODE flags must also be turned on. Set ARMOR=ON (or use the -a option), and set TEXTMODE=ON (or use the -t option). If your config file has CLEARSIG turned off, you can turn it back on again directly on the command line, like so: pgp -sta +clearsig=on message.txt This message representation is analogous to the MIC-CLEAR message type used in Internet Privacy Enhanced Mail (PEM). It is important to note that since this method only applies ASCII armor to the binary signature certificate, and not to the message text itself, there is some risk that the unarmored message may suffer some accidental molestation while en route. This can happen if it passes through some E-mail gateway that performs character set conversions, or in some cases extra spaces may be added to or stripped from the ends of lines. If this occurs, the signature will fail to verify, which may give a false indication of intentional tampering. But since PEM lives under a similar vulnerability, it seems worth having this feature despite the risks. Beginning with PGP version 2.2, trailing blanks are ignored on each line in calculating the signature for text in CLEARSIG mode. VERBOSE - Quiet, Normal, or Verbose Messages -------------------------------------------- Default setting: VERBOSE = 1 VERBOSE may be set to 0, 1, or 2, depending on how much detail you want to see from PGP diagnostic messages. The settings are: 0 - Display messages only if there is a problem. Unix fans wanted this "quiet mode" setting. 1 - Normal default setting. Displays a reasonable amount of detail in diagnostic or advisory messages. 2 - Displays maximum information, usually to help diagnose problems in PGP. Not recommended for normal use. Besides, PGP doesn't have any problems, right? INTERACTIVE - Ask for Confirmation for Key Adds ----------------------------------------------- Default Setting: INTERACTIVE = off Enabling this mode will mean that if you add a key file containing multiple keys to your key ring, PGP will ask for confirmation for each key before adding it to your key ring. NOMANUAL - Let PGP Generate Keys Without the Manual --------------------------------------------------- Default Setting: NOMANUAL = off It is important that the freeware version of PGP not be distributed without the user documentation, which normally comes with it in the standard release package. This manual contains important information for using PGP, as well as important legal notices. But some people have distributed previous versions of PGP without the manual, causing a lot of problems for a lot of people who get it. To discourage the distribution of PGP without the required documentation, PGP has been changed to require the PGP User's Guide to be found somewhere on your computer (like in your PGP directory) before PGP will let you generate a key pair. However, some users like to use PGP on tiny palmtop computers with limited storage capacity, so they like to run PGP without the documentation present on their systems. To satisfy these users, PGP can be made to relax its requirement that the manual be present, by enabling the NOMANUAL flag on the command line during key generation, like so: pgp -kg +nomanual The NOMANUAL flag can only be set on the command line, not in the config file. Since you must read this manual to learn how to enable this simple override feature, I hope this will still be effective in discouraging the distribution of PGP without the manual. Some people may object to PGP insisting on finding the manual somewhere in the neighborhood to generate a key. They bristle against this seemingly authoritarian attitude. Some people have even modified PGP to defeat this feature, and redistributed their hotwired version to others. That creates problems for me. Before I added this feature, there were maimed versions of the PGP distribution package floating around that lacked the manual. One of them was uploaded to Compuserve, and was distributed to countless users who called me on the phone to ask me why such a complicated program had no manual. It spread out to BBS systems around the country. And a freeware distributor got hold of the package from Compuserve and enshrined it on CD-ROM, distributing thousands of copies without the manual. What a mess. A Peek Under the Hood ===================== Let's take a look at a few internal features of PGP. Random Numbers -------------- PGP uses a cryptographically strong pseudorandom number generator for creating temporary conventional session keys. The seed file for this is called "randseed.bin". It too can be kept in whatever directory is indicated by the PGPPATH environmental variable. If this random seed file does not exist, it is automatically created and seeded with truly random numbers derived from timing your keystroke latencies. This generator reseeds the disk file each time it is used by mixing in new key material partially derived with the time of day and other truly random sources. It uses the conventional encryption algorithm as an engine for the random number generator. The seed file contains both random seed material and random key material to key the conventional encryption engine for the random generator. This random seed file should be at least slightly protected from disclosure, to reduce the risk of an attacker deriving your next or previous session keys. The attacker would have a very hard time getting anything useful from capturing this random seed file, because the file is cryptographically laundered before and after each use. Nonetheless, it seems prudent to at least try to keep it from falling into the wrong hands. If you feel uneasy about trusting any algorithmically derived random number source however strong, keep in mind that you already trust the strength of the same conventional cipher to protect your messages. If it's strong enough for that, then it should be strong enough to use as a source of random numbers for temporary session keys. Note that PGP still uses truly random numbers from physical sources (mainly keyboard timings) to generate long-term public/secret key pairs. PGP's Conventional