Return to pgp_vms.hlp CVS log

Up to [PGP] / pgp / doc

PGP 2.6.3i

! .TH PGP 1 "PGP Version 2.6.3i"
! .\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
! .\" other parms are allowed: see man(7), man(1)
1 PGP
 Pretty Good Privacy encryption system (PGP Version 2.6.3i).

 SYNOPSIS

     $ pgp [options] pgpfile

     $ pgp -e [options] file user

 DOCUMENTATION

 Full documentation path: PGP$LIBRARY:[DOC]
 Read PGPDOC1.TXT and PGPDOC2.TXT before to start using this product.

 "THE BEGINNER'S GUIDE" and the "Frequently Asked Questions" can be found 
 in the same directory, the file names are: PGPBG11.ASC and PGP.FAQ
!
2 Description
 PGP (Pretty Good Privacy) is a public key encryption package to protect
 E-mail and data files. It lets you communicate securely with people
 you've never met, with no secure channels needed for prior exchange of
 keys. It's well featured and fast, with sophisticated key management,
 digital signatures, data compression, and good ergonomic design. If you
 really want to learn how to use it properly, it's best to read the full
 documentation that comes with the system, which is very complete. This
 is a "quick start" guide and reference manual; it is necessarily
 incomplete, and assumes you are already familiar with most of the basic
 concepts, including the concepts behind public key cryptography.
!
2 Terminology
 user id: an ascii string used to identify a user.

    User IDs tend to look like "John Q. Public <[email protected]>"; please
    try sticking to that format. When giving a user id to PGP, you may
    specify any unique (case-insensitive) substring. E.g. john, or
    jqp@xyz.

 pass phrase: the secret string used to conventionally encipher your
              private key. It's important that this be kept secret.

 keyring: a file containing a set of public or secret keys.

    Default names for public and secret rings are "pubring.pgp" and
    "secring.pgp" respectively.

 ascii armor: the ascii radix 64 format PGP uses for transmitting messages
              over channels like E-Mail; similar in concept to uuencoding.
!
2 Command_summary

 To see a quick command usage summary for PGP, just type:

        $ pgp -h

 To encrypt a plaintext file with the recipient's public key:

        $ pgp -e textfile her_userid [other userids]

 To sign a plaintext file with your secret key:

        $ pgp -s textfile [-u your_userid]
 
 To sign a plaintext file with your secret key, and then encrypt it with
 the recipient's public key:

        $ pgp -es textfile her_userid [other userids] [-u your_userid]

 To create a signature certificate that is detached from the document:

        $ pgp -sb textfile [-u your_userid]

 To encrypt a plaintext file with just conventional cryptography, type:

        $ pgp -c textfile

 To decrypt an encrypted file, or to check the signature integrity of a
 signed file:

        $ pgp ciphertextfile [-o plaintextfile]

 To see a quick summary of PGP's key-management commands, just type:

        $ pgp -k

 To generate your own unique public/secret key pair:

        $ pgp -kg

 To add a public or secret key file's contents to your public or secret
 key ring:

        $ pgp -ka keyfile [keyring]

 To remove a key from your public key ring:

        $ pgp -kr userid [keyring]

 To extract (copy) a key from your public or secret key ring:

        $ pgp -kx[a] userid keyfile [keyring]

 To view the contents of your public key ring:

        $ pgp -kv[v] [userid] [keyring]

 To view the "fingerprint" of a public key, to help verify it over the
 telephone with its owner:

        $ pgp -kvc [userid] [keyring]

 To view the contents and check the certifying signatures of your public
 key ring:

        $ pgp -kc [userid] [keyring] 

 To edit the pass phrase for or add a userid to your secret key:

        $ pgp -ke userid [keyring]

 To edit the trust parameters for a public key:

        $ pgp -ke userid [keyring]

 To remove a key or just a userid from your public key ring:

        $ pgp -kr userid [keyring]

 To sign and certify someone else's public key on your public key ring:

        $ pgp -ks her_userid [-u your_userid] [keyring]

 To remove selected signatures from a userid on a keyring:

        $ pgp -krs userid [keyring]


 Command options that can be used in combination with other command
 options (sometimes even spelling interesting words):

 To produce a ciphertext file in ASCII radix-64 format, just add the -a
 option when encrypting or signing a message or extracting a key:

        $ pgp -sea textfile her_userid

        $ pgp -kxa userid keyfile [keyring]

 To wipe out the plaintext file after producing the ciphertext file, just
 add the -w (wipe) option when encrypting or signing a message:

        $ pgp -sew message.txt her_userid

 To specify that a plaintext file contains ASCII text, not binary, and
 should be converted to recipient's local text line conventions, add the
 -t (text) option to other options:

        $ pgp -seat message.txt her_userid

 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

 To specify that the recipient's decrypted plaintext will be shown only on
 her screen and cannot be saved to disk, add the -m option:

        $ pgp -steam message.txt her_userid

 To recover the original plaintext filename while decrypting, add the -p
 option:

        $ pgp -p ciphertextfile

 To use a Unix-style filter mode, reading from standard input and writing
 to standard output, add the -f option:

        $ pgp -feast her_userid <inputfile >outputfile
