Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PGP(1)			    General Commands Manual			PGP(1)

       pgp - Pretty Good Privacy encryption system

       pgp [options] pgpfile

       pgp -e [options]	file user ...

       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.

       user id:	an ascii string	used to	identify a user.   User	 IDs  tend  to
       look  like  "John  Q. Public <>";	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"

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

   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 ...

       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 ...	[-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  op-
       tions (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
       pgp -p ciphertextfile

       To  use a Unix-style filter mode, reading from standard input and writ-
       ing to standard output, add the -f option:
       pgp -feast her_userid <inputfile	>outputfile

   The Config File
       PGP uses	a configuration	database that is  stored  in  the  file	 "con-
       fig.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 op-
       tions 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	 noth-
       ing is specified.  Some highlights:

       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  de-
       fined, 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.

       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" be-
       fore encrypting it.  Canonical text has a carriage return and  a	 line-
       feed 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.

       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  en-
       able this parameter.

       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.

       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.

       ENCRYPTTOSELF - Add MYNAME to Recipients	List

       Default setting:	 ENCRYPTTOSELF = off

       If this is emabled, MYNAME will be implcitly added to the list  of  re-
       cipients	 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.

       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 ap-
       pear  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 ob-

       CHARSET - Character Set

       Default setting:	 CHARSET = noconv

       PGP  tries to translate all text-mode messages into the ISO Latin-1 al-
       phabet, or the KOI-8 alphabet for cyrillic alphabets.  This setting in-
       dicates	the  native character set, so PGP can do the translation.  Op-
       tions 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.

       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.

       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  lo-
       cal file	system is also a good idea.

       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	debug-
       ging purposes.

       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 spec-
       ified.  By default, PGP uses a simple builtin pager.

       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.

       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.

       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.

       PUBRING - Public	Key Ring Location

       Default setting:	 PUBRING = $PGPPATH/pubring.pgp

       This is the path	name to	the public key ring to use.

       SECRING - Secret	Key Ring Location

       Default setting:	 SECRING = $PGPPATH/secring.pgp

       This is the path	name to	the secret key ring to use.

       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	whole-
       sale modifications to your key rings in a spoofing attack.

       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 protect-
       ing it from disclosure is desirable.

       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: ".

       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.

   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.

   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.

   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".

       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	incom-
       ing  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 nu-
       meric 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.

       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 val-

       *.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
       $PGPPATH/language.txt	      foreign language translation file
       $PGPPATH/pgp/pgp.hlp	      online help text file
       $PGPPATH/pgp/pgpkey.hlp	      online key-management help text file

       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!

       It is impossible	to overemphasize the importance	of protecting your se-
       cret 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 "Vul-
       nerabilities" for caveats.

       Mostly self explanatory.

       PGP was initially written for the PC, and behaves very PCish.  In  par-
       ticular,	 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.

       Originally written by Philip R. Zimmermann.  Later augmented by a  cast
       of thousands.

       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 in-
       stead, 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

			      PGP Version 2.6.3i			PGP(1)


Want to link to this manual page? Use this URL:

home | help