Return to pgp.1 CVS log

Up to [PGP] / pgp / doc

Annotation of pgp/doc/pgp.1, revision 1.1

1.1     ! root        1: .TH PGP 1
        !             2: .\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
        !             3: .\" other parms are allowed: see man(7), man(1)
        !             4: .SH NAME
        !             5: pgp \- Pretty Good Privacy encryption system
        !             6: .\" denote multiple entry points thus; makewhatis(8) will catch them
        !             7: .SH SYNOPSIS
        !             8: .B pgp 
        !             9: [options] pgpfile
        !            10: .PP
        !            11: .B PGP \-e
        !            12: [options]
        !            13: file user .\|.\|.
        !            14: .SH "DESCRIPTION"
        !            15: 
        !            16: PGP (Pretty Good Privacy) is a public key encryption package to
        !            17: protect E-mail and data files.  It lets you communicate securely with
        !            18: people you've never met, with no secure channels needed for prior
        !            19: exchange of keys.  It's well featured and fast, with sophisticated
        !            20: key management, digital signatures, data compression, and good
        !            21: ergonomic design.  If you really want to learn how to use it
        !            22: properly, it's best to read the full documentation that comes with
        !            23: the system, which is very complete.  This is a "quick start" guide
        !            24: and reference manual; it is necessarily incomplete, and assumes you
        !            25: are already familiar with most of the basic concepts, including the
        !            26: concepts behind public key cryptography.
        !            27: 
        !            28: .SS "Terminology"
        !            29: 
        !            30: user id: an ascii string used to identify a user.  User IDs tend to
        !            31: look like "John Q. Public <[email protected]>"; please try sticking to
        !            32: that format.  When giving a user id to PGP, you may specify any unique
        !            33: (case-insensitive) substring.  E.g. john, or jqp@xyz.
        !            34: 
        !            35: pass phrase: the secret string used to conventionally encypher your
        !            36: private key; it's important that this be kept secret.
        !            37: 
        !            38: keyring: a file containing a set of public or secret keys.  Default
        !            39: names for public and secret rings are "pubring.pgp" and "secring.pgp"
        !            40: respectively.
        !            41: 
        !            42: ascii armor: the ascii radix 64 format PGP uses for transmitting
        !            43: messages over channels like E-Mail; similar in concept to uuencoding.
        !            44: 
        !            45: .SS "Command summary"
        !            46: 
        !            47: To see a quick command usage summary for PGP, just type:
        !            48:         pgp -h
        !            49: 
        !            50: To encrypt a plaintext file with the recipient's public key:
        !            51:         pgp -e textfile her_userid [his_userid .\|.\|.]
        !            52:       
        !            53: To sign a plaintext file with your secret key:
        !            54:         pgp -s textfile [-u your_userid]
        !            55:       
        !            56: To sign a plaintext file with your secret key, and then encrypt it 
        !            57: with the recipient's public key:
        !            58:         pgp -es textfile her_userid [his_userid .\|.\|.] [-u your_userid]
        !            59:       
        !            60: To create a signature certificate that is detached from the document:
        !            61:         pgp -sb textfile [-u your_userid]
        !            62:       
        !            63: To encrypt a plaintext file with just conventional cryptography, type:
        !            64:         pgp -c textfile
        !            65:       
        !            66: To decrypt an encrypted file, or to check the signature integrity of a
        !            67: signed file:
        !            68:         pgp ciphertextfile [-o plaintextfile]
        !            69:      
        !            70: To generate your own unique public/secret key pair:
        !            71:         pgp -kg
        !            72:       
        !            73: To add a public or secret key file's contents to your public or
        !            74: secret key ring:
        !            75:         pgp -ka keyfile [keyring]
        !            76:       
        !            77: To remove a key from your public key ring:
        !            78:         pgp -kr userid [keyring]
        !            79:       
        !            80: To extract (copy) a key from your public or secret key ring:
        !            81:         pgp -kx userid keyfile [keyring]
        !            82:    or:  pgp -kxa userid keyfile [keyring]
        !            83:       
        !            84: To view the contents of your public key ring:
        !            85:         pgp -kv[v] [userid] [keyring] 
        !            86:       
        !            87: To view the "fingerprint" of a public key, to help verify it over 
        !            88: the telephone with its owner:
        !            89:      pgp -kvc [userid] [keyring]
        !            90: 
        !            91: To view the contents and check the certifying signatures of your 
        !            92: public key ring:
        !            93:         pgp -kc [userid] [keyring] 
        !            94:       
        !            95: To edit the userid or pass phrase for your secret key:
        !            96:         pgp -ke userid [keyring]
        !            97:       
        !            98: To edit the trust parameters for a public key:
        !            99:         pgp -ke userid [keyring]
        !           100:       
        !           101: To remove a key or just a userid from your public key ring:
        !           102:         pgp -kr userid [keyring]
        !           103: 
        !           104: To sign and certify someone else's public key on your public key ring:
        !           105:         pgp -ks her_userid [-u your_userid] [keyring]
        !           106:       
        !           107: To remove selected signatures from a userid on a keyring:
        !           108:         pgp -krs userid [keyring]
        !           109:       
        !           110:       
        !           111: Command options that can be used in combination with other command
        !           112: options (sometimes even spelling interesting words!):
        !           113:       
        !           114: To produce a ciphertext file in ASCII radix-64 format, just add the
        !           115: -a option when encrypting or signing a message or extracting a key:
        !           116:         pgp -sea textfile her_userid
        !           117:    or:  pgp -kxa userid keyfile [keyring]
        !           118:       
        !           119: To wipe out the plaintext file after producing the ciphertext file,
        !           120: just add the -w (wipe) option when encrypting or signing a message:
        !           121:         pgp -sew message.txt her_userid
        !           122:       
        !           123: To specify that a plaintext file contains ASCII text, not binary, and
        !           124: should be converted to recipient's local text line conventions, add
        !           125: the -t (text) option to other options:
        !           126:         pgp -seat message.txt her_userid
        !           127:       
        !           128: To view the decrypted plaintext output on your screen (like the
        !           129: Unix-style "more" command), without writing it to a file, use 
        !           130: the -m (more) option while decrypting:
        !           131:         pgp -m ciphertextfile
        !           132:       
        !           133: To specify that the recipient's decrypted plaintext will be shown
        !           134: ONLY on her screen and cannot be saved to disk, add the -m option:
        !           135:         pgp -steam message.txt her_userid
        !           136:       
        !           137: To recover the original plaintext filename while decrypting, add 
        !           138: the -p option:
        !           139:         pgp -p ciphertextfile
        !           140:       
        !           141: To use a Unix-style filter mode, reading from standard input and
        !           142: writing to standard output, add the -f option:
        !           143:         pgp -feast her_userid <inputfile >outputfile
        !           144:       
        !           145: 
        !           146: .SS "The Config File"
        !           147: 
        !           148: PGP uses a fairly complete configuration database that is stored in
        !           149: the file "config.txt"; please see the manual for complete details.
        !           150: Some highlights:
        !           151: 
        !           152: MYNAME - Default User ID for Making Signatures
        !           153:       
        !           154: Default setting:  MYNAME = ""
        !           155:       
        !           156: The configuration parameter MYNAME specifies the default user ID to
        !           157: use to select the secret key for making signatures.  If MYNAME is not
        !           158: defined, the most recent secret key you installed on your secret key
        !           159: ring is used.  The user may also override this setting by
        !           160: specifying a user ID on the PGP command line with the -u option.
        !           161: 
        !           162: TEXTMODE - Assuming Plaintext is a Text File
        !           163:       
        !           164: Default setting:  TEXTMODE = off
        !           165:       
        !           166: The configuration parameter TEXTMODE is equivalent to the -t command
        !           167: line option.  If enabled, it causes PGP to assume the plaintext is a
        !           168: text file, not a binary file, and converts it to "canonical text"
        !           169: before encrypting it.  Canonical text has a carriage return and a
        !           170: linefeed at the end of each line of text.
        !           171:       
        !           172: This mode is automatically turned off if PGP detects that the
        !           173: plaintext file contains 8-bit binary data.
        !           174:       
        !           175: ARMOR - Enable ASCII Armor Output
        !           176:       
        !           177: Default setting:  ARMOR = off
        !           178:       
        !           179: The configuration parameter ARMOR is equivalent to the -a command
        !           180: line option.  If enabled, it causes PGP to emit ciphertext or keys in
        !           181: ASCII Radix-64 format suitable for transporting through E-mail
        !           182: channels.  Output files are named with the ".asc" extension.
        !           183:       
        !           184: If you tend to use PGP mostly for E-mail, it may be a good idea to
        !           185: enable this parameter.
        !           186: 
        !           187: KEEPBINARY - Preserve Internediate .pgp File
        !           188: 
        !           189: Default setting:  KEEPBINARY = off
        !           190: 
        !           191: If KEEPBINARY is enabled, then PGP will produce a .pgp file in addition
        !           192: to a .asc file when ASCII armor is enabled.
        !           193: 
        !           194: COMPRESS - Compress Plaintext Before Encrypting
        !           195: 
        !           196: Default setting:  COMPRESS = on
        !           197: 
        !           198: PGP usually compresses the plaintext before encrypting it, so it will
        !           199: have less to encrypt and the file you send will be smaller.  This is
        !           200: usually only turned off for debugging purposes.
        !           201: 
        !           202: SHOWPASS - Echo Pass Phrase During Entry
        !           203: 
        !           204: Default setting:  SHOWPASS = off
        !           205: 
        !           206: If someone is unable to type a long pass phrase reliably without seeing it,
        !           207: this can be turned on, at the cost of security.
        !           208: 
        !           209: INTERACTIVE - Prompt Before Adding Each Key
        !           210: 
        !           211: Default setting:  INTERACTIVE = off
        !           212: 
        !           213: By default, when given a file containing new keys, PGP asks if you would
        !           214: like to add them to your public key ring.  Since adding keys does not
        !           215: imply that you trust them, adding more just wakes up space.  If this
        !           216: option is set, PGP asks about each key in a key file.
        !           217: 
        !           218: VERBOSE - Level of Detail Printed
        !           219: 
        !           220: Default setting:  VERBOSE = 1
        !           221: 
        !           222: When set to 0, pgp only prints messages that are necessary or indicate an
        !           223: error.  When set to 2, PGP prints a significant amount of debugging
        !           224: information describing what it's doing.  Values above 2 have no effect.
        !           225: 
        !           226: .SS "Key certification"
        !           227: 
        !           228: PGP employs a system where users specify trusted users who may sign
        !           229: other people's public keys.  It is important that you understand how
        !           230: this mechanism works; a full description is in the manual. 
        !           231: 
        !           232: IMPORTANT: The manual also describes how to generate and send a "key
        !           233: compromise" certificate that tells readers that your private key has
        !           234: been compromised.  If your key has been compromised, please read the
        !           235: manual section on key compromise certificates and how to create them;
        !           236: the faster you send out a key compromise certificate, the smaller the
        !           237: window of opportunity for "bad guys" to send forged messages.
        !           238: 
        !           239: .SS "Important Hints"
        !           240: 
        !           241: PGP automatically tries compressing your input file; there is no point
        !           242: in precompressing input for transmission.
        !           243: 
        !           244: PGP "ascii armor" is only needed on the outer transmitted message; as
        !           245: an example, if you are, say, sending a public key to someone else and
        !           246: you are for some reason signing it, simply armor the outer message;
        !           247: it's better to sign the binary form of the key.
        !           248: 
        !           249: .SS "Foreign Languages"
        !           250: 
        !           251: PGP is easily customized for foreign language help and error
        !           252: messages; it has been translated into 10 European languages.  See the
        !           253: manual for details on the file "language.txt".
        !           254: 
        !           255: .SH ENVIRONMENT
        !           256: 
        !           257: PGP uses several special files for its purposes, such as your standard
        !           258: key ring files "pubring.pgp" and "secring.pgp", the random number seed
        !           259: file "randseed.bin", the PGP configuration file "config.txt", and the
        !           260: foreign language string translation file "language.txt".  These
        !           261: special files can be kept in any directory, by setting the environment
        !           262: variable "PGPPATH" to the desired pathname.  If PGPPATH remains
        !           263: undefined, these special files are assumed to be in the current
        !           264: directory.
        !           265: 
        !           266: Normally, PGP prompts the user to type a pass phrase whenever PGP
        !           267: needs a pass phrase to unlock a secret key.  But it is possible to
        !           268: store the pass phrase in an environment variable from your operating
        !           269: system's command shell.  The environmental variable PGPPASS can be
        !           270: used to hold the pass phrase that PGP attempts to use first.  If
        !           271: the pass phrase stored in PGPPASS is incorrect, PGP recovers by
        !           272: prompting the user for the correct pass phrase.  This dangerous
        !           273: feature makes your life more convenient if you have to regularly deal
        !           274: with a large number of incoming messages addressed to your secret key,
        !           275: by eliminating the need for you to repeatedly type in your pass phrase
        !           276: every time you run PGP.  THIS IS A VERY DANGEROUS FEATURE; on UNIX it
        !           277: is trivial to read someone else's environment using the ps(1) command.
        !           278: If you are contemplating using this feature, be sure to read the
        !           279: sections "How to Protect Secret Keys from Disclosure" and "Exposure on
        !           280: Multi-user Systems" in the full PGP manual.
        !           281: 
        !           282: .SH "RETURN VALUE"
        !           283: 
        !           284: PGP returns a 0 to the shell on success, and a nonzero error code on
        !           285: failure.  See the source code for details on nonzero status return
        !           286: values.
        !           287: 
        !           288: .SH FILES
        !           289: .br
        !           290: .nf
        !           291: .\" set tabstop to longest possible filename, plus a wee bit
        !           292: .ta \w'/usr/lib/perl/getopts.pl   'u
        !           293: *.pgp  ciphertext, signature, or key file
        !           294: *.asc  ascii armor file
        !           295: pubring.pgp    public key ring
        !           296: secring.pgp    secret key ring
        !           297: language.txt   foreign language string translation file
        !           298: config.txt     configuration file
        !           299: pgp.hlp        online help text file
        !           300: 
        !           301: .SH NOTE
        !           302: The manual is really good, and it's really important in the long run
        !           303: that you read it.  It may not be important to read the fine print on
        !           304: a box of breakfast cereal, but it may be crucial to read the label of
        !           305: a prescription drug.  Cryptography software is like pharmaceuticals--
        !           306: so read the manual!
        !           307: 
        !           308: .SH CAVEATS
        !           309: 
        !           310: It is impossible to overemphasize the importance of protecting your
        !           311: secret key.  Anyone gaining access to it can forge messages from you or
        !           312: read mail addressed to you.  Be EXTREMELY cautious in using PGP on any
        !           313: multi-user unix system.
        !           314: 
        !           315: PGP is believed by its authors to be secure when used as directed, but
        !           316: then again everyone always claims their pet encryption system is
        !           317: secure.  Read the section in the manual on "Trusting Snake Oil" and the 
        !           318: section on "Vulnerabilities" for caveats.
        !           319: 
        !           320: .SH DIAGNOSTICS
        !           321: 
        !           322: Mostly self explanatory.
        !           323: 
        !           324: .SH BUGS
        !           325: 
        !           326: PGP was initially written for the PC, and behaves very PCish.  In
        !           327: particular, its automagic file selection, file extensions, and the
        !           328: like all make it somewhat alien in the UNIX environment.
        !           329: 
        !           330: .SH AUTHORS
        !           331: 
        !           332: Originally written by Philip R. Zimmermann.  Later augmented by a cast
        !           333: of thousands, especially including Hal Finney, Branko Lankester, and
        !           334: Peter Gutmann.
        !           335: 
        !           336: .SH "LEGAL RESTRICTIONS"
        !           337: 
        !           338: For detailed information on PGP licensing, distribution, copyrights,
        !           339: patents, trademarks, liability limitations, and export controls, see
        !           340: the "Legal Issues" section in the "PGP User's Guide, Volume II: 
        !           341: Special Topics".
        !           342: 
        !           343: PGP uses a public key algorithm claimed by U.S. patent #4,405,829. 
        !           344: The exclusive rights to this patent are held by a California company
        !           345: called Public Key Partners, and you may be infringing this patent if
        !           346: you use PGP in the USA.  This is explained in the PGP User's Guide, 
        !           347: Volume II.
        !           348: 
        !           349: PGP is "guerrilla" freeware, and the authors don't mind if you
        !           350: distribute it widely.  Just don't ask Philip Zimmermann to send you a
        !           351: copy.  Instead, you can get it yourself from many BBS systems and a
        !           352: number of Internet FTP sites.  
        !           353: 
        !           354: 

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