!
2 The_Config_File
 PGP uses a configuration database that is stored in the file
 "config.txt"; please see the manual for complete details. Blank lines and
 lines beginning with "#" are comments. Options take string, numeric, or
 boolean values. The boolean values are "on" and "off". These options can
 also be specified on the command line, using a syntax such as +armor=on.
 Keywords can be abbreviated to unique prefixes. Keywords are not
 case-sensitive. "=on" is assumed for boolean options if nothing is
 specified. Some highlights:
3 MYNAME
     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 is used. The user may also override this setting by specifying a
 user ID on the PGP command line with the -u option.
3 TEXTMODE
     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 is automatically turned off if PGP detects that the
 plaintext file contains 8-bit binary data. Thus, it is safe to leave
 enabled at all times.
3 ARMOR
     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 tend to use PGP mostly for E-mail, it may be a good idea to
 enable this parameter.
3 ARMORLINES
     ARMORLINES - Size of ASCII Armor Multipart Files

     Default setting:  ARMORLINES = 720

 For large ASCII armor files, PGP splits them into files named
 ".asc1", ".asc2", ".asc3", etc. so as not to choke mailers, which
 typically starts to happen around 50,000 bytes. This specifies the
 number of (64-byte) lines to place in each file. If set to 0, PGP
 will not split ASCII armor files.
3 CLEARSIG
     CLEARSIG - Enable Clear-Signed Output

     Default setting:  CLEARSIG = on

 Normally, a signed and ASCII-armored PGP message is gibberish, even
 though the text is not encrypted. This prevents munging by mailers,
 but requires PGP to simply read the message.

 If CLEARSIG is enabled, then when signing and ASCII-armoring a text
 file, PGP uses a different format that includes the plaintext in
 human-readable form. Lines beginning with "-" are quoted with "\-\ ".
 To cope with some of the stupider mailers in the world, lines
 beginning with "From" are also quoted, and trailing whitespace on
 lines is stripped. PGP will remove the quoting if you use it to
 decrypt the message, but the trailing whitespace is not recovered.
 This is still useful enough to be enabled by default.
3 ENCRYPTTOSELF
     ENCRYPTTOSELF - Add MYNAME to Recipients List

     Default setting:  ENCRYPTTOSELF = off

 If this is emabled, MYNAME will be implcitly added to the list of
 recipients for any message you encrypt with a public key. Since in
 this case, MYNAME is looked up in the public keyring, it is important
 that it unambiguously specify the right key.
3 LANGUAGE
     LANGUAGE - Language To Use

     Default setting:  LANGUAGE = en

 If you want to use a different language, and translations are in the
 language.txt file, setting this option will cause PGP's messages to
 appear in a different language. If a translation for a message is not
 available, it appears in english.

 If you look at the supplied language.txt file, the format should be
 obvious.
3 CHARSET
     CHARSET - Character Set

     Default setting:  CHARSET = noconv

 PGP tries to translate all text-mode messages into the ISO Latin-1
 alphabet, or the KOI-8 alphabet for cyrillic alphabets. This setting
 indicates the native character set, so PGP can do the translation.
 Options are noconv, latin1 or koi8, indicating that no translation
 should be done; cp850, indicating that IBM PC code page 850 mappings
 should be used; ascii, indicating that a minimal ASCII subset should
 be used; and alt_codes, indicating that the IBM PC alt codes should
 be used for the cyrillic alphabet.
3 KEEPBINARY
     KEEPBINARY - Preserve Intermediate .pgp File

     Default setting:  KEEPBINARY = off

 If KEEPBINARY is enabled, then PGP will produce a .pgp file in
 addition to a .asc file when ASCII armor is enabled.
3 TMP
     TMP - Temporary file directory

     Default setting:  TMP = ""

 PGP produces temporary files while decrypting a message. This is the
 directory they are stored in. If not specified in the config file,
 the environment variable TMP is used, or the current directory. It
 helps security somewhat if this is not a publicly-readable directory.
 A local file system is also a good idea.
3 COMPRESS
     COMPRESS - Compress Plaintext Before Encrypting

     Default setting:  COMPRESS = on

 PGP usually compresses the plaintext before encrypting it, so it will
 have less to encrypt and the file you send will be smaller. It also
 makes cryptanalysis harder. This is usually only turned off for
 debugging purposes.
3 PAGER
     PAGER - Select Shell Command to Display Pager Output

     Default setting:  PAGER = ""

 If set, PGP uses this program to view files when the -m option is
 specified. By default, PGP uses a simple builtin pager.
3 SHOWPASS
     SHOWPASS - Echo Pass Phrase During Entry

     Default setting:  SHOWPASS = off

 If someone is unable to type a long pass phrase reliably without
 seeing it, this can be turned on, at the cost of security.
3 INTERACTIVE
     INTERACTIVE - Prompt Before Adding Each Key

     Default setting:  INTERACTIVE = off

 By default, when given a file containing new keys, PGP asks if you
 would like to add them to your public key ring. Since adding keys
 does not imply that you trust them, adding more just wakes up space.
 If this option is set, PGP asks about each key in a key file.
3 VERBOSE
     VERBOSE - Level of Detail Printed

     Default setting:  VERBOSE = 1

 When set to 0, PGP only prints messages that are necessary or
 indicate an error. When set to 2, PGP prints a significant amount of
 debugging information describing what it's doing. Values above 2 have
 no effect.
3 PUBRING
     PUBRING - Public Key Ring Location

     Default setting:  PUBRING = $PGPPATH/pubring.pgp

 This is the path name to the public key ring to use.
3 SECRING
     SECRING - Secret Key Ring Location

     Default setting:  SECRING = $PGPPATH/secring.pgp

 This is the path name to the secret key ring to use.
3 BAKRING
     BAKRING - Backup Secret Key Ring

     Default setting:  BAKRING = ""

 If this is set, when checking your key ring (pgp -kc), PGP will
 compare the normal secret key ring against the given backup copy,
 usually kept on write-protected removable media. This is to protect
 against wholesale modifications to your key rings in a spoofing
 attack.
3 RANDSEED
     RANDSEED - Random Number Seed File

     Default setting:  RANDSEED = $PGPPATH/randseed.bin

 This is the path to a random seed file which is part of PGP's random
 number generation algorithm, used to generate session keys. While PGP
 goes to great lengths to use every available source of randomness in
 generating session keys, this file is part of the process and
 protecting it from disclosure is desirable.
3 COMMENT
     COMMENT - ASCII Armor Comment

     Default setting:  COMMENT = ""

 If set to a non-empty string, the value of this variable is printed
 in the header of ASCII armor files, preceded by "Comment: ".
3 LEGAL_KLUDGE
     LEGAL_KLUDGE - Incompatibility with PGP versions prior to 2.6

     Default setting:  LEGAL_KLUDGE = on

 If set, PGP will generate keys and messages in a new format that
 cannot be read by PGP 2.5 and earlier versions.
!
2 Key_certification
 PGP employs a system where users specify trusted users who may sign other
 people's public keys. It is important that you understand how this
 mechanism works; a full description is in the manual. 

 Important: The manual also describes how to generate and send a "key
            compromise" certificate that tells readers that your private
            key has been compromised. If your key has been compromised,
            please read the manual section on key compromise certificates
            and how to create them; the faster you send out a key
            compromise certificate, the smaller the window of opportunity
            for "bad guys" to send forged messages.
!
2 Important_Hints
 PGP automatically tries compressing your input file; there is little
 point in precompressing input for transmission.

 PGP "ascii armor" is only needed on the outer transmitted message; as an
 example, if you are, say, sending a public key to someone else and you
 are for some reason signing it, simply armor the outer message; it's
 better to sign the binary form of the key.
!
2 Foreign_Languages
 PGP is easily customized for foreign language help and error messages;
 it has been translated into a number of non-english languages. See the
 manual for details on the file "language.txt".
!
2 Environment
 PGP uses several special files for its purposes, such as your standard
 key ring files "pubring.pgp" and "secring.pgp", the random number seed
 file "randseed.bin", the PGP configuration file "config.txt", and the
 foreign language string translation file "language.txt". These special
 files can be kept in any directory, by setting the environment variable
 "PGPPATH" to the desired pathname. If PGPPATH remains undefined, these
 special files are assumed to be in the current directory.

 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 environment variable from your operating system's command
 shell. The environment variable PGPPASS can be used to hold the pass
 phrase that PGP attempts to use first. If the pass phrase stored in
 PGPPASS is incorrect, PGP recovers by prompting the user for the correct
 pass phrase. 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.
 This is a very dangerous feature; on UNIX it is trivial to read someone
 else's environment using the ps(1) command. If you are contemplating
 using this feature, be sure to read the sections "How to Protect Secret
 Keys from Disclosure" and "Exposure on Multi-user Systems" in the full
 PGP manual.

 If the environment variable PGPPASSFD is defined, it must have a numeric
 value, which PGP uses as a file descriptor number to read a pass phrase
 from. This is done before anything else, so it can be combined with an
 input file on standard input. This is mainly for use by shell scripts,
 since under Unix it is difficult to read the contents of other people's
 pipes.
!
2 Return_Value
 PGP returns a 0 to the shell on success, and a nonzero error code on
 failure. See the source code for details on nonzero status return values.
!
2 Files
  *.pgp                           ciphertext, signature, or key file
  *.asc                           ascii armor file
  /usr/local/lib/config.txt       system-wide configuration file
  $PGPPATH/config.txt             per-user configuration file
  $PGPPATH/pubring.pgp            public key ring
  $PGPPATH/secring.pgp            secret key ring
  $PGPPATH/randseed.bin           random number seed file
  /usr/local/lib/pgp/language.txt
  $PGPPATH/language.txt           foreign language translation file
  /usr/local/lib/pgp/pgp.hlp
  $PGPPATH/pgp/pgp.hlp            online help text file
  /usr/local/lib/pgp/pgpkey.hlp
  $PGPPATH/pgp/pgpkey.hlp         online key-management help text file
!
2 Note
 The manual is really good, and it's really important in the long run that
 you read it. PGP may be an unpickable lock, but you have to put in in the
 door properly to keep out intruders. So read the manual and find out how!
!
2 Caveats
 It is impossible to overemphasize the importance of protecting your
 secret key. Anyone gaining access to it can forge messages from you or
 read mail addressed to you. Be very cautious in using PGP on any
 multi-user unix system.

 PGP is believed by its authors to be the most secure cryptographic
 software available to the public when used as directed, but then again
 everyone always claims their pet encryption system is secure. Read the
 section in the manual on "Trusting Snake Oil" and the section on
 "Vulnerabilities" for caveats.
!
2 Diagnostics

 Mostly self explanatory.
!
2 Bugs
 PGP was initially written for the PC, and behaves very PCish. In
 particular, its automagic file selection, file extensions, and the like
 all make it somewhat alien in the UNIX environment.

 This man page needs to be updated to reflect all the latest features.
!
2 Authors
 Originally written by Philip R. Zimmermann. Later augmented by a cast of
 thousands.
!
2 Legal_Restrictions
 PGP 2.6.3i is freeware, and may be used for non-commercial purposes only.
 This version of PGP is illegal to use within the USA but is fine
 elsewhere in the world. US users should get a copy of MIT PGP 2.6.2
 instead, or purchase the commercial version 2.7.1 from ViaCrypt.

 For detailed information on PGP licensing, distribution, copyrights,
 patents, trademarks, liability limitations, and export controls, see the
 "Legal Issues" section in the "PGP User's Guide, Volume II: Special
 Topics".

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.