PGP Command Line User's Guide 9.5.2 Instruction Manual 952 Users En

User Manual: Command Line - 9.5.2 - Instruction Manual User Guide for PGP Command Line Software, Free Instruction Manual

Open the PDF directly: View PDF PDF.
Page Count: 276 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Rest SecuredTM
December 2006
PGP® Command Line
User’s Guide
Version Information
PGP Command Line 9.5.2 Users Guide. Released December 2006.
Copyright Information
Copyright © 1991–2006 by PGP Corporation. All Rights Reserved. No part of this document can be reproduced or transmitted
in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of PGP
Corporation.
Trademark Information
“PGP”, “Pretty Good Privacy”, and the PGP logo are registered trademarks and “Rest Secured” is a trademark of PGP
Corporation in the U.S. and other countries. “IDEA” is a trademark of Ascom Tech AG. “Windows” is a registered trademark
of Microsoft Corporation. “Red Hat” and “Red Hat Linux” are trademarks or registered trademarks of Red Hat, Inc. “Linux” is
a registered trademark of Linus Torvalds. “Solaris” is a trademark or registered trademark of Sun Microsystems, Inc. “AIX” is
a trademark or registered trademark of International Business Machines Corporation. “HP-UX” is a trademark or registered
trademark of Hewlett-Packard Company. “Mac OS X” is a trademark or registered trademark of Apple Computer Corporation.
All other registered and unregistered trademarks in this document are the sole property of their respective owners.
Licensing and Patent Information
The IDEA cipher described in U.S. patent number 5,214,703 is licensed from Ascom Tech AG. The CAST algorithm is licensed
from Northern Telecom, Ltd. PGP Corporation has secured a license to the patent rights contained in the patent application
Serial Number 10/655,563 by The Regents of the University of California, entitled Block Cipher Mode of Operations for
Constructing a Wide-blocksize block Cipher from a Conventional Block Cipher. PGP Corporation may have patents and/or
pending patent applications covering subject matter in this software or its documentation; the furnishing of this software or
documentation does not give you any license to these patents.
Acknowledgments
The Zip and ZLib compression code in PGP Command Line was created by Mark Adler and Jean-Loup Gailly; the Zip code is
used with permission from the free Info-ZIP implementation. The BZip2 compression code in PGP Command Line was created
by Julian Seward.
Export Information
Export of this software and documentation may be subject to compliance with the rules and regulations promulgated from
time to time by the Bureau of Export Administration, U.S. Department of Commerce, which restrict the export and re-export of
certain products and technical data.
Limitations
The software provided with this documentation is licensed to you for your individual use under the terms of the End User
License Agreement provided with the software. The information in this document is subject to change without notice. PGP
Corporation does not warrant that the information meets your requirements or that the information is free of errors. The
information may include technical inaccuracies or typographical errors. Changes may be made to the information and
incorporated in new editions of this document, if and when made available by PGP Corporation.
About PGP Corporation
Recognized worldwide as a leader in enterprise encryption technology, PGP Corporation develops, markets, and supports
products used by more than 30,000 enterprises, businesses, and governments worldwide, including 90% of the Fortune® 100
and 75% of the Forbes® International 100. PGP products are also used by thousands of individuals and cryptography experts
to secure proprietary and confidential information. During the past 15 years, PGP technology has earned a global reputation for
standards-based, trusted security products. It is the only commercial security vendor to publish source code for peer review.
The unique PGP encryption product suite includes PGP Universal—an automatic, self-managing, network-based solution for
enterprises—as well as desktop, mobile, FTP/batch transfer, and SDK solutions. Contact PGP Corporation at www.pgp.com or
+1 650 319 9000.
iii
Contents
1 PGP Command Line Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Important Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2 Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Installing on AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Installing on HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Installing on Mac OS X. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Installing on Red Hat Enterprise Linux or Fedora Core . . . . . . . . . . . . . . . . 18
Installing on Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Installing on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3 Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
License Recovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Using a License Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Using a License Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Re-Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Through a Proxy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4 The Command-Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Flags and Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Standard Input, Output, and Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Specifying a Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
‘Secure’ Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
5 First Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Creating Your Keypair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Protecting Your Private Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Distributing Your Public Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Getting the Public Keys of Others . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Verifying Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
PGP Command Line User’s Guide Contents
iv
6 Cryptographic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
7 Key Listings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
8 Working with Keyservers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
9 Managing Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
10 Miscellaneous Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
11 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Boolean Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Integer Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Enumeration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
String Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
List Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
File Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
A Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Basic Key List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Detailed Key List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Key List in XML Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Detailed Signature List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
B Usage Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Secure Off-Site Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
PGP Command Line and PGP Desktop . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Compression Saves Money . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Surpasses Legal Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
C Quick Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
PGP Command Line User’s Guide Contents
v
Configuration File Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
D Command Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
E Codes and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Messages Without Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Messages With Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Exit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
F Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
G Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
PGP Command Line User’s Guide Contents
vi
7
1PGP Command Line Basics
Getting Started with PGP Command Line
This chapter describes some important PGP Command Line concepts and gives you a
high-level overview of the things you need to do to set up and use PGP Command Line.
Important Concepts
The following concepts are important for you to understand:
PGP Command Line: A software product from PGP Corporation that automates the
processes of encrypting/signing, decrypting/verifying, and file wiping; it provides a
command-line interface to PGP technology.
command-line interface: An interface where you type commands at a command
prompt. PGP Command Line uses a command-line interface.
keyboard input: PGP Command Line was designed so that all relevant information
can be entered at the command line, thus requiring no further input from the
keyboard to implement the commands.
scripting: PGP Command Line commands can be easily inserted into scripts to be
used for automating tasks. For example, if your company regularly copies a large
database to an off-site backup and then stores it there, PGP Command Line
commands can be added to the script that does this so that the database is
encrypted before it is transmitted to the off-site location and then decrypted when it
arrives. PGP Command Line commands are easily added to shell scripts or scripts
written with scripting languages (such as Perl or Python, for example).
environment variables: Environment variables control various aspects of PGP
Command Line behavior; for example, the location of the PGP Command Line home
directory. Environment variables are established on the computer running PGP
Command Line.
configuration file variables: When PGP Command Line starts, it reads the
configuration file, which includes special configuration variables and values for each
variable. These settings affect how PGP Command Line operates. Configuration file
variables can be changed permanently by editing the configuration file or overridden
on a temporary basis by specifying a value for a configuration file variable on the
command line.
Self-Decrypting Archives (SDAs): PGP Command Line lets you create SDAs,
compressed and conventionally encrypted archives that require a passphrase to
decrypt. SDAs contain an executable for the target platform, which means the
recipient of an SDA does not need to have any PGP software installed to open the
archive. You can thus securely transfer data to recipients with no PGP software
installed. You will have to communicate the passphrase of the SDA to the recipient,
however.
PGP Command Line User’s Guide 1: PGP Command Line Basics
8
Additional Decryption Key (ADK): PGP Command Line supports the use of an
ADK, which is an additional key to which files or messages are encrypted, thus
allowing the keeper of the ADK to retrieve data or messages as well as the intended
recipient. Use of an ADK ensures that your corporation has access to all its
proprietary information even if employee keys are lost or become unavailable.
PGP Zip archives: The PGP Zip feature lets you encrypt/sign groups of files or entire
directories into a single compressed archive file. The archive format is tar and the
supported compression formats are Zip, BZip2, and Zlib.
Getting Started
Now that you know a little bit about PGP Command Line, let’s go deeper into what you
need to do to get started using it:
1 Install PGP Command Line. Specific instructions for installing PGP Command Line
on the supported platforms are in Chapter 2, Installation.
2 License the software. PGP Command Line functionality is extremely limited until
you license the software. Refer to Chapter 3, Licensing for more information.
3 Create your default key pair. Most PGP Command Line operations require a key
pair (a private key and a public key). Refer to “Creating Your Keypair” on page 46 for
more information.
4 Protect your private key. Because your private key can decrypt your protected
data, it is important that you protect it. Do not write down or tell someone the
passphrase. It is a good idea to keep your private key on a machine that only you can
access, and in a directory that is not accessible from the network. Also, you should
make a backup of the private key and store it in a secure location.
Refer to “Protecting Your Private Key” on page 47 for more information.
5 Exchange public keys with others. In order to encrypt data to someone you need
their public key; and they need yours to encrypt data to you.
Refer to “Getting the Public Keys of Others” on page 50 for more information about
how to obtain public keys.
6 Verify the public keys you get from the keyserver. Once you have a copy of
someones public key, you add it to your public keyring. When you get someones
public key, you should make sure that it has not been tampered with and that it really
belongs to the purported owner. You do this by comparing the unique fingerprint on
your copy of someones public key to the fingerprint on that persons original key.
For more information about validity and trust, refer to An Introduction to
Cryptography (it was put onto your computer during installation). For instructions
how to verify someones public key, see “--fingerprint” on page 72.
7 Start securing your data. After you have generated your key pair and have obtained
public keys, you can begin encrypting, signing, decrypting, and verifying your data.
9
2Installation
Instructions for All Platforms
This chapter lists the system requirements for, and tells you how to install PGP Command
Line onto, the six supported platforms: AIX, HP-UX, Mac OS X, Linux, Solaris, and
Windows. It also includes uninstall instructions.
Overview
PGP Command Line can be installed on these platforms:
Windows Server 2003 (SP 1), Windows XP (SP 2), Windows 2000 (SP 4)
HP-UX 11i and above (PA-RISC only)
IBM AIX 5.2 and above
RedHat Enterprise Linux 3.0 and above (x86 only)
Fedora Core 3 and above (x86_64)
Sun Solaris 9 (SPARC only)
Apple Mac OS X 10.4 and above (Universal binary)
PGP Command Line uses a specific directory for the application data such as the
configuration file, and a specific directory (called the home directory) for the files it
creates, such as keyring files.
On any UNIX system, the application data and the home directory are identical and they
are configured through the $HOME environment variable. For more information, refer to
the installation instructions for the specific UNIX platform.
On Windows, the application data directory is used to store data such as the configuration
file PGPprefs.xml. The home directory is called “My Documents” and is used to store
keys. These two directories can be named differently, depending on the specific version
on Windows. For more information, refer to “To Install on Windows” on page 22.
Caution
You can also use the --home-dir option on the command line to specify a different home
directory. Using this option affects only the command it is used in and does not change the
PGP_HOME_DIR environment variable.
Using --home-dir on the command line overrides the current setting of the
PGP_HOME_DIR environment variable.
PGP Command Line User’s Guide 2: Installation
10
System Requirements
In general, system requirements for PGP Command Line are the same as the system
requirements for the host operating system.
In addition to the hard drive space required by the base operating system, PGP Command
Line requires additional space for both the data on which cryptographic operations (such
as encryption, decryption, signing, and verifying) will be applied and temporary files
created in the process of performing those operations.
For a given file being encrypted or decrypted, PGP Command Line can require several
times the size of the original file in free hard drive space (depending on how much the file
was compressed), enough to hold the original file or files and the final file resulting from
the encryption or decryption operation.
In cases where PGP Zip functionality is used on a file, PGP Command Line may also
require several times the size of the original file or files in free hard drive space, enough to
hold the original file, a temporary file created when handling the archive, and the final file
resulting from the encryption or decryption operation. Make sure you have adequate free
hard drive space on your system before using PGP Command Line.
Windows Server 2003
Standard Edition
Component Requirement
Computer and
processor
PC with a 133-MHz processor required; 550-MHz or faster processor
recommended (Windows Server 2003 Standard Edition supports up to four
processors on one server)
Memory 128 MB of RAM required; 256 MB or more recommended; 4 GB maximum
Hard disk 1.25 to 2 GB of available hard-disk space
Drive CD-ROM or DVD-ROM drive
Display VGA or hardware that supports console redirection required; Super VGA
supporting 800 x 600 or higher-resolution monitor recommended
PGP Command Line User’s Guide 2: Installation
11
Datacenter Edition
Enterprise Edition
These system requirements apply only to the 32-bit version of Windows Server 2003
Enterprise Edition; no support is provided for 64-bit versions of Windows Server 2003
Enterprise Edition.
Web Edition
Windows XP
Component Requirement
Computer and
processor
Minimum: 400 MHz processor for x86-based computers; recommended:
733 MHz processor
Memory Minimum: 512 MB of RAM; recommended: 1 GB of RAM
Hard disk 1.5 GB hard-disk space for x86-based computers
Other Minimum: 8-way capable multiprocessor machine required; maximum:
64-way capable multiprocessor machine supported
Component Requirement
Computer and
processor
133-MHz or faster processor for x86-based PCs; up to eight processors
supported on either the 32-bit
Memory 128 MB of RAM minimum required; maximum: 32 GB for x86-based PCs
with the 32-bit version
Hard disk 1.5 GB of available hard-disk space for x86-based PCs; additional space is
required if installing over a network
Drive CD-ROM or DVD-ROM drive
Display VGA or hardware that supports console redirection required
Component Requirement
Computer and
processor
133-MHz processor (550 MHz recommended)
Memory 128 MB of RAM (256 MB recommended; 2 GB maximum)
Hard disk 1.5 GB of available hard-disk space
Component Requirement
Computer and
processor
PC with 300 megahertz (MHz) or higher processor clock speed
recommended; 233-MHz minimum required; Intel Pentium/Celeron family,
AMD K6/Athlon/Duron family, or compatible processor recommended
Memory 128 megabytes (MB) of RAM or higher recommended (64 MB minimum
supported; may limit performance and some features)
Hard disk 1.5 gigabyte (GB) of available hard disk space
PGP Command Line User’s Guide 2: Installation
12
Windows 2000
IBM AIX 5.2 and 5.3
PGP Command Line runs on the range of IBM eServer p5, IBM eServer pSeries, IBM
eServer i5 and IBM RS/6000, as supported by IBM AIX 5.2 and 5.3.
HP-UX 11i
PGP Command Line runs on the list of PA-RISC workstation and servers supported by
HP-UX 11i, as specified at http://docs.hp.com/en/5187-2239/ch03s01.html.
Solaris 9
Red Hat Enterprise Linux and Fedora Core
Drive CD-ROM or DVD-ROM drive
Display Super VGA (800 × 600) or higher resolution video adapter and monitor
supporting 800 x 600 or higher-resolution monitor recommended
Component Requirement
Computer and
processor
133 MHz or higher Pentium-compatible CPU
Memory At least 64 megabytes (MB) of RAM; more memory generally improves
responsiveness
Hard disk 2 GB with 650 MB free space
Drive CD-ROM or DVD-ROM drive
Display VGA or higher resolution monitor
Component Requirement
Computer and
processor
SPARC (32- and 64-bit) platforms
Memory 64 MB minimum (128 MB recommended)
Hard disk 600 MB for desktops; one GB for servers
Component Requirement
Computer and
processor
x86 for Red Hat Enterprise Linux, x86_64 for Fedora Core; see Red Hat or
Fedora websites for hardware compatibility
Memory 256 MB minimum
Hard disk 800 MB minimum
PGP Command Line User’s Guide 2: Installation
13
Mac OS X
Installing on AIX
This section tells you how to install, change the home directory, and uninstall on AIX.
To Install on AIX
You need to have root or administrator privileges on the machine on which you are
installing PGP Command Line.
To install PGP Command Line onto an AIX machine:
1If you have an existing version of PGP Command Line installed on the computer,
uninstall it.
2Download the installer application called PGPCommandLine905AIX.tar to a known
location on your system.
3Untar the package first. You will get the following file:
PGPCommandLine95AIX.rpm
4Type : rpm -ivh PGPCommandLine95AIX.rpm
5Press Enter.
By default, the PGP Command Line application, pgp, is installed into the directory
/opt/pgp/bin. You need to add this directory to your PATH environment variable in
order for the application to be found.
For sh-based shells, use this syntax:
PATH=$PATH:/opt/pgp/bin
For csh-based shells, use this syntax:
set path = ($path /opt/pgp/bin)
Also, in order to access the PGP Command Line man page, you need to set the
MANPATH environment variable appropriately.
For sh-based shells, use this syntax:
MANPATH=$MANPATH:/opt/pgp/man; export MANPATH
For csh-based shells, use this syntax:
setenv MANPATH "/opt/pgp/man"
Component Requirement
Computer and
processor
Macintosh computer with PowerPC G3, G4, or G5 processor
Memory 128 MB of physical RAM
PGP Command Line User’s Guide 2: Installation
14
By adding the option --prefix to the rpm command, you can install PGP Command
Line in a location other than the default:
1If you have an existing version of PGP Command Line installed on the computer,
uninstall it.
2Download the installer application called PGPCommandLine95AIX.tar to a known
location on your system.
3Untar the package first. You will get the following file:
PGPCommandLine95AIX.rpm
4Type : rpm --prefix=/usr/pgp -ivh PGPCommandLine95AIX.rpm
5Press Enter.
This command installs the application binary in the directory /usr/pgp/bin/pgp, libraries in
/usr/pgp/lib, and so on.
You will need to edit the environmental variable LIBPATH to include the new library path
(/usr/pgp/lib) so that PGP Command Line can function in a location other than the default.
Changing the Home Directory on AIX
The home directory is where PGP Command Line stores the files that it creates and uses;
for example, keyring files.
By default, the PGP Command Line installer for AIX creates the PGP Command Line
home directory at $HOME/.pgp. If this directory does not exist, it will be created. For
example, if the value of $HOME for user “alice” is /usr/home/alice, PGP Command
Line will attempt to create /usr/home/alice/.pgp.
The PGP Command Line installer will not try to create any other part of the directory listed
in the $HOME variable, only .pgp.
If you want the home directory changed on a permanent basis, you will need to create the
$PGP_HOME_DIR environment variable and specify the path of the desired home
directory.
Uninstalling on AIX
Uninstalling PGP Command LIne on AIX requires root privileges, either through su or
sudo.
To uninstall PGP Command Line on AIX:
1Type the following command and press Enter:
rpm -e pgpcmdln
2PGP Command Line is uninstalled.
PGP Command Line User’s Guide 2: Installation
15
Installing on HP-UX
This section tells you how to install, change the home directory, and uninstall on HP-UX.
To Install on HP-UX
You need to have root or administrator privileges on the machine on which you are
installing PGP Command Line.
To install PGP Command Line onto an HP-UX machine:
1If you have an existing version of PGP Command Line installed on the computer,
uninstall it.
2Download the installer file called PGPCommandLine95HPUX.tar to a known
location on your system.
3Untar the package first. You will get the following file:
PGPCommandLine95HPUX.depot
4Type : swinstall -s /absolute/path/to/PGPCommandLine95HPUX.depot
5Press Enter.
The PGP Command Line application, pgp, is installed into the directory /opt/pgp/bin.
You need to add this directory to your PATH environment variable in order for the
application to be found.
For sh-based shells, use this syntax:
PATH=$PATH:/opt/pgp/bin
For csh-based shells, use this syntax:
set path = ($path /opt/pgp/bin)
Also, in order to access the PGP Command Line man page, you need to set the
MANPATH environment variable appropriately.
For sh-based shells, use this syntax:
MANPATH=$MANPATH:/opt/pgp/man; export MANPATH
For csh-based shells, use this syntax:
setenv MANPATH "/opt/pgp/man"
Caution
You may encounter an issue generating 2048- or 4096-bit keys on HP-UX systems running
PGP Command Line if you have altered the maximum number of shared memory segments
that can be attached to one process, as configured by the shmseg system parameter. If you
encounter this issue, reset the shmseg system parameter to its default value of 120. Consult
your HP-UX documentation for information on how to alter system parameters.
PGP Command Line User’s Guide 2: Installation
16
Changing the Home Directory on HP-UX
The home directory is where PGP Command Line stores the files that it creates and uses;
for example, keyring files.
By default, the PGP Command Line installer for HP-UX creates the PGP Command Line
home directory in $HOME/.pgp. If this directory does not exist, it will be created. For
example, if the value of $HOME for user “alice” is /usr/home/alice, PGP Command
Line will attempt to create /usr/home/alice/.pgp.
The PGP Command Line installer will not try to create any other part of the directory listed
in the $HOME variable, only .pgp.
If you want the PGP Command Line home directory changed on a permanent basis, you
can define the $PGP_HOME_DIR environment variable and specify the path of the desired
home directory.
Uninstalling on HP-UX
Uninstalling PGP Command LIne on HP-UX requires root privileges, either su or sudo.
To uninstall PGP Command Line on HP-UX:
1Type the following command and press Enter:
swremove pgpcmdln
2PGP Command Line is uninstalled.
Installing on Mac OS X
To Install on Mac OS X
To install PGP Command Line onto a Mac OS X computer:
1Close all applications.
2Download the installer application, PGPCommandLine95MacOSX.tgz, to your
desktop.
3Double-click on the file PGPCommandLine95MacOSX.tgz.
4If you have Stuffit Expander, it will automatically first uncompress this file into
PGPCommandLine95MacOSX.tar, and then untar it into
PGPCommandLine95MacOSX.pkg.
5Double-click on the file PGPCommandLine95MacOSX.pkg.
6Follow the on-screen instructions.
The Mac OS X PGP Command Line application, pgp, is installed into /usr/bin/.
After you run PGP Command Line for the first time, its home directory will be created
automatically in the directory $HOME/.pgp.
PGP Command Line User’s Guide 2: Installation
17
Changing the Home Directory on Mac OS X
The home directory is where PGP Command Line stores the files that it creates and uses;
for example, keyring files.
By default, the PGP Command Line installer for Mac OS X creates the PGP Command
Line home directory at $HOME/.pgp. If this directory does not exist, it will be created. For
example, if the value of HOME for user “alice” is /usr/home/alice, PGP Command
Line will attempt to create /usr/home/alice/.pgp.
The PGP Command Line installer will not try to create any other part of directory listed in
the $HOME variable, only .pgp.
If you want the home directory changed permanently, you need to create the
$PGP_HOME_DIR environment variable and specify the path of the desired home
directory.
Uninstalling on Mac OS X
Uninstalling PGP Command LIne on Mac OS X requires administrative privileges.
.
To uninstall PGP Command Line on Mac OS X:
1Using the Terminal application, enter the following commands:
rm -rf /usr/bin/pgp
rm -rf /Library/Frameworks/PGP*
rm -rf /Library/Receipts/PGP*
2PGP Command Line is uninstalled.
Preferences and keyrings are not removed when PGP Command Line is uninstalled.
Caution
If you have PGP Desktop for Mac OS X installed on the same system with PGP Command
Line, do not uninstall PGP Command Line unless you also plan to uninstall PGP Desktop.
Uninstalling PGP Command Line will delete files that PGP Desktop requires to operate; you
will have to reinstall PGP Desktop to return to normal operation.
PGP Command Line User’s Guide 2: Installation
18
Installing on Red Hat Enterprise Linux or Fedora Core
To Install on Red Hat Enterprise Linux or Fedora Core
You need to have root or administrator privileges on the machine on which you are
installing PGP Command Line.
To install PGP Command Line onto a Linux machine:
1If you have an existing version of PGP Command Line installed on the computer,
uninstall it.
2Download the installer file called PGPCommandLine95Linux.tar to a known
location on your system.
3Untar the package first. You will get the following file:
PGPCommandLine95Linux.rpm
4Type : rpm -ivh PGPCommandLine95Linux.rpm
5Press Enter.
The PGP Command Line application, pgp, is installed by default into /usr/bin/.
By adding the option --prefix to the rpm command, you can install PGP Command
Line in a location other than the default. Perform the following steps:
1If you have an existing version of PGP Command Line installed on the computer,
uninstall it.
2Download the installer file called PGPCommandLine95Linux.tar to a known
location on your system.
3Untar the package first. You will get the following file:
PGPCommandLine95Linux.rpm
4Type : rpm --prefix=/opt -ivh PGPCommandLine95Linux.rpm
5Press Enter.
This command will install the application binary in the directory /opt/bin/pgp, libraries
in /opt/lib, etc. You will need to edit the environment variable LD_LIBRARY_PATH to
include the new library path for the software to function in any location other than the
default.
Caution
If you want to use the XML key list functionality in PGP Command Line, you need to upgrade
libxml2 to Version 2.6.8; the default is Version 2.5.10. If you attempt to use the XML key list
functionality without upgrading, you will receive an error.
PGP Command Line User’s Guide 2: Installation
19
Changing the Home Directory on Linux
The home directory is where PGP Command Line stores the files that it creates and uses;
for example, keyring files.
By default, the PGP Command Line installer for Linux creates the PGP Command Line
home directory at $HOME/.pgp. If this directory does not exist, it will be created. For
example, if the value of $HOME for user “alice” is /usr/home/alice, PGP Command
Line will attempt to create /usr/home/alice/.pgp.
The PGP Command Line installer will not try to create any other part of the directory listed
in the $HOME variable, only .pgp.
If you want the home directory changed on a permanent basis, you need to create the
$PGP_HOME_DIR environment variable and specify the path of the desired home
directory.
Uninstalling on Linux
Uninstalling PGP Command LIne on Linux requires root privileges, either su or sudo.
To uninstall PGP Command Line on Linux:
1Type the following command and press Enter:
rpm -e pgpcmdln
2PGP Command Line is uninstalled.
PGP Command Line User’s Guide 2: Installation
20
Installing on Solaris
This section tells you how to install, change the home directory, and uninstall on Solaris.
To Install on Solaris
You need to have root or administrator privileges on the machine on which you are
installing PGP Command Line.
To install PGP Command Line onto a Solaris machine in the default directory:
1If you have an existing version of PGP Command Line installed on the computer,
uninstall it.
2Download the installer file called PGPCommandLine95Solaris.tar to a known
location on your system.
3Untar the package first. You will get the following file:
PGPCommandLine95Solaris.pkg
4Type pkgadd -d PGPCommandLine95Solaris.pkg and press Enter.
5At the first prompt, enter “1” or “all” to install the package.
If the directories /usr/bin and /usr/lib are not owned by root:bin, the install application
pkgadd will ask if you want to change the ownership/group on these directories. It is not
necessary to change them, but as an admin you may do so if you wish.
By default, the PGP Command Line application, pgp, is installed into the directory
/opt/pgp/bin. You need to add this directory to your PATH environment variable in
order for the application to be found.
For sh-based shells, use this syntax:
PATH=$PATH:/opt/pgp/bin
For csh-based shells, use this syntax:
set path = ($path /opt/pgp/bin)
Also, in order to access the PGP Command Line man page, you need to set the
MANPATH environment variable appropriately.
For sh-based shells, use this syntax:
MANPATH=$MANPATH:/opt/pgp/man; export MANPATH
For csh-based shells, use this syntax:
setenv MANPATH "/opt/pgp/man"
PGP Command Line User’s Guide 2: Installation
21
To install PGP Command Line on Solaris into a directory other than the default location:
1If you have an existing version of PGP Command Line installed, uninstall it.
2Download the installer application PGPCommandLine95Solaris.tar to a known
location on your system.
3Untar the package first. You will get the following file:
PGPCommandLine95Solaris.pkg
4Type : pkgadd -a none -d PGPCommandLine95Solaris.pkg
(This will force an interactive installation).
5Press Enter.
6At the first prompt, enter “1” or “all” to install the package.
7You will be asked to enter the path to the package’s base directory.
If you enter /usr/pgp, the binary will be installed to /usr/pgp/bin/pgp, libraries
will be installed to /usr/pgp/lib, and so on.
You need to edit the environment variable LD_LIBRARY_PATH to include the new
library path (/usr/pgp/lib) so that PGP Command Line can function in this
location.
Changing the Home Directory on Solaris
The home directory is where PGP Command Line stores the files that it creates and uses;
for example, keyring files.
By default, the PGP Command Line installer for Solaris creates the PGP Command Line
home directory in $HOME/.pgp. If this directory does not exist, it will be created. For
example, if the value of $HOME for user “alice” is /usr/home/alice, PGP Command
Line will attempt to create /usr/home/alice/.pgp.
The PGP Command Line installer will not try to create any other part of the directory listed
in the $HOME variable, only .pgp.
If you want the PGP Command Line home directory changed on a permanent basis, you
can define the $PGP_HOME_DIR environment variable and specify the path of the desired
home directory.
Uninstalling on Solaris
Uninstalling PGP Command LIne on Solaris requires root privileges, either su or sudo.
To uninstall PGP Command Line on Solaris:
1Type the following command and press Enter:
pkgrm PGPcmdln
To uninstall with no confirmation, use: pkgrm -n PGPcmdln
2PGP Command Line is uninstalled.
PGP Command Line User’s Guide 2: Installation
22
Installing on Windows
This section tells you how to install, change the home directory, and uninstall on
Windows.
To Install on Windows
To install PGP Command Line onto a supported Windows system:
1Close all Windows applications.
2Download the installer application, PGPCommandLine95Win32.zip, to a known
location on your system.
3Unzip the file PGPCommandLine95Win32.zip. You will get the following file:
PGPCommandLine95Win32.msi.
4Double click on PGPCommandLine95Win32.msi.
5Follow the on-screen instructions.
6If prompted, restart your machine. A restart is needed only if other PGP products are
also installed on the same machine.
The Windows PGP Command Line application, pgp.exe, is installed into:
C:\Program Files\PGP Corporation\PGP Command Line\
After you run PGP Command Line for the first time, its home directory will be created
automatically in the users home directory:
C:\Documents and Settings\<user>\My Documents\PGP\
Application data is stored in the directory:
C:\Documents and Settings\<user>\Application Data\PGP
Corporation\PGP
Locations may be different for the different Windows versions.
Changing the Home Directory on Windows
The home directory is where PGP Command Line stores its keyring files. If a different
PGP product has already created this directory, PGP Command Line will also use it (thus,
PGP Command Line can automatically use existing PGP keys).
PGP Command Line data files, such as keys, are stored in the home directory:
C:\Documents and Settings\<user>\My Documents\PGP\
PGP Command Line application files, such as the configuration file PGPprefs.xml, are
stored in:
C:\Documents and Settings\<user>\Application Data\PGP
Corporation\PGP\
PGP Command Line User’s Guide 2: Installation
23
If you want the home directory changed on a permanent basis, you need to create the
PGP_HOME_DIR environment variable and specify the path of the desired home directory.
To create the PGP_HOME_DIR environment variable on a supported Windows system:
1Click Start, select Settings, select Control Panel, and then select System.
The System Properties dialog appears.
2Select the Advanced tab, then click Environment Variables.
The Environment Variables screen appears.
3In the User Variables section, click New.
The New User Variable dialog appears.
4In the Variable name field, enter PGP_HOME_DIR. In the Variable value field, enter
the path of the home directory you want to use. For example:
C:\PGP\PGPhomedir\
5Click OK.
The Environment Variables screen reappears. PGP_HOME_DIR appears in the list of
user variables.
Uninstalling on Windows
To uninstall PGP Command Line on a supported Windows system:
1Navigate to the Add or Remove Programs Control Panel.
2Select PGP Command Line from the list of installed programs.
3Click Remove, then follow the on-screen instructions.
PGP Command Line is uninstalled.
PGP Command Line User’s Guide 2: Installation
24
25
3Licensing
Instructions for Licensing PGP Command Line
PGP Command Line requires a valid license to operate. This chapter describes how to
license your copy of PGP Command Line.
Overview
PGP Command Line requires a valid license to support full functionality. If you use PGP
Command Line without entering a license or after your license has expired, only basic
functionality will be available; you will only be able to get help and version information;
perform a speed test; list keys, user IDs, fingerprints, and signatures; export public keys
and keypairs; and license PGP Command Line.
When your license gets within 60 days of expiration, PGP Command Line begins issuing
warnings that license expiration is nearing. There is no grace period once the license
expiration date has been reached.
PGP Command Line supports the following licensing scenarios:
Using a license number: This is the normal method to license PGP Command Line.
You must have your license number and a working connection to the Internet.
Using a license authorization file: This licensing method uses licensing information
in a file that was obtained from PGP Corporation. This method does not require a
working connection to the Internet.
Re-licensing: If you have already licensed PGP Command Line on a system but want
to re-license it with a new license number (to support additional functionality, for
example), use this method. You must have your new license number and a working
connection to the Internet.
Through a proxy server: If you connect to the Internet through a proxy server, use
this method to license PGP Command Line. You must have your license number and
the appropriate proxy server information.
All of these scenarios are described in detail below.
Caution
As PGP Command Line will not operate normally until licensed, you should license it
immediately after installation.
PGP Command Line User’s Guide 3: Licensing
26
License Recovery
When you first enter your PGP Command Line license, one option is --license-email,
which takes a valid email address.
You are not required to use --license-email to license your copy of PGP Command
Line, but it is required if you want to take advantage of the license recovery feature.
The license recovery feature provides an automated mechanism for retrieving your original
licensing information for those occasions when you need to enter it again.
Here is how the license recovery feature works: When you first license your copy of PGP
Command Line, you enter a License Name, License Organization, your License Number,
and a License Email. The license authorizes, and you begin using PGP Command Line.
Several months pass. The hardware hosting PGP Command Line fails and it is no longer
usable. You need to reinstall PGP Command Line on a new system. You still have your
PGP Command Line license number, but you enter your company name differently in
License Organization; you didnt remember exactly how you entered it several months
ago, and this time you picked a slightly different form (or maybe you even mis-typed it by
mistake).
Not a big deal, you think; what difference could it make? But when you attempt to
authorize the license, it doesn’t work.
What happened is that when you re-license PGP Command Line, you must enter the
same information exactly as you did the first time or it will not license correctly.
At this point the license recovery feature kicks in. When you attempt to re-license PGP
Command Line, and you enter a valid license, but the License Name or License
Organization you enter is different, the license recovery feature sends an email message
to the License Email you entered the first time you licensed PGP Command Line.
The email message includes the License Name and License Organization you used when
you first licensed PGP Command Line. You can now license PGP Command Line on the
new system using the information in the message.
The key to the license recovery feature is entering a valid email address when you first
license PGP Command Line. The license recovery feature will only use the email address
you enter when you first license a specific PGP Command Line license. You can’t add or
change the email address at a later time; if you don’t enter it the first time you license, the
license recovery feature won’t work for that particular PGP Command Line license.
If the license recovery feature isn’t available for a PGP Command Line license, but you
need your original License Name or License Organization, you need to contact PGP
Support. Refer to pgpsupport.com for more information.
PGP Command Line User’s Guide 3: Licensing
27
Using a License Number
If you have a license number and a working Internet connection you can license your copy
of PGP Command Line.
Use --license-authorize to license PGP Command Line.
The following options are required:
--license-name <Name>
Where <Name> is your name or a descriptive name.
--license-organization <Org>
Where <Org> is the name of your company.
--license-number <Number>
Where <Number> is a valid license number.
The following option is not required but is recommended:
--license-email <EmailAddress>
Where <EmailAddress> is a valid email address, generally the email address of the
PGP Command Line administrator.
Before deciding not to enter a license email, be sure to refer to “License Recovery” on
page 26. Not entering a license email when you first license your copy of PGP Command
Line negates the license recovery feature for your PGP Command Line license. If you
decide not to enter a license email, you will see a warning message but your license will
authorize.
For example:
pgp --license-authorize --license-name "Alice Cameron"
--license-organization "Example Corporation"
--license-number "aaaaa-bbbbb-ccccc-ddddd-eeeee-fff"
--license-email "acameron@example.com"
(When entering this text, it all goes on a single line.)
PGP Command Line User’s Guide 3: Licensing
28
Using a License Authorization
If you have both a license number and a license authorization (a text file) from PGP
Corporation instead of just a license number, you need to list the name of the license
authorization file in the command.
You may need a license authorization if you are having problems authorizing your license
number or if the system hosting PGP Command Line is not connected to the Internet.
Use --license-authorize to license PGP Command Line using a license
authorization.
The following options are required:
--license-name <Name>
Where <Name> is your name or a descriptive name.
--license-organization <Org>
Where <Org> is the name of your company.
--license-number <Number>
Where <Number> is a valid license number.
The following option is not required but is recommended:
--license-email <EmailAddress>
Where <EmailAddress> is a valid email address, generally the email address of the
PGP Command Line administrator.
Before deciding not to enter a license email, be sure to refer to “License Recovery” on
page 26. Not entering a license email when you first license your copy of PGP Command
Line negates the license recovery feature for your PGP Command Line license. If you
decide not to enter a license email, you will see a warning message but your license will
authorize.
For example:
pgp --license-authorize --license-name "Alice Cameron"
--license-organization "Example Corporation"
--license-number "aaaaa-bbbbb-ccccc-ddddd-eeeee-fff"
license-auth.txt --license-email "acameron@example.com"
(When entering this text, it all goes on a single line.)
In this example, the text file “license-auth.txt” is shown after the license number.
PGP Command Line User’s Guide 3: Licensing
29
Re-Licensing
If you have already licensed your copy of PGP Command Line on a system, but you need
to re-license it on the same system (if you have purchased a new license with additional
capabilities, for example), you must use the <force> option to override the existing
license.
You can use a license number or a license authorization when you are re-licensing.
Use --license-authorize to re-license PGP Command Line.
The following options are required:
--license-name <Name>
Where <Name> is your name or a descriptive name.
--license-organization <Org>
Where <Org> is the name of your company.
--license-number <Number>
Where <Number> is a valid license number.
--force
The following option is not required but is recommended:
--license-email <EmailAddress>
Where <EmailAddress> is a valid email address, generally the email address of the
PGP Command Line administrator.
The following option is optional:
<LicenseAuthFilename>
Where <LicenseAuthFilename> is the name of the text file from PGP
Corporation that includes license authorization information.
Before deciding not to enter a license email, be sure to refer to “License Recovery” on
page 26. Not entering a license email when you first license your copy of PGP Command
Line negates the license recovery feature for your PGP Command Line license. If you
decide not to enter a license email, you will see a warning message but your license will
authorize.
For example:
pgp --license-authorize --license-name "Alice Cameron"
--license-organization "Example Corporation"
--license-number "aaaaa-bbbbb-ccccc-ddddd-eeeee-fff"
--license-email "acameron@example.com" --force
(When entering this text, it all goes on a single line.)
PGP Command Line User’s Guide 3: Licensing
30
Through a Proxy Server
If the Internet access of the system hosting PGP Command Line is via an HTTP proxy
connection, you can still license your copy of PGP Command Line directly; you simply
need to add the necessary proxy information.
Use --license-authorize to license PGP Command Line via a proxy server.
The following options are required:
--license-name <Name>
Where <Name> is your name or a descriptive name.
--license-organization <Org>
Where <Org> is the name of your company.
--license-number <Number>
Where <Number> is a valid PGP Command Line license number.
--proxy-server <Server>
Where <Server> is the IP address or fully qualified domain name of the proxy
server PGP Command Line must go through to reach the Internet.
The following options are not required; they are only needed when the proxy server
requires authentication:
--proxy-username <Username>
Where <Username> is a valid username on the proxy server.
--proxy-passphrase <Passphrase>
Where <Passphrase> is the passphrase for the username you entered.
The following option is not required but is recommended:
--license-email <EmailAddress>
Where <EmailAddress> is a valid email address, generally the email address of the
PGP Command Line administrator.
Before deciding not to enter a license email, refer to “License Recovery” on page 26. Not
entering a license email when you first license your copy of PGP Command Line negates
the license recovery feature for your PGP Command Line license. If you decide not to
enter a license email, you will see a warning message but your license will authorize.
For example:
pgp --license-authorize --license-name "Alice Cameron"
--license-organization "Example Corporation"
--license-number "aaaaa-bbbbb-ccccc-ddddd-eeeee-fff"
--proxy-server "proxyserver.example.com"
--proxy-username "acameron"
--proxy-passphrase "a_cameron1492sailedblue"
--license-email "acameron@example.com"
(When entering this text, it all goes on a single line.)
31
4The Command-Line Interface
How to Enter Commands
This chapter describes the command-line interface of the PGP Command Line product:
what it is, how to use it, how to get help, flags and arguments, the configuration file, and
environment variables.
Overview
PGP Command Line uses a command-line interface. You enter a valid command and
press Enter. PGP Command Line responds appropriately based on what you entered (if
you entered a valid command) or with an error message (if you entered an invalid or
incorrectly structured command).
All PGP Command Line commands have a long form: the text “pgp”, a space, two
hyphens “--, and then the command name. Some of the more common commands
have a short form: one hyphen and then a single letter that substitutes for the command
name.
The --version command, for example, tells you what version of PGP Command Line
you are using. It does not have a short form:
%pgp --version [Enter]
From here on, the command prompt (% in this example) and [Enter] will not be shown.
The response is:
PGP Command Line 9.5
Copyright (C) 2006 PGP Corporation
All rights reserved.
The --help command tells you about the commands available in PGP Command Line.
The long form is:
pgp --help
The short form is:
pgp -h
The response to either version of the --help command is:
PGP Command Line 9.5
Copyright (C) 2006 PGP Corporation
All rights reserved.
Commands:
Generic:
-h --help this help message
and so on.
PGP Command Line User’s Guide 4: The Command-Line Interface
32
Some more examples of the command line:
1 pgp --encrypt report.doc --recipient Alice
report.doc:encrypt (0:output file report.doc.pgp)
Encrypts a file (the output filename will be report.doc.pgp) to the recipient
Alice.
2 pgp -e report.doc -r Alice
report.doc:encrypt (0:output file report.doc.pgp)
Does the same as above, but using the short forms of the encrypt and the recipient
flags.
3 pgp -er Alice report.doc
report.doc:encrypt (0:output file report.doc.pgp)
Combines multiple command short forms. “Alice” must come after the “r” because
it is a required argument to --recipient.
4 pgp -er Alice report.doc --output NewReport.pgp
report.doc:encrypt (0:output file NewReport.pgp)
Changes the name of the file that is produced.
PGP Command Line User’s Guide 4: The Command-Line Interface
33
Flags and Arguments
PGP Command Line uses flags, commands, options, and arguments:
Flags come in two different types, commands and options. Commands are flags
that control what PGP Command Line does in its current invocation; they have no
effect on subsequent invocations of PGP Command Line. Options change the
behavior of the current command. Some options require an argument, described
below, while others do not. The order in which flags are listed on the command line
has no effect on their behavior.
Arguments are required as the next parameter when an option flag is used.
Arguments must immediately follow their flags. Where the flag/argument pair are on
the command line does not change what the flag/argument pair does. Except when
setting lists, in which case the command is read left to right; so when searching
keyservers, for example, the listed keyservers are searched in the order in which
they are provided on the command line.
Flags and arguments must be separated by a space on the command line. Extra spaces
are ignored. If a space between parts of an argument is required, the entire argument
must be between quotes.
In some cases, there can be multiple names for a single flag.
For example:
--textmode and --text (same flag with two names)
It is also possible to provide an option that has no effect on the current operation. Flags
that have no bearing on the current operation are ignored, unless they cause an error, in
which case the command returns an error.
For example:
--list-keys Alice with the option --encrypt-to-self
(the option --encrypt-to-self will be ignored)
Flags
As noted above, flags have both long and short forms. To combine multiple long forms,
you simply write them out separated by a space. For example, to encrypt a file and armor
the output:
pgp --encrypt ... --armor
You can, however, combine multiple short forms into a single flag. For example, to
encrypt and sign at the same time:
pgp -es ...
When combining short forms, if at any time an option is used in the list that requires an
argument, the list must be terminated and followed by the argument. For example: -ear
recipient.
PGP Command Line User’s Guide 4: The Command-Line Interface
34
Arguments
An argument is required as the next parameter when some option flags are used. There
are several kinds of arguments, differentiated by how they are structured or what kind of
information is provided.
The kinds of arguments are:
Booleans
Integers
Enumerations
Strings
Lists
File descriptor
No parent
Each of these kinds of arguments is described below.
Booleans
Booleans are a special kind of argument. They never take a direct argument themselves.
Instead, the behavior changes by how the flag is specified. To disable a Boolean, specify
it with the prefix “--no-” instead of the normal “--.
When the short form is used for a Boolean flag, there is no way to specify the disabled
version of the flag.
For example:
--reverse-sort (activates reverse sorting)
--no-compress (deactivates compression, the reverse of --compress)
-t (activates text mode; to deactivate text mode, the long form must be used,
--no-text)
Integers
Integers are arguments that take a numeric value.
For example:
--wipe-passes 8 (sets the number of wipe passes to eight)
PGP Command Line User’s Guide 4: The Command-Line Interface
35
Enumerations
Enumerations are arguments that take a string, which is then converted to the correct
value by PGP Command Line. This string will be one of several possible for each flag.
For example:
--sort-order userid (sort by user ID)
--overwrite remove (sets the file overwrite behavior to remove files if they exist)
Strings
String arguments take a string. If the string you want to use contains any spaces, the
entire string must be in quotes (this indicates that all of the pieces belong to the same
argument). In some cases, an empty string (““) can be passed as an argument.
On Windows systems, strings are read in as double-byte character strings and converted
to UTF-8 for use by the PGP SDK or for output. On all other platforms, UTF-8 is used.
For example:
--default-key 0x8885BE88 (sets the key with this key ID as the default key)
--output “New File.txt.pgp” (sets the output filename to a filename with a
space in it)
--passphrase ““ (specifies a blank passphrase)
--expiration-date 2005-12-27 (specifies an expiration date of Dec. 27, 2005)
Lists
List arguments are the same as string arguments except you can supply more than one
string.
For example:
--recipient bob --recipient bill (sets both Bob and Bill as recipients)
-r bob -r bill (same command using the short form of the flag)
File descriptors
File descriptor arguments behave like integer arguments, but instead of storing the value
of the descriptor, PGP Command Line reads a string value from the descriptor. These
string values always have a string type counterpart.
If you need to specify the data in UTF-8 format on a Windows system, use the “8”
versions of the file descriptor options.
For example:
--passphrase-fd 4 (read passphrase from fd 4 and use it as if
--passphrase had been supplied)
--passphrase-fd8 7 (read a UTF-8 passphrase from fd 7)
PGP Command Line User’s Guide 4: The Command-Line Interface
36
No parent
The final kind of arguments are those that have no parent flag. These arguments behave
like lists and follow the same rules. They are used in different ways, depending on the
operation being performed, but they can occur anywhere in the command line except
after a flag that has a required argument.
These arguments can represent users or represent files.
For example
--list-keys Alice Bob Bill (list all keys that match any one of these users)
--encrypt file1.txt file2.txt file3.txt (encrypt multiple files with the
same command)
Configuration File
Generally, the configuration file PGPprefs.xml cannot be changed by PGP Command Line
itself: any changes need to be edited manually (on Mac OS X, the configuration file is
com.pgp.desktop.plist, located in /users home directory/Library/Preferences/).
Starting with the PGP Command Line version 9.0, there is one operation that will change
the configuration file: when you authorize a license, this information is saved in the file
PGPprefs.xml for future use.
The configuration file PGPprefs.xml is located in the following locations:
$HOME directory on any Unix platform
The exact location depends on the version of Windows, but it is always the directory
that holds the application data.
By changing some of the settings in the PGPprefs.xml file, you will change how PGP
Command Line works as long as this file is not replaced.
Note that those configuration file settings that do not begin with “CL” are shared among
all PGP applications on the system.
Like arguments, the configuration file settings come in different types: Boolean, Integer,
Enumeration, List, and String.
Boolean configuration file settings you can use with PGP Command Line are:
ADK warning level (adkWarning). Enables warning messages for ADK actions
such as adding an ADK, skipping an ADK, or when an ADK is not found. Refer to
“--warn-adk” on page 148 for more information.
Encrypt to self (encryptToSelf). When on, all files or messages you encrypt to
someone else are also encrypted to your key, which means you can decrypt those
encrypted files/messages at a later time, if you wish. The default is off. See
“--encrypt-to-self” on page 142 for more information.
Fast keygen (fastKeyGen). Establishes the setting for fast key generation, on or
off. The default is on. See “--fast-key-gen” on page 143 for more information.
PGP Command Line User’s Guide 4: The Command-Line Interface
37
Halt on error (CLhaltOnError). When on, causes PGP Command Line to halt
operations when an error occurs. Does not apply to all operations. The default is off.
See “--halt-on-error” on page 144 for more information.
Keyring cache (CLkeyringCache). When on, stores keyrings in memory for each
access. The default is off. See “--keyring-cache” on page 144 for more information.
Large Keyrings (CLlargeKeyrings). Checks keyring signatures only when
necessary. See “--large-keyrings” on page 144 for more information.
Marginal is invalid (marginalIsInvalid). Establishes whether marginally trusted
keys are considered valid. The default is true, which means that marginally valid keys
are not valid. See “--marginal-as-valid” on page 145 for more information.
Passphrase cache (CLpassphraseCache). When on, automatically saves your
passphrase in memory until you log off or purge the passphrase cache. The default is
off. See “--passphrase-cache” on page 145 for more information.
Integer configuration file settings you can use with PGP Command Line are:
Keyring cache timeout (CLkeyringCacheTimeout). Establishes the number of
seconds a keyring stays cached in memory. The default is 120 seconds. See
“--keyring-cache-timeout” on page 153 for more information.
Keyserver timeout (CLkeyserverTimeout). Establishes the number of seconds
to wait before a keyserver operation times out. The default is 120 seconds. See
“--keyserver-timeout” on page 153 for more information.
Number of wipe input passes (CLfileWipeInputPasses). Establishes the
number of wipe passes for input files. The default is 3 passes. See
“--wipe-input-passes” on page 158 for more information.
Number of wipe passes (fileWipePasses). Establishes the number of passes
used by the --wipe command. The default is 3 passes. See “--wipe” on page 136 for
more information.
Number of wipe temp passes (CLfileWipeTempPasses). Establishes the
number of wipe passes for temporary files. The default is 3 passes. See
“--wipe-temp-passes” on page 158 for more information.
Number of wipe overwrite passes (CLfileWipeOverwritePasses). Establishes
the number of wipe passes when overwriting an existing output file. The default is 3
passes. See “--wipe-overwrite-passes” on page 159 for more information.
Passphrase cache timeout (CLpassphraseCacheTimeout). Establishes the
number of seconds a passphrase stays cached in memory. The default is 120
seconds. See “--passphrase-cache-timeout” on page 154 for more information.
Enumeration configuration file settings you can use with PGP Command Line are:
Automatic import of keys (CLautoImportKeys). Establishes behavior when keys
are found during non-import operations. The default is all. See “--auto-import-keys”
on page 160 for more information.
PGP Command Line User’s Guide 4: The Command-Line Interface
38
Compression Level (CLcompressionLevel). Sets the compression level for the
current operation. The default is default. See “--compression-level” on page 161 for
more information.
Enforce ADK (CLenforceADK). Establishes the ADK enforcement policy. The
default is attempt. See “--enforce-adk” on page 162 for more information.
Input cleanup (CLinputCleanup). Establishes what to do with input files after
they have been used. The default is off. See “--input-cleanup” on page 165 for more
information.
Manual import of keys (CLmanualImportKeys). Establishes behavior when keys
are found during an import. The default is all. See “--manual-import-keys” on
page 166 for more information.
Manual import of key pairs (CLmanualImportKeyPairs). Establishes behavior
when key pairs are found during import. The default is pair. Refer to
“--manual-import-key-pairs” on page 166 for more information.
Sort order (CLsortOrder). Changes the sort order for writing key lists. The default
is any. See “--sort-order, --sort” on page 167 for more information.
Overwrite (CLoverwrite). Establishes what to do when an operation tries to
create an output file but it already exists. The default is off. See “--overwrite” on
page 167 for more information.
List configuration file settings you can use with PGP Command Line are:
Always encrypt to keys (alwaysEncryptToKeys). Specifies additional recipients
for encryption. Use the 32- or 64-bit key ID to specify the key(s) to use. Refer to
“--additional-recipient” on page 180 for more information.
Default keyserver names and associated values (keyservers). Specifies default
keyservers. The default is ldap://keyserver.pgp.com:389/. If you supply a keyserver
on the command line, those keyservers listed in the configuration file are ignored.
String configuration file settings you can use with PGP Command Line are:
Comment (commentString). Specifies a comment string to be used in armored
output blocks. The default is not set. Refer to “--comment” on page 170 for more
information.
Default signing key (CLdefaultKey). Specifies a key to be used by default for
signing. The default is not set. See “--default-key” on page 171 for more
information.
License Authorization (CLlicenseAuthorization). Specifies the license
authorization. The default is not set. See “--license-name, --license-number,
--license-organization, --license-email” on page 173 for more information.
.
Caution
Because licensing information is stored somewhat differently, PGP Corporation recommends
that you do not directly edit the license-related configuration file settings; instead, use the
license authorization commands described in Chapter 3, Licensing.
PGP Command Line User’s Guide 4: The Command-Line Interface
39
License Name (CLlicenseName). Specifies the name of the licensee. The default is
not set. See “--license-name, --license-number, --license-organization,
--license-email” on page 173 for more information.
License Number (CLlicenseNumber). Specifies the license number. The default is
not set. See “--license-name, --license-number, --license-organization,
--license-email” on page 173 for more information.
License Organization (CLlicenseOrganization). Specifies the organization of
the licensee. The default is not set. See “--license-name, --license-number,
--license-organization, --license-email” on page 173 for more information.
Output File (CLoutputFile). Specifies the output file (default is not set in the
configuration file; defaults to stdout). The output file is used for output messages.
See “--output-file” on page 174 for more information.
Private keyring file (privateKeyringFile). The filename or path and filename to
the private keyring file. The default is secring.skr, located in the default PGP
Command Line home directory. See “--private-keyring” on page 175 for more
information.
Public keyring file (publicKeyringFile). The filename or path and filename to
the public keyring file. The default is pubring.pkr, located in the default PGP
Command Line home directory. See “--public-keyring” on page 176 for more
information.
Random seed filename (rngSeedFile). Sets the location of the random seed file.
By default, the random seed file is located in the PGP Command Line data directory.
See “--random-seed” on page 177 for more information.
Status File (CLstatusFile). Specifies the status file. The default is not set in the
configuration file; defaults to stderr. The status file is used for status messages,
using a file name (with or without the path information). See “--status-file” on
page 178 for more information.
PGP Command Line User’s Guide 4: The Command-Line Interface
40
Keyserver Configuration File Settings
Here is the keyserver section of the PGPprefs.xml file, with brief explanations of specific
settings:
<key>keyservers</key>
<array>
<dict>
<key>title</key>
<string>keyserver.example.com</string>(
(name of the keyserver)
<key>domain</key>
<string></string>
<key>hostname</key>
<string>keyserver.example.com</string>
(hostname of the keyserver)
<key>port</key>
<integer>389</integer> (keyserver port)
<key>protocol</key>
<integer>1</integer>(keyserver protocol: 1= LDAP, 2= HTTP,
3 = LDAPS and 4 = HTTPS (currently not supported)
<key>type</key>
<integer>1</integer>(keyserver type: 1 = HTTP, 2 = HTTPS
(currently not supported)
<key>keyserverType</key>
<integer>100</integer>(keyserver type: 100 = PGPLDAP, 101 =
PGPLDAPS, 102 = PGPVKD, 103 = X509LDAP, 104 = X509LDAPS, 105 =
PGPHTTP)
<key>baseDN</key>
<string></string>
<key>authKeyID</key>
<string></string> (not used)
<key>authAlgorithm</key>
<integer>0</integer> (not used)
<key>flags</key>
<integer>0</integer> (not used)
PGP Command Line User’s Guide 4: The Command-Line Interface
41
Environment Variables
PGP Command Line behavior can be changed using environment variables. For
information about defining environment variables, refer to the section that describes the
platform you are using in Chapter 2, Installation.
Environment variables have the lowest priority compared to the command line and the
configuration file. Settings for either will override environment variables. However, if a
value for an item is not specified in either, the environment variable will be used.
Environment variables cannot be disabled; if they are present, they are implemented. To
disable an environment variable, remove it. Setting a Boolean environment variable will
activate it, regardless of the value to which it is set.
Environment variables that can be implemented for PGP Command Line are:
PGP_LOCAL_MODE. This is a Boolean environment variable that forces PGP
Command Line to run in local mode. The default is unset. See “--local-mode” on
page 145 for more information.
Usage: PGP_LOCAL_MODE=1
PGP_NO_BANNER. This is a Boolean environment variable that turns off the banner
when a command is run. The default is unset. See “--banner” on page 141 for more
information.
Usage: PGP_NO_BANNER=1
PGP_HOME_DIR. This is a string environment variable that overrides the default
home directory, pointing it to the path supplied in the variable. The default is unset.
See “--home-dir” on page 172 for more information.
Usage: PGP_HOME_DIR=/usr/bin/alice
PGP_PASSPHRASE. This is a string environment variable that lets you set your
passphrase. The default is unset. For more information, See “--passphrase” on
page 174 for more information.
Usage: PGP_PASSPHRASE=”Now is the time for all good men
PGP_NEW_PASSPHRASE. This is a string environment variable that lets you set a
new passphrase. The default is unset. See “--new-passphrase” on page 173 for
more information.
Usage: PGP_NEW_PASSPHRASE=”to come to the aid of their country.
PGP_SYMMETRIC_PASSPHRASE. This is a string environment variable that lets
you set a passphrase for symmetric encryption. The default is unset. See
“--symmetric-passphrase” on page 178 for more information.
Usage: PGP_SYMMETRIC_PASSPHRASE=”Now is the time
PGP_EXPORT_PASSPHRASE. This is a string environment variable that lets you set
the export passphrase. The default is unset. See “--export-passphrase” on page 171
for more information.
Usage: PGP_EXPORT_PASSPHRASE=”For All Good Men
PGP Command Line User’s Guide 4: The Command-Line Interface
42
Standard Input, Output, and Error
PGP Command Line writes different data to several different places by default. Any user
output generated by PGP Command Line is written to standard output (stdout),
including version information, key list data, and so on. Any status information generated
by command line is sent to standard error (stderr).
When encrypting and decrypting, PGP Command Line reads and writes files by default.
These files can be overridden with the special argument “-” to either --input or
--output. This behavior is set so that PGP Command Line doesn’t have to wait for input
if you forget something: it will generate an error that you can detect.
The behavior of PGP Command Line changes depending on the operating system you are
using, while the syntax changes depending on the shell.
When you work with PGP Command Line, you can use standard input (stdin) in two
ways: by redirecting an existing file, or by typing (pasting in) data.
Redirecting an Existing File
You can use your shell to redirect input to PGP Command Line from an existing file.
The command looks like:
pgp -er user -i - -o file.pgp<file.txt
Example:
pgp -er "bob@example.com" -i - -o newnote.pgp<newnote.txt
stdin:encrypt (0:output file newnote.pgp)
In this case, the file newnote.txt was encrypted with Bob’s key and saved as
newnote.pgp.
Entering Data
Instead of redirecting an existing file, you can also type (or paste in) the data that needs to
be encrypted. The command looks like:
pgp -er user -i - -o file.pgp
(type/paste in the data to be encrypted)
Example:
pgp -er "bob@example.com" -i - -o newnote.pgp
(This text is the file newnote.txt, which will be signed by Bob.)
^Z
stdin:encrypt (0:output file newnote.pgp)
In addition to specifying the end of file, you also need to specify an output file name
(such as “newnote.pgp”), since the input file name was not specified.
pgp --decrypt newnote.pgp --passphrase sm1t4
PGP Command Line User’s Guide 4: The Command-Line Interface
43
newnote.pgp:decrypt (0:output file newnote)
If you now decrypt newnote.pgp, the decrypted file newnote will not have an
extension since the input was not in a file format.
On platforms where buffered standard input/output (I/O) is disabled by default, you
cannot type or paste into stdin. Instead, you need to enable standard I/O using
--buffered-stdin (see --buffered-stdin for details).
End-of-File
Depending on the shell you use, the end of file will be announced in different ways:
On Windows, enter ^Z (ctrl-z) on a separate line.
On UNIX, enter ^D (ctrl-d) anywhere in the text. The end of file character is
shell-dependent and will vary on different systems.
Specifying a Key
When you need to specify a key or keys as input for a PGP Command Line operation,
there are two methods you can use:
Match by user ID: To match by user ID, supply some of the text in the user ID(s) you
want to match. A case insensitive search of the user IDs of the keys on the local
keyring is made. All keys that match the supplied text will be returned; for example,
searching on ’ex’ would return all keys on the local keyring from the domain
example.com’, as well as a key whose user ID was ’dexter@pgp.com’. This is a
convenience feature that makes it easy for you to match multiple keys on the local
keyring.
Searching by user ID can return no keys, one key, or multiple keys, depending on the
supplied text and the user IDs of the keys on the local keyring. Matching by user ID
is best for operations where you want your search to return multiple keys; for
example, the list operations (--list-keys, --fingerprint, and so on). Match by user ID
can be used for operations that work only on a single key, but as it may return
multiple keys, match by user ID may not be the best choice for these operations.
Match by key ID: To match by key ID, supply the key ID of the specific key you want
used for the operation (0xABCD1234, for example). The key IDs of the keys on the
local keyring will be searched. If the key with the specified key ID is found on the
local keyring, it will be used for the operation; if not, the operation will terminate.
Searching by key ID will return either no keys or one key. Matching by key ID is best
for those cases where the search must exactly match one key (--default-key, for
example) or where only a single key can be used for the operation; for example,
most of the key edit operations (--split-key, --revoke, and so on).
PGP Command Line User’s Guide 4: The Command-Line Interface
44
‘Secure’ Options
The descriptions of some options in PGP Command Line mention that they are “secure,
as in “This option is not secureor “--auth-passphrase is secure.
In this context, “secure means that the options argument is saved in non-pageable
memory (when that option is available to applications). Options that are not “secure” are
saved in normal system memory.
45
5First Steps
An Overview of What To Do First
This chapter describes the first steps you need to take to get up and running with PGP
Command Line.
Overview
The first steps for getting up and running with PGP Command Line are:
1Install PGP Command Line.
Installation for all supported platforms is fully described in Chapter 2, Installation.
2License your copy of PGP Command Line.
Licensing is required for normal operation of PGP Command Line. Refer to Chapter
3, Licensing and “--license-authorize” on page 134 for more information about
licensing PGP Command Line.
3Create your key pair.
Most of the things you do with PGP Command Line require a key pair (a private key
and a public key). How to create your key pair is described later in this chapter in
“Creating Your Keypair” on page 46.
4Protect your private key.
No one but you should know the password or have access to your private key. How
to protect your private key is described later in this chapter in “Protecting Your
Private Key” on page 47.
5Distribute your public key.
In order for others to verify your signature or encrypt data so that only you can
decrypt it, they will need your public key.
One way to distribute your public key is to post it to a keyserver so that others can
obtain it. The best way to do this is to post your public key to the PGP Global
Directory (keyserver.pgp.com), a free, public keyserver hosted by PGP Corporation.
It provides quick and easy access to the universe of PGP keys.
You can also export your public key to a file, which you can then distribute in any
number of ways. For information about how to post your public key to a keyserver
and extract your public key to a file, refer to “Distributing Your Public Key” on
page 48.
6Obtain the public keys of others.
PGP Command Line User’s Guide 5: First Steps
46
You need someones public key to be able to encrypt data so that only they can
decrypt it. You can get public keys from a keyserver (as long as the key is posted, of
course). And if you receive someone’s public key in a file, you can import it. For more
information about how to get a public key from a keyserver and how to import a key,
refer to “Getting the Public Keys of Others” on page 50.
7Verifying the public keys you get.
It is important to make sure the public keys you get actually belong to the person or
organization they appear to be from. For instructions on how to verify a public key,
refer to “Verifying Keys” on page 52.
8Start securing your data.
Creating Your Keypair
The first thing you need to do after installing PGP Command Line is to make sure you
have a usable PGP key pair, as most PGP Command Line operations require a key pair.
A key pair consists of two keys:
Private key (stored in secring.skr) that only you have.
Public key (stored in pubring.pkr) that you can distribute freely to the people you
correspond with.
Keys are stored on keyrings. Theres one keyring for private keys (secring.skr), and one
keyring for public keys (pubring.pkr).
If you are using a Windows or Mac OS X system, you may already have a key pair
generated by PGP Desktop. If you do have an existing key pair you want to use with
PGP Command Line and you distributed your public key to the people who will be
encrypting data to you, you need to make sure the environment variable (PGP_HOME_DIR)
is defined and points to the directory where your existing key pair is located.
If you do not have a PGP key pair, you will need to create one for use with
PGP Command Line.
Use the --gen-key command to create a new key pair.
To create a key pair:
1On the command line, enter:
pgp --gen-key <user> --key-type <type> --encryption-bits <bits>
--passphrase <pass> [--signing-bits <bits>] [options]
where:
Caution
If you have PGP Desktop installed on the same Windows or Mac OS X computer as
PGP Command Line, and you installed PGP Desktop into the default directory, then
PGP Command Line will automatically locate and use your existing keyrings.
PGP Command Line User’s Guide 5: First Steps
47
<user> is a user ID that people can use to locate your public key. A common user ID
is your name and email address in the format: “Alice Cameron
<alice@example.com>”. If your user ID contains spaces, you must enclose it in
quotation marks.
<type> means you are creating either an RSA or a DH key.<bits> is the number of
bits of the key (usually 1024 - 4096).
<passphrase> is a passphrase of your choice. If your passphrase includes spaces,
enclose it in quotation marks.
For more information, refer to “--gen-key” on page 100.
2Press Enter when the command is complete.
PGP Command Line responds by generating your key pair.
Protecting Your Private Key
If someone gets your private key and manages to guess your passphrase or finds it
written on a Post-it®, they can impersonate you. They can open messages encrypted to
you and they can sign messages, making them appear to be from you.
By default, all generated keys (private and public) are stored in the directory to which the
environment variable points (which is PGP_HOME_DIR, if set.
Otherwise:
UNIX: $HOME/.pgp
Windows: C:\Documents and Settings\<current user>\
My Documents\PGP
Mac OS X: /user’s home directory/.pgp/
You can locate your keyrings using the --version -v command.
Once the keys are generated, you can store them in any location you choose (provided
you don’t forget to adjust the environment variable to point to the new location). Moving
your keys to a different location is one way to protect them from someone who might get
access to your system.
Caution
The --gen-key command automatically creates your key pair and a public and a private
keyring in the home directory, then puts your new private and public keys onto their
respective keyrings. You can create empty keyring files without generating a key pair at the
same time using the --create-keyrings command.
Caution
It is very important to protect your private key! Don’t let anyone get a copy of it and don’t ever
give anyone the passphrase.
PGP Command Line User’s Guide 5: First Steps
48
It is also a good practice to make a backup copy of your keys. Make sure to be especially
careful with your private key, storing it on a machine only you can access and in a
directory that cannot be accessed via a network. You may also choose to implement
additional security precautions.
Distributing Your Public Key
People need your public key to encrypt information that only you can decrypt and to verify
your signature.
There are three main methods available to distribute your public key:
Post your public key to the PGP Global Directory. The PGP Global Directory is a
free, publicly available keyserver hosted by PGP Corporation that provides quick and
easy access to the universe of PGP keys. If you aren’t in an email domain
protected by a PGP Universal Server, the PGP Global Directory is your source
for trusted keys.
Post your public key to another keyserver. Once posted, people can get a copy of
your public key and use it to encrypt data that only your private key can decrypt.
How to use PGP Command Line to post your public key to a keyserver is described
below.
Export your public key to a text file. Once exported to a text file, you can distribute
your public key however you like: attached to an email message, pasted into the
body of an email message, or copied to a CD.
How to use PGP Command Line to extract your public key to a text file is described
in “Exporting Your Public Key to a Text File” on page 49.
Posting Your Public Key to a Keyserver
You can post your public key to a private keyserver or a public keyserver; the procedure is
the same in both cases.
Use the --keyserver-send command to post your public key to a keyserver.
To post a public key to a keyserver:
1On the command line, enter:
pgp --keyserver-send <input> --keyserver <ks>
where:
<input> is the user ID, portion of the user ID, or key ID of the public key you are
posting.
<ks> is the name of the keyserver to which you are posting.
For example:
PGP Command Line User’s Guide 5: First Steps
49
pgp --keyserver-send alice@example.com --keyserver
ldap://keyserver.example.com
If there are multiple keys with user IDs that match the input, all of them will be
posted. To make sure only a specific key is posted, use the key ID as the input.
pgp --keyserver-send 0x12345678 --keyserver
ldap://keyserver.pgp.com
Only the specified key will be posted to ldap://keyserver.pgp.com, a public
keyserver.
2Press Enter when the command is complete.
PGP Command Line responds by posting the public key(s) to the specified
keyserver.
Once you have posted your public key to a keyserver, you should search the keyserver for
your public key to make sure it was correctly posted.
How to search for a key on a keyserver is described in “Finding a Public Key on a
Keyserver” on page 50.
Exporting Your Public Key to a Text File
Once you have extracted your public key to a text file, it is easy to distribute. You can
attach it to an email message, paste it into the body of an email message, or copy it to a
CD.
Use the --export command to export your public key.
To export a public key:
1On the command line, enter:
pgp --export <input>
where:
<input> is the user ID, portion of the user ID, or the key ID of the key you want
to export.
If you don’t enter any input, all keys on the keyring are exported.
By default, keys are exported as ASCII armor (.asc) files into the directory
currently active on the command line.
For example:
pgp --export example
All keys with the string “example” anywhere in them would be exported into
separate .asc files.
pgp --export “Alice C <acameron@example.com>”
Only keys that exactly match this user ID would be exported. The filename would be
Alice C.asc.
PGP Command Line User’s Guide 5: First Steps
50
2Press Enter when the command is complete.
PGP Command Line responds by creating the .asc file(s) in the appropriate
directory.
Getting the Public Keys of Others
To encrypt data to a specific person, you need to encrypt it with their public key. Naturally,
you have to get their public key onto your keyring first.
To get a public key onto your keyring, you must first find the public key on a keyserver and
then import it from the keyserver onto your keyring.
Finding a Public Key on a Keyserver
In order to get a public key onto your keyring, you have to find the right key. In many
cases, you can get the key you need from a keyserver. You use the same procedure for a
public keyserver and a private keyserver.
Use the --keyserver-search command to search a keyserver for a key.
To search a keyserver for a key:
1On the command line, enter:
pgp --keyserver-search <input> --keyserver <ks>
where:
<input> is the user ID, portion of the user ID, or the key ID of the key for which
you are searching.
If you are searching by key ID, only an exact match will be found (you can find
the key ID of your key using the --list-keys command). If you are searching by
user ID, any key whose user ID contains the user ID or portion of the user ID you
enter will be found. So a search by user ID could return many matches, where a
search by key ID will return only one key.
<ks> is the name of the keyserver you want to search.
You can enter more than one keyserver, separated by a space. Only results from
the first keyserver where there is a match will be returned.
For example:
pgp --keyserver-search example.com --keyserver
ldap://keyserver.pgp.com
This search would return keys that have “example.com” in the user ID and are on
keyserver.pgp.com, a public keyserver.
2Press Enter when the command is complete.
PGP Command Line responds by listing the key or keys that match the search
criteria you specified in the following format:
PGP Command Line User’s Guide 5: First Steps
51
Alg Type Size/Type Flags Key ID User ID
--- ---- --------- ----- --------- -------
DSS pub 2048/1024 [-----] 0x1234ABCD Alice C <ac@example.com>
Importing a Public Key from a Keyserver
Once you have found the key you want on the keyserver, you need to get the key from
the keyserver onto your keyring.
Use the --keyserver-recv command to locate a key on a keyserver and import it
onto your keyring.
To import a key from a keyserver:
1On the command line, enter:
pgp --keyserver-recv <input> --keyserver <ks>
where:
<input> is the user ID, portion of the user ID, or key ID of the key you want to get
onto your keyring.
To get a specific key, use the key ID. To get one or more keys, use the user ID or
portion of the user ID.
<ks> is the name of the keyserver you want to search.
You can enter more than one keyserver to search, separated by a space. Only results
from the first keyserver where there is a match will be returned.
For example:
pgp --keyserver-recv 0xABCD1234 --keyserver
ldap://keyserver.pgp.com
The key with the key ID shown would be imported if it were on the specified
keyserver.
2Press Enter when the command is complete.
PGP Command Line responds by listing the key(s) it found on the specified
keyserver that matched the criteria you specified and that the key(s) was imported:
pgp:keyserver receive (2504:successful search on
ldap://keyserver.pgp.com)
0xABCD1234:keyserver receive (0:key imported as Alice C
<ac@example.com>.)
Caution
If you want to make sure the key was imported onto your keyring, use the --list-keys
command (the short form is -l) to see what keys are currently on your keyring.
PGP Command Line User’s Guide 5: First Steps
52
Verifying Keys
If you have information you want to send to someone privately, and you are going to the
trouble to encrypt it so that it stays private, then it is probably also important that you
make sure the public key you have obtained and are going to use to encrypt your
important information is actually from the person or organization that you believe it to be
from.
One way to do this is to compare the fingerprint of the public key you have with the
fingerprint of the real key. You could, for example, call the person on the phone and ask
them to read the fingerprint of their key.
Some people also put the fingerprint of their PGP key on their Web site or on their
business card, making it easy to compare the fingerprint of the real key with the
fingerprint of the public key you have.
Use the --fingerprint command to see the fingerprint of any of the keys currently on
your keyring; refer to “--fingerprint” on page 72 for more information.
To view the fingerprint of a key:
1On the command line, enter:
pgp --fingerprint <input>
where:
<input> is the user ID, portion of the user ID, or key ID of the key whose fingerprint
you want to see.
If you don’t enter any input, PGP Command Line will display the fingerprints of all
keys on your keyrings.
For example:
pgp --fingerprint 0xABCD1234
The user ID and the fingerprint of the key with the key ID shown would display if
it were on either keyring.
pgp --fingerprint
The user IDs and the fingerprints of all keys on both keyrings would display.
2Press Enter when the command is complete.
PGP Command Line responds by listing the user ID of the key(s) it found that
matched the criteria you specified and the fingerprint of that key using the following
format:
Alice Cameron <alice@example.com>
896A 4A96 9C3A 3BEC C87C EA8B 2CDB B87B 2CEB 53CC
53
6Cryptographic Operations
Descriptions and Examples of Cryptographic
Commands
This chapter describes the commands used in PGP Command Line that relate to
cryptographic operations. These commands are:
--armor, which converts a file to ASCII armor format (page 54).
--clearsign, which creates a clear signature (page 56).
--decrypt, which decrypts encrypted data (page 57).
--detached, which creates a detached signature (page 59).
--dump-packets, which dumps the packets in a PGP message (page 60).
--encrypt, which encrypts your data (page 61).
--export-session-key, which exports the session key that was used to encrypt
data to a separate file (page 64).
--list-sda, which lists the contents of an SDA (page 65).
--list-archive, which lists the contents of a PGP Zip archive (page 65)
--sign, which signs your data (page 66).
--symmetric, which encrypts data using a symmetric cipher (page 68).
--verify, which lets you verify data without creating any output (page 69).
Overview
This chapter covers four of PGP Command Lines most significant cryptographic
operations: encrypting, signing, decrypting, and verifying:
Encrypt: A method of scrambling information to render it unreadable to anyone
except the intended recipient, who must decrypt it to read it. You use PGP
Command Line to encrypt your important information so that if it is stolen from a
hard drive or intercepted while in transit, it is of no value to the person who has taken
it because they cannot decrypt it.
Sign: When you sign a message or file, PGP Command Line uses your private key
to create a digital code that is unique to both the contents of the message/file and
your private key. Only your public key can be used to verify your signature.
Decrypt: When you receive decrypted data, it’s of no value until you decrypt it. To do
this, you need to use the private key of the key pair that includes the public key that
was used to encrypt the data.
Verify: In addition to decrypting your data so that you can use it, you should also
verify the files you use with PGP Command Line, including data, signature, and key
files, to make sure they have not been tampered with.
PGP Command Line User’s Guide 6: Cryptographic Operations
54
For more information about these cryptographic operations, refer to An Introduction to
Cryptography, which was installed with PGP Command Line.
Commands
The commands that relate to encrypting and signing are described in the following
sections.
--armor (-a)
Armors data, produces a PGP armored file, and changes the default file extension from
.pgp or .sig to .asc. The resulting ASCII armored data format is used with email
systems that only allow ASCII printable characters. It converts the plaintext by expanding
groups of three binary 8-bit bytes into four (4) printable ASCII characters, and the resulting
file expands in size by approximately 33%.
The usage format is:
pgp --armor <input> [<input2> ...] [options]
Where:
<input> is the file to be armored. It is either in the current directory, or its location
has to be defined using a relative or absolute path. Multiple files can be armored.
[options] let you modify the command:
--comment. Saves a comment at the beginning of the file with the header tag
"Comment".
--compress. Compresses the output file.
--compression-algorithm. Sets the compression algorithm. The default for this
option is zip.
--eyes-only. Text inputs that are processed using this option can only be
decrypted to the screen.
--input-cleanup. This option will clean up the input file, depending on the
arguments you specify: off (default), remove, or wipe.
--output. Lets you specify a different name for the armored file.
--overwrite. Sets the overwrite behavior when PGP Command Line tries to
create an output file with the same name that already exists in the directory. This
option accepts the following arguments: off (default), remove, rename, or wipe.
--temp-cleanup. Cleans up the temporary file(s), depending on the arguments
you specify: off, remove, or wipe (default). For large encryption jobs, this option
should be set to remove to speed up the process.
--text. Forces the input to canonical text mode. Do not use with binary files.
Automatic detection of file types is not supported.
PGP Command Line User’s Guide 6: Cryptographic Operations
55
-v|--verbose. Gives a verbose (detailed) report about the operation.
The option --compression-algorithm is allowed when --armor is the primary
operation (armor only). When --armor is combined with --sign or --encrypt
operations, check these operations for details about setting the compression algorithm.
Examples:
1 pgp --armor report.txt --overwrite remove
The ASCII armored output file "report.txt.asc" replaced the existing file with the same
name, which was removed by overwriting.
2 pgp -a report.txt --compression-algorithm zlib
The ASCII armored file “report.txt.asc” is compressed using the ZLIB compression
algorithm.
Using --armor as an option with other commands to armor a file:
The usage format is:
pgp command1 input command2 user [--passphrase] pass --armor
Examples:
1 pgp --sign report.txt --signer <alice@example.com>
--passphrase cam3r0n --armor
The output file is an armored file “report.txt.asc”, which contains Alice’s signature.
2 pgp -er “Bill Brown” report.txt --armor --comment “Urgent”
Creates the ASCII armored file “report.txt.asc,” which is encrypted for Bill and has
the plaintext comment “Urgent” displayed on top of the encrypted file:
-----BEGIN PGP MESSAGE-----
Version: PGP Command Line v9.0.0 (OSX)
Comment: Urgent
qANQR1DBwEwDRB9gEpFtI3MBB/0UL7GQa1xr0LCp54FKg/
FN4KZNlr+DrD3IGi0P
e5xyNUQcYnQ2YqZYO2kDuFkOEJ1lE1HyixLs4m4ETYxhT3EH/
VA+yIjqqBHOwl6k
MXzGN9fNFcp8SoQZGVlOm6bLWOtRY/5W2E90B0iB+f3Pv/VHiN5gDO/
FmvzREJke
..
PGP Command Line User’s Guide 6: Cryptographic Operations
56
--clearsign
Causes the document to be wrapped in an ASCII-armored signature but otherwise
doesn't modify the document. The signed message can be verified to ensure that the
original document has not been changed. To verify the signed message, use --verify.
The usage format is:
pgp --clearsign <input> [<input2> ...] --signer <user>
--passphrase <pass> [options]
Where:
<input> is the name of the file to be clear-signed. It is required. You can clear-sign
multiple files by listing them, separated by a space.
<user> is the user ID, portion of the user ID, or the key ID of the clearsigner. The
private key of the clear-signer must be on the keyring. If <user> is not specified, the
default key is used.
<pass> is the passphrase of the private key of the clear-signer. It is required.
[options] let you modify the command. Options are:
--comment saves a comment at the beginning of the file with the header tag
"Comment".
--input-cleanup cleans up the input file, depending on the arguments you
specify: off (default), remove, or wipe.
--overwrite sets the overwrite behavior when PGP Command Line tries to create
an output file with the same name that already exists in the directory. This option
accepts the following arguments: off (default), remove, rename, or wipe.
--temp-cleanup cleans up the temporary file(s) depending on the arguments you
specify: off, remove, or wipe (default). For large encryption jobs, this option should be
set to remove to speed up the process.
--text forces the input to canonical text mode. Do not use with binary files
(automatic detection of file types is not supported).
-v|--verbose gives a verbose (detailed) report about the operation.
Example:
pgp --clearsign newnote.txt --signer bob@example.com
--passphrase sm1t4
newnote.txt:sign (0:output file newnote.txt.asc)
The resulting file "newnote.txt.asc" will have the unchanged text, "wrapped" between
the header and the footer such as this:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
(the unchanged text in the file "new.note.asc")
PGP Command Line User’s Guide 6: Cryptographic Operations
57
-----BEGIN PGP SIGNATURE-----
Version: PGP Command Line v9.0.0 (Win32)
iQEVAwUBQZF+rbnA+IViRSc+AQiSpQgAnaGd+6/
4iOoQ+bsawPB632cEE9Ypa6wL
/
9DeSFgn2mmFIIIOaHljBGheJpIhax4BBDut2ngpOxIUywMEpMuD3Zw05IUGD7n
r/+YseC6Hteb/
S3j9ib0JCd97IxE54MA5DvSX07xTqAjc1ddBqkP8tK28kTmlJGN
0QEFJ/zti/
k6IYSKP8QSQ+x+aTto2pioibk6QXz4NDWttZ30g4BFefxQnwNwYPf7
+kbq2fY+VHn0nkIPPrN+8vHskNklO4rxEZccLKPFGdoRPWc9hEkIqDEBOXt7CW
Jf
016AaKwF7wWtz1yWAZJXzfr/EHXRqOBWZb9F/cMimqgnvCnQI/i9VA==
=GE1E
-----END PGP SIGNATURE-----
--decrypt
Decrypts encrypted data.
If data being decrypted is also signed, the signature is automatically verified during the
decryption process.
The usage format is:
pgp --decrypt <input> [<input2> ...] [<inputd>...] [options]
Where:
--archive. When you decrypt archives, note the following:
– if you specify --archive, the contents of the archive are extracted
if you don't specify --archive, only the .tar file is extracted
<inputd>. Additional detached signature target files are allowed. Note that PGP
Command does not write output when decrypting detached signature files.
--eyes-only. Text inputs that are processed using this option can only be
decrypted to the screen: the recipient must view the output on screen when
decrypting a message. The default is off.
When decrypting data that is marked for your eyes only, PGP Command Line
generates an error if the option --eyes-only is not specified.
--input-cleanup cleans up the input file, depending on the arguments you
specify: off (default), remove, or wipe.
--output lets you specify a different name for the decrypted file.
--overwrite sets the overwrite behavior when PGP Command Line tries to create
an output file and it already exists. It accepts the following arguments: off (default),
remove, rename, or wipe.
PGP Command Line User’s Guide 6: Cryptographic Operations
58
--passphrase is used for [asymmetrically] encrypted files
--sda. When decrypting SDAs, the option --sda must be specified or PGP
Command Line will not be able to find PGP data.
To decrypt an SDA, you need either --symmetric-passphrase or
--passphrase. Note that the symmetric passphrase cannot have an empty string
(" "), while the asymmetric passphrase can have an empty string because such
passphrase references a private key.
When decrypting SDAs or archives, files will be automatically overwritten. The
option -o (output) can be used to specify the output directory; this directory will be
created if it does not exist.
--symmetric-passphrase is used for symmetrically encrypted files.
--temp-cleanup cleans up the temporary file(s), depending on the arguments you
specify: off, remove, or wipe (default). For large encryption jobs, this option should
be set to remove to speed up the process.
-v|--verbose gives a verbose (detailed) report about the operation.
Examples:
1 pgp --decrypt note.txt.pgp --symmetric-passphrase cam3r0n
--overwrite remove
Decrypts the file to "note.txt" and removes the existing file with the same name by
overwriting it.
2 pgp --decrypt keyshares.exe --sda --symmetric-passphrase sm1t4
keyshares.exe:decrypt (0:directory created successfully)
keyshares.exe:decrypt (0:output file keyshares\Alice
Cameron-1-Bob Smith.shf)
keyshares.exe:decrypt (0:output file keyshares\Alice
Cameron-2-John Jones.shf)
keyshares.exe:decrypt (0:output file keyshares\Alice
Cameron-3-Bill Brown.shf)
keyshares.exe:decrypt (0:output file keyshares\pgp)
keyshares.exe:decrypt (0:SDA decoded successfully)
Decrypts a SDA.
3 pgp --decrypt keyshares.exe --symmetric-passphrase sm1t4
keyshares.exe:decrypt (3031:input does not contain PGP data)
If you dont enter the option --sda. PGP Command Line will not recognize the SDA
you want to decrypt and uncompress.
4 pgp --decrypt note.txt.sig --passphrase sm1t4
note.txt:decrypt (1082:detached signature target file)
note.txt.sig:decrypt (3038:signing key 0x6245273E Bob Smith
<bob@example.com>)
PGP Command Line User’s Guide 6: Cryptographic Operations
59
note.txt.sig:decrypt (3040:signature created
2005-10-28T12:44:38-07:00)
note.txt.sig:decrypt (3035:good signature)
Decrypts the detached signature file "note.txt.sig". When decrypting detached
signature files, you will get only a status message as output.
5 pgp --decrypt bobsarchive.pgp --passphrase sm1t4
bobsarchive.pgp:decrypt (0:output file bobsarchive.tar)
Decrypts the archive file into a tar file.
6 pgp --decrypt bobsarchive.pgp --passphrase sm1t4 --archive
bobsarchive.pgp:decrypt (0:output file .\note.txt)
bobsarchive.pgp:decrypt (0:output file .\report.doc)
Decrypts the archive file into the actual archived files "note.txt" and report.doc,
with their path information included.
--detached (-b)
Signs data and creates a detached signature. If you use this command to sign a
document, both the document and detached signature are needed to verify the signature.
To verify the signed message, use --verify.
The usage format is:
pgp --detached <input> [<input2> ...] --signer <user>
--passphrase <pass> [options]
Where:
<input> is the name of the file for which the detached signature is being created. It
is required. You can create a detached signature for multiple files by listing them,
separated by a space.
<user> is the user ID, portion of the user ID, or the key ID of the signer. It is
required. The private key of the signer must be on the keyring.
<pass> is the passphrase of the private key of the signer. It is required.
[options] let you modify the command. Options are:
--armor armors the data and changes the file extension from .sig to .asc.
--comment saves a comment at the beginning of the file with the header tag
"Comment". It works only if --armor is specified as well.
--input-cleanup cleans up the input file, depending on the arguments you
specify: off (default), remove, or wipe.
--output lets you specify a different name for the created file.
--overwrite sets the overwrite behavior when PGP Command Line tries to create
an output file that already exists. This option accepts the following arguments: off
(default), remove, rename, or wipe.
PGP Command Line User’s Guide 6: Cryptographic Operations
60
--temp-cleanup cleans up the temporary file(s), depending on the arguments you
specify: off, remove, or wipe (default). For large encryption jobs, this option should
be set to remove to speed up the process.
--text forces the input to canonical text mode. Do not use this option with binary
files (automatic detection of file types is not supported).
-v|--verbose gives a verbose (detailed) report about the operation.
Examples:
1 pgp -b note.txt --passphrase sm1t4 --signer “Bob Smith”
note.txt:sign (0:output file note.txt.sig)
Output is the file note.txt.sig, which contains Bob’s detached signature.
2 pgp --verify note.txt.sig
note.txt:verify (1082:detached signature target file)
note.txt.sig:verify (3038:signing key 0x6245273E Bob Smith
<bob@example.com>)
note.txt.sig:verify (3040:signature created
2005-10-28T12:44:38-07:00)
note.txt.sig:verify (3035:good signature)
note.txt.sig:verify (0:verify complete)
The detached signature is verified:
--dump-packets, --list-packets
Dumps the packet information in a PGP message. Input is a list of files or standard input;
output is always a standard output.
This command uses the normal output format for data blocks and displays hexadecimal
values in the format "NN".
The usage format is:
pgp --dump-packets <input> [<input2> …] [options]
Where:
<input> is a list of files or standard input.
<input2> are additional files.
[options] let you modify the command. Options are:
--buffered-stdio enables buffered stdio for stdin and stdout.
Example:
pgp --dump-packets TrainingDetails.msg
Processing file TrainingDetails.msg
New: unknown(tag 16)(4049 bytes)
Old: Trust Packet(tag 12)(46 bytes)
PGP Command Line User’s Guide 6: Cryptographic Operations
61
Trust - 00 30 00 5f 00 30 00 30 00 36 00 34 00 30 00 30 00
31 00 45 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 2a
Old: Reserved(tag 0)(2 bytes)
File TrainingDetails.msg complete
--encrypt (-e)
Encrypts a document to specified recipients. Input is either the standard input or a list of
files. Output is either the standard output, a list of files, or an archive. If you use standard
input, note that it cannot be combined with other inputs.
When encrypting, the preferred cipher and compression algorithms of the recipient is
used. If there is more than one recipient, the most compatible algorithm is used. Note
that you cannot specify a one-time cipher or compression algorithm with --encrypt.
The usage format is:
pgp --encrypt <input> [<input2> ...] --recipient <user>
[-r <user2> ...] [options]
Where:
<input> is the name of the file to be encrypted. It is required. You can encrypt
multiple files by listing them, separated by a space. The default output filename for
an encrypted file is <input filename>.pgp. Note that stdin can be used only by
itself and cannot be combined with other inputs.
<user> is the user ID, portion of the user ID, or the key ID of the recipient. It is
required. The public key of the recipient must be on the keyring. You must specify a
recipient; you cannot encrypt to your own key by not specifying a recipient. You can
encrypt the file to multiple recipients by listing them, separated by a space.
[options] let you modify the command. Options are:
--adk can be used only together with the option --sda. Note that if any of the keys
used with the option --adk have ADKs, they will also be used.
--archive saves the output as an archive. It cannot be used with the options
--text-mode or --sda. When using --archive, directories can be in the input
file: without this option, the directories are skipped.
-a or --armor armors the encrypted file.
--cipher. If the option --cipher is used, the existing cipher will be forcefully
overridden and the key preferences and algorithm lists in the SDK will be ignored.
This can create messages that don’t comply with the OpenPGP standard. This option
must be used together with the option --force.
Caution
The --encrypt command is not used for symmetric encryption; instead, use the
--symmetric command, described in “--symmetric (-c)” on page 68.
PGP Command Line User’s Guide 6: Cryptographic Operations
62
--comment saves a comment at the beginning of the file with the header tag
"Comment". It works only if --armor is specified as well.
--compress toggles compression. If enabled, the preferred compression algorithm
of the recipient is used.
--compression-algorithm. If the option --compression-algorithm is used,
the existing compression algorithm will be forcefully overridden and the key
preferences and algorithm lists in the SDK will be ignored. This can create messages
that do not comply with the OpenPGP standard. This option must be used together
with the option --force.
--encrypt-to-self lets you encrypt to the default key in addition to any other
specified keys. The default is off.
--eyes-only. Text inputs that are processed using this option can only be
decrypted to the screen.
--force required to use --compression-algorithm and --cipher.
--input-cleanup cleans up the input file, depending on the arguments you
specify: off (default), remove, or wipe.
--output lets you specify a different name for the encrypted file.
--overwrite sets the overwrite behavior when PGP Command Line tries to create
an output file that already exists. This option accepts the following arguments: off
(default), remove, rename, or wipe.
--root-path can only be used with either --sda or --archive.
--sda cannot be used together with the command --sign (such as -es). For more
information, refer to the option --sda.
--sign lets you sign the encrypted file.
--temp-cleanup cleans up the temporary file(s) depending on the arguments you
specify: off, remove, or wipe (default). For large encryption jobs, this option should
be set to remove to speed up the process.
--text forces the input to canonical text mode. Do not use with binary files
(automatic detection of file types is not supported).
-v |--verbose gives a verbose (detailed) report about the operation.
Refer to the descriptions of these options or to the man page for information about how
to use these options.
Examples:
1 pgp --encrypt report.txt README.rtf -r "Bill Brown" -r "Mary
Smith" -r "Bob Smith"
The files "report.txt" and "README.rtf" are encrypted to multiple recipients.
PGP Command Line User’s Guide 6: Cryptographic Operations
63
2 pgp -er "Bob Smith" report.txt --eyes-only
The output file "readme.txt.pgp" is encrypted for Bob’s "eyes only", which means that
he can read the file only on the screen.
3 pgp -e report.doc -r "Bob Smith" --output newreport.pgp -v
The output file is "newreport.pgp", and the on-screen message contains the following
detailed information about the performed operation:
pgp:encrypt (3157:current local time
2005-11-05T12:13:09-08:00)
/Users/bobsmith/.pgp/pubring.pkr:open keyrings (1006:public
keyring)
/Users/bobsmith/.pgp/secring.skr:open keyrings (1007:private
keyring)
0x4A8C54B8:encrypt (1030:key added to recipient list)
report.doc:encrypt (3048:data encrypted with cipher AES-128)
report.doc:encrypt (0:output file newreport.pgp)
4 pgp -er "Bob Smith" report.doc --output /Users
report.doc:encrypt (0:output file /Users/report.doc.pgp)
You have encrypted the file report.doc to the specified directory.
5 pgp -er "Bob Smith" *.doc
myreport.doc:encrypt (0:output file myreport.doc.pgp)
report.doc:encrypt (0:output file report.doc.pgp)
Both files with the extension .doc were encrypted for the user Bob.
6 pgp -er "Bob Smith" *.doc -output /Users
myreport.doc:encrypt (0:output file /Users/myreport.doc.pgp)
report.doc:encrypt (0:output file /Users/report.doc.pgp)
You have encrypted all files with the extension .doc to another directory.
7 pgp -er "Bob Smith" *.doc --output archive.pgp
pgp:encrypt (3028:multiple inputs cannot be sent to a single
output file)
Nothing happened since the archive mode was not enabled.
8 pgp -er "Bob Smith" *.doc --output archive.pgp --archive
pgp00000.tmp:encrypt (3110:archive imported myreport.doc)
pgp00000.tmp:encrypt (3110:archive imported report.doc)
pgp00000.tmp:encrypt (0:output file archive.pgp)
With the option --archive added, the two doc files are encrypted into archive.pgp.
9 pgp -er "Bob Smith" /Users/note.txt
/Users/note.txt:encrypt (0:output file /Users/note.txt.pgp)
In this case, you have encrypted the file note.txt, which was located in another
directory.
PGP Command Line User’s Guide 6: Cryptographic Operations
64
10 pgp -er "Bob Smith" /Users/*.txt -o MyNewArchive.pgp --archive
pgp00000.tmp:encrypt (3110:archive imported /Users/note.txt)
pgp00000.tmp:encrypt (3110:archive imported /Users/note2.txt)
pgp00000.tmp:encrypt (0:output file MyNewArchive.pgp)
In this case, you have encrypted multiple text files located in another directory into a
new archive in your local directory.
--export-session-key
Exports the session key of an encrypted message. This key is used to encrypt each set of
data on a transaction basis, and a different session key is used for each communication
session. Output of this command is a key file with the extension .key, which contains the
key fingerprint of the key used during the session that produced the encrypted file.
Using the session key, it is possible to decrypt a document without the recipients private
key and its passphrase. Therefore, it reveals only the content of a specific message
without compromising the private recipient’s key (which would reveal all messages
encrypted to that key). Note that a user cannot directly specify a session key during
encryption.
The usage format is:
pgp --export-session-key <input> [<input2> ...] --passphrase
<pass> [--output]
Where:
<input> is the encrypted file whose session key is to be exported to a separate file.
It is required. Multiple files can have their session key exported as well; each
encrypted file must be listed, separated by a space.
--passphrase is needed for encrypted files (--symmetric-passphrase is used
for conventionally encrypted files, but --passphrase will also work)
--output lets you specify a different filename for the resulting file.
Refer to the descriptions of these options for information about how to use them.
Example:
1 pgp -e report.doc -r "Bob Smith" --output BobsReport.pgp
report.doc:encrypt (0:output file BobsReport.pgp)
First, the file report.doc was encrypted into BobsReport.pgp.
2 pgp --export-session-key BobsReport.pgp --passphrase sm1t4
BobsReport.pgp:export session key (0:output file report.doc.key)
Second, the key used for the encrypting session was exported into the file
report.doc.key, which contains the fingerprint of the key used for the session,
such as:
7:8F042E99E383FCD4921FD74A63C514D3
PGP Command Line User’s Guide 6: Cryptographic Operations
65
--list-sda
Lists the contents of a Self-Decrypting Archive (SDA). The entire SDA needs to be
decrypted in order to list its contents, which could take up to several minutes (depending
on the number and size of the files in the archive).
The usage format is:
pgp --list-sda <input> --passphrase <pass>
Where:
<input> is an SDA file, such as reports.exe. Output is always the standard output.
<pass> This is a passphrase or symmetric passphrase with which the SDA was
encrypted.
Example:
pgp --list-sda reports.exe --symmetric-passphrase sm1t4
reports\
reports\README.rtf
reports\README.txt
reports\report.txt
reports.exe:list SDA (0:SDA decoded successfully)
The archive “reports.exe” was decrypted and listed.
--list-archive
Lists the contents of a PGP Zip archive, which lets you add any combination of files and
folders to an encrypted, compressed, portable archive.
A PGP Zip archive is an excellent way to distribute files and folders securely or back them
up. Refer to “--archive” on page 140 for more information about PGP Zip archives.
The usage format is:
pgp --list-archive <input> [<input2> ...] --passphrase <pass>
Where:
<input> is the PGP archive(s) whose files you want to list.
<pass> is the passphrase of the archive whose files you want to list.
Example:
pgp --list-archive archive.pgp --passphrase sm1t4
In this case, the archive is located in the local directory and no directory path is
displayed.
report.txt
README.txt
PGP Command Line User’s Guide 6: Cryptographic Operations
66
--sign (-s)
Signs a document, without encrypting it. You can sign and encrypt a file at the same time
using the command -es. Input is a standard input or a list of files; output is a standard
output or a list of files.
The usage format is:
pgp --sign <input> [<input2> ...] --passphrase <pass>
[--signer <user>] [options]
Where:
<input> is the name of the file to be signed. It is required. You can sign multiple files
by listing them, separated by a space.
<pass> is the passphrase of the private key of the signer. It is required.<user> is
the user ID, portion of the user ID, or the key ID of the signer. The private key of the
signer must be on the keyring. If <user> is not specified, the default key is used to
sign.
--archive allows you to create an unencrypted signed tar file. You cannot use this
archive until it is decrypted (the signature is removed). Using the option --sign with
--archive, you can create a signed tar file that anyone can open.
-a , --armor. Armors the signed file.
--comment saves a comment at the beginning of the file with the header tag
"Comment". It works only if --armor is specified as well.
--compress toggles compression.
--compression-algorithm. You can select the compression algorithm in case
you are creating an attached opaque signature only (that is not encrypted), or when
you are creating a conventionally encrypted and signed output.
--eyes-only. Text inputs that are processed using this option can be decrypted
only to the screen.
--force. Required to use --hash.
--hash. If you use this option, the existing hash algorithm will be forcefully
overridden. Note that the key preferences and algorithm lists in the SDK will be
ignored, which can lead to the creation of messages that violate OpenPGP standard.
You must use the option --force with --hash.
--input-cleanup cleans up the input file, depending on the arguments you
specify: off (default), remove, or wipe.
--output lets you specify a different name for the signed file.
--overwrite sets the overwrite behavior when PGP Command Line tries to create
an output file that already exists. This option accepts the following arguments: off
(default), remove, rename, or wipe.
--temp-cleanup cleans up the temporary file(s) depending on the arguments you
specify: off, remove, or wipe (default). For large encryption jobs, this option should be
set to remove to speed up the process.
PGP Command Line User’s Guide 6: Cryptographic Operations
67
--text forces the input to canonical text mode. Do not use with binary files
(automatic detection of file types is not supported).
-v|--verbose gives a verbose (detailed) report about the operation.
Refer to the descriptions of these options or to the man page for information about how
to use these options.
Examples:
1 pgp -s report.txt --signer "Bob Smith" --passphrase sm1t4
report.txt:sign (0:output file report.txt.pgp)
Output is "report.txt.pgp" signed by Bob.
2 pgp -es report.txt -r bob@example.com --passphrase cam3r0n
This command produces "report.txt.pgp," which is encrypted for Bob and signed by
Alice using her passphrase (we assume that her key is the default signing key and
the option --signer is not used).
3 pgp -s report.txt --signer "Bob Smith" --passphrase sm1t4
--compression-algorithm zip
report.txt:sign (0:output file report.txt.pgp)
The file "report.txt.pgp" was signed by Bob and compressed using the Zip
compression algorithm.
4 pgp -s report.doc note.txt --signer "Bob Smith" --passphrase
sm1t4 -o NewArchive.pgp --archive
pgp00001.tmp:sign (3110:archive imported report.doc)
pgp00001.tmp:sign (3110:archive imported note.txt)
pgp00001.tmp:sign (0:output file NewArchive.pgp)
First, both files are signed and saved as a tar file NewArchive.pgp. This file cannot be
used until the signature is removed by decrypting the file. This file is just opaquely
signed, and you do not need a passphrase to verify the signature:
pgp --decrypt NewArchive.pgp
NewArchive.pgp:decrypt (3038:signing key 0x6245273E Bob Smith
<bob@example.com>)
NewArchive.pgp:decrypt (3040:signature created
2005-11-11T16:40:42-08:00)
NewArchive.pgp:decrypt (3035:good signature)
NewArchive.pgp:decrypt (0:output file NewArchive.tar)
The resulting tar file can be uncompressed with utilities that are appropriate for your
platform.
PGP Command Line User’s Guide 6: Cryptographic Operations
68
--symmetric (-c)
Encrypts data using symmetric encryption, not public-key encryption.
The usage format is:
pgp --symmetric <input> [<input2> ...] --symmetric-passphrase
<pass> [options]
Where:
<input> is the name of the file to be symmetrically encrypted and it is required. You
can encrypt multiple files by listing them, separated by a space. The default filename
for an encrypted file is <input filename>.pgp. You can modify the filename of
the encrypted file using --output.
<pass> is the passphrase you want to use for the symmetrically encrypted file.
[options] let you modify the command. Options are:
--output lets you specify a different filename for the encrypted file.
--sign lets you sign the encrypted file. If you use --sign with --symmetric, you will
need both --symmetric-passphrase for the encryption and --passphrase for the
signature.
--armor armors the output file. File extension is changed to .asc.
--comment lets you specify a comment for armored data.
--text forces the <input> to canonical text mode. Do not use with binary files.
Automatic detection of file type is not supported.
--compress toggles compression.
--compression-algorithm specifies the compression algorithm to use for the
operation. The default is Zip.
--cipher specifies the cipher to use for the operation. The default is AES256.
--eyes-only prevents the decrypted output from being saved to disk; the
decrypted output can only be displayed on-screen.
--encrypt-to-self lets you encrypt to the default key.
--archive lets you combine multiple files into a single .pgp file.
--overwrite lets you specify what to do if a file of the same name as the output
filename already exists.
--input-cleanup lets you specify what to do with <input> files when the
operation is done. The default is off (leave them alone).
--temp-cleanup lets you specify how to handle temporary files. The default is to
wipe them.
--verbose (-v) shows verbose results information.
PGP Command Line User’s Guide 6: Cryptographic Operations
69
Examples:
1 pgp --symmetric file.txt --symmetric-passphrase Bilbo$Frodo
Encrypts a file, which will be called file.txt.pgp, using the passphrase
"Bilbo$Frodo" without the quotes.
2 pgp -ec file.txt --symmetric-passphrase Bilbo$Frodo
Same as above, using the short forms.
The important information about --encrypt also applies to --symmetric.
--verify
Verifies that data was not tampered with and tests whether PGP Command Line can
process the entire file.
It verifies data, signatures, and key files and works on all PGP Command Line data types.
The command output describes what was verified.
The usage format is:
pgp --verify <input> [<input2> ...] [options]
Where:
<input> is the file to be verified. It is required.
[options] let you modify the command. Options are:
--input-cleanup cleans up the input file, depending on the arguments you
specify: off (default), remove, or wipe.
--passphrase|--symmetric-passphrase. This is the passphrase that is
required for encrypted files.
--temp-cleanup cleans up the temporary file(s) depending on the arguments you
specify: off, remove, or wipe (default). For large encryption jobs, this option should be
set to remove to speed up the process.
-v|--verbose gives a verbose (detailed) report about the operation.
Refer to the descriptions of these options for information about how to use them.
Example:
pgp --verify report.doc.pgp --passphrase smit4
report.doc.pgp:verify (3111:data is a PGP archive)
report.doc.pgp:verify (3042:suggested output file name
report.doc.tar)
report.doc.pgp:verify (3038:signing key 0x6245273E Bob Smith
<bob@example.com>)
report.doc.pgp:verify (3040:signature created
2005-11-10T13:58:07-08:00)
report.doc.pgp:verify (3035:good signature)
PGP Command Line User’s Guide 6: Cryptographic Operations
70
report.doc.pgp:verify (0:verify complete)
The file report.doc.pgp is verified.
71
7Key Listings
How to Get Information About Your Keys
This chapter describes the commands that list information about the PGP keys on
keyrings. These commands are:
--fingerprint, which lists the fingerprints of keys on your keyring, in hexadecimal
numbers or biometric words (page 72).
--fingerprint-details, which lists the fingerprints of keys on your keyring and
their subkeys, in hexadecimal numbers or biometric words (page 72).
--list-key-details, which lists the keys on the keyring and displays detailed
information about those keys (page 75).
--list-keys, which lists the keys on the keyring (page 76).
--list-keys-xml, which lists keys in XML format (page 77).
--list-sig-details, which provides detailed information about signatures on a
key (page 78).
--list-sigs, which lists the keys on the keyring and the user IDs and signatures on
those keys (page 78).
--list-userids, which lists the keys on the keyring and the user IDs on those keys
(page 79).
Overview
At some point, you are going to need to know about the keys on your keyrings. The key
listing commands provide those details. Using the commands in basic display mode gives
you summary information about the keys on a keyring. Detailed display mode tells you
everything there is to know about those keys.
Refer to Appendix A, Lists for more information about what the key and signature lists
show about a key.
PGP Command Line User’s Guide 7: Key Listings
72
Commands
The key listing commands are described in the following sections.
--fingerprint
Lists the fingerprints of keys on your keyring that match the supplied criteria. If you run
the command with no user or key ID information, all key fingerprints will be displayed. If
you enter any user or key ID information, only key fingerprints that match will be
displayed.
The usage format is:
pgp --fingerprint [<user1> ...] [--biometric] [--verbose]
Where:
<user1> is the user ID, portion of a user ID, or the key ID of a key on your keyring. If
you don’t supply a user ID, all fingerprints will be listed.
--biometric displays biometric words instead of hexadecimal numbers.
--verbose shows the key IDs under the primary user ID for each fingerprint.
Examples:
pgp --fingerprint Alice
Displays the fingerprint in hexadecimal of any keys on the keyring that match "Alice"
using the format:
Alice Cameron <alice@example.com>
896A 4A96 9C3A 3BEC C87C EA8B 2CDB B87B 2CEB 53CC
pgp --fingerprint 0x12345678 --biometric
Displays the fingerprint in biometric words of the key with the specified key ID using
the format:
Alice Cameron <alice@example.com>
aimless photograph goldfish yesteryear
beeswax corporate crackdown millionaire
indoors upcoming choking sardonic
reward underfoot eyeglass amulet
sawdust holiness glitter therapist
1 key found
PGP Command Line User’s Guide 7: Key Listings
73
--fingerprint-details
Lists the fingerprints and subkeys of keys on your keyring that match the supplied criteria.
If you run the command with no user or key ID information, all key fingerprints will be
displayed. If you enter any user or key ID information, only key fingerprints that match will
be displayed.
Subkey fingerprints are displayed if found on the specified key. Hash names are the same
as listed in the detailed key list mode.
Fingerprints are shown with one of the following prefixes:
Key Fingerprint indicates that the following fingerprint is for a master key.
Subkey Fingerprint indicates that the following fingerprint is for a subkey.
X.509 <alg> Thumbprint indicates that the following thumbprint is for an X.509
certificate, where <alg> is replaced by the hash algorithm used to create the
thumbprint.
The usage format is:
pgp --fingerprint-details [<user1> ...] [--biometric]
Where:
<user1> is the user ID, portion of a user ID, or the key ID of a key on your keyring. If
you do not supply a user ID, all fingerprints and subkeys will be listed.
--biometric displays biometric words instead of hexadecimal numbers.
Examples:
pgp --fingerprint-details Alice
Displays the fingerprint in hexadecimal of any keys on the keyring that match "Alice"
using the format:
Alice Cameron <alice@example.com>
Key Fingerprint: 0x6D2A476D (0x7B72AAE06D2A476D)
D2E0 23B2 53D0 49C9 6812 31AC 7B72 AAE0 6D2A 476D
Subkey Fingerprint: 0xB86FF2CF (0x0787EE48B86FF2CF)
DAB6 570B 9411 197D 5DDF A9B2 0787 EE48 B86F F2CF
PGP Command Line User’s Guide 7: Key Listings
74
pgp --fingerprint-details 0xF88C6910 --biometric
Displays the key and subkey fingerprints in biometric words of the key with the
specified key ID using the format:
Alice Cameron <alice@example.com>
Key Fingerprint: 0x6D2A476D (0x7B72AAE06D2A476D)
crucial performance ragtime adviser
robust molasses stairway sardonic
beehive quantity spindle gravity
reform monument artist supportive
Vulcan megaton gazelle autopsy
Subkey Fingerprint: 0xB86FF2CF (0x0787EE48B86FF2CF)
chatter decimal snowcap caravan
breadline caravan pupil decimal
beeswax Wilmington tunnel nebula
bombast outfielder endorse Jupiter
preclude Eskimo drainage sandalwood
PGP Command Line User’s Guide 7: Key Listings
75
--list-key-details
Lists the keys on a keyring in detailed output mode. If you run the command with no user
or key ID information, all keys on the keyring will be displayed. If you enter any user or key
ID information, only keys that match will be displayed.
The usage format is:
pgp --list-key-details [<user1> ...]
Where:
<user1> is the user ID, portion of a user ID, or the key ID of a key on your keyring.
Example:
pgp --list-key-details Alice
Lists all of the keys on your keyrings using the format:
Key Details: Alice Cameron <alice@example.com>
Key ID: 0xB2726BDF (0xAAEB5E06B2726BDF)
Type: RSA (v4) key
Size: 2048
Validity: Complete
Trust: Implicit (Axiomatic)
Created: 2003-04-22
Expires: Never
Status: Active
Cipher: AES-192
Cipher: AES-128
Cipher: CAST5
Cipher: TripleDES
Cipher: Twofish-256
Hash: SHA
Compress: Zip (Default)
Photo: No
Revocable: No
Token: No
Keyserver: keyserver.pgp.com
Default: No
Prop Flags: Sign user IDs
Prop Flags: Sign messages
Ksrv Flags: None
Feat Flags: Modification detection
Notations: 01 0x80000000 preferred-email-encoding@pgp.com:pgpmime
Subkey ID: 0x6F742FE6 (0x939BB8896F742FE6)
Type: ElGamal
Size: 2048
Created: 2003-04-22
Expires: Never
Status: Active
Revocable: No
Prop Flags: Encrypt communications
Prop Flags: Encrypt storage
ADK: None
PGP Command Line User’s Guide 7: Key Listings
76
Revoker: None
1 key found
For more information, refer to “Detailed Key List” on page 193.
--list-keys (-l)
Lists the keys on a keyring in basic output mode. If you run the command with no user or
key ID information, all keys on the keyring will be displayed. If you enter any user or key
ID information, only keys that match will be displayed.
The usage format is:
pgp --list-keys [<user1> ...]
Where:
<user1> is the user ID, portion of a user ID, or the key ID of a key on your keyring.
Examples:
1 pgp --list-keys
Lists all of the keys on your keyrings using the format:
Alg Type Size/Type Flags Key ID User ID
--- ---- --------- ------- ---------- ------------------------
DSS pub 2048/1024 [-----] 0xABCD1234 Alice C <ac@example.com>
1 key found
2 pgp -l Alice Bob Jill
Uses the short form of the command; displays any key on the keyring with "Alice",
"Bob", or "Jill" in the user ID.
3 pgp -l 0x12345678
Lists only the key with the specified key ID, if it is on the keyring.
For more information, refer to “Basic Key List” on page 187.
PGP Command Line User’s Guide 7: Key Listings
77
--list-keys-xml
When you choose to list a key in XML format, PGP Command Line will display all
information including all user IDs and signatures. If you run the command with no user or
key ID information, all keys on the keyring will be displayed. If you enter any user or key
ID information, only keys that match will be displayed.
To list keys in XML format, you may use either the command --list-keys-xml, or a key
list operation with the added option --xml, such as --list-keys user1 --xml, or
--list-keys --xml.
The usage format is:
pgp --list-keys-xml [<user1> …]
Where:
<user1> is the name of the specific local user whose keys you want to check.
Example:
pgp --list-keys-xml "Jose Medina"
Here is an abbreviated key list in XML format. For more details and explanations, refer to
“Key List in XML Format” on page 206.
<?xml version="1.0"?>
<keyList>
<key>
....
<signature>
...
<subkey>
...
<adk>
...
<revoker>
</key>
</keyList>
PGP Command Line User’s Guide 7: Key Listings
78
--list-sig-details
Lists keys with their user IDs and signatures in detailed output mode.
The usage format is:
pgp --list-sig-details <user> [<user2> ...]
Where:
<user> is the user ID, portion of a user ID, or the key ID of a key on your keyring. You
can list one or more users, with their names/IDs separated by a space. If you dont
specify a user, you will get an error message ("too many keys found").
Example:
pgp --list-sig-details Alice
Lists Alice’s key and shows details about her user IDs and signatures:
Signature Details: Alice Cameron <alice@example.com>
Signed Key ID: 0xB2726BDF (0xAAEB5E06B2726BDF)
Signed User ID: Alice Cameron <alice@example.com>
Signer Key ID: 0xB2726BDF (0xAAEB5E06B2726BDF)
Signer User ID: Alice Cameron <alice@example.com>
Type: DSA signature
Exportable: Yes
Status: Active
Created: 2003-04-22
Expires: Never
Trust Depth: 0
Domain: None
1 signature found
For more information, refer to “Detailed Signature List” on page 213.
--list-sigs
Lists keys with their user IDs and signatures in basic output mode. If you run the
command with no user or key ID information, all signatures on the keyring will be
displayed. If you enter any user or key ID information, only signatures that match will be
displayed.
The usage format is:
pgp --list-sigs [<user1> ...]
Where:
<user1> is the user ID, portion of a user ID, or the key ID of a key on the keyring.
Example:
pgp --list-sigs 0x12345678
Lists the user IDs and signatures on the key with the specified key ID, if it is on the
keyring.
PGP Command Line User’s Guide 7: Key Listings
79
--list-userids
Lists keys and their user IDs in basic output mode. The command --list-users is the
same as --list-userids.
The usage format is:
pgp --list-userids [<user1> ...]
Where:
<user1> is the user ID, portion of a user ID, or the key ID of a key on your keyring.
Examples:
1 pgp --list-userids
Lists all of the user IDs on the keys on your keyrings.
2 pgp --list-users
Same as the previous command, using the other form of the command.
3 pgp --list-userids Alice Bob Jill
Lists any key on the keyring with "Alice", "Bob", or "Jill" in the user ID.
PGP Command Line User’s Guide 7: Key Listings
80
81
8Working with Keyservers
Descriptions and Examples of Keyserver Commands
This chapter describes those commands that explain how PGP Command Line interacts
with keyservers.
--keyserver-disable, which disables keys on a keyserver (page 81).
--keyserver-recv, which gets keys from a keyserver and imports them onto
your keyring (page 82).
--keyserver-remove, which removes keys from a keyserver (page 83).
--keyserver-search, which searches a keyserver for keys but does not import
them (page 84).
--keyserver-send, which sends keys to a keyserver (page 85).
--keyserver-update, which updates keys on a keyserver (page 86).
Overview
PGP Command Line provides several commands that let you interact with keyservers.
These commands help you post keys to a keyserver, import keys from a keyserver, and
so on.
When using commands that require you to specify a keyserver, make sure to use the full
URL to the keyserver such as ldap://keyserver.pgp.com, and not just
keyserver.pgp.com.
Commands
--keyserver-disable
Disables a key on a keyserver. Note that this command only works with the legacy PGP
Keyserver product.
Requests for disabling a key must be signed. If no signer is supplied, the default signing
key is used. Key disable requires an exact match on the key to be removed.
If a keyserver is specified on the command line, any keyservers listed in the PGP
Command Line configuration file will not be used.
The usage format is:
pgp --keyserver-disable <input> [--keyserver <ks1> ...]
[--signer <signer>] [--passphrase <pass>] [options]
PGP Command Line User’s Guide 8: Working with Keyservers
82
Where:
<input> is the user ID, portion of the user ID, or key ID of the key you want
disabled on the keyserver. Key disable requires an exact match on the key to be
disabled.
<ks> is the name of the keyserver where the key to be disabled is located.
You can enter more than one keyserver, separated by a space.
[options] let you modify the command.Options are:
--signer the user ID of the signer.
--passphrase the passphrase of the signer.
--keyserver-timeout sets the number of seconds until the keyserver operation
times out. The default setting is 120 seconds.
--halt-on-error stops if an error occurs, if more than one keyserver is specified,
or the operation stops.
Example:
pgp --keyserver-disable 0x12345678 --keyserver
ldap://keyserver.example.com --signer "Alice Cameron
<alice@example.com>" --passphrase Bilbo*Baggins
The specified key is disabled on the specified keyserver.
--keyserver-recv
Finds keys on a keyserver and imports them onto your keyring. Keyservers are searched
in the order provided on the command line. As soon as a match is made on a keyserver,
the operation will finish and all other keyservers on the list will be ignored.
If a keyserver is specified on the command line, any keyservers listed in the PGP
Command Line configuration file will not be used. Preferred keyservers are not used.
Note that you cannot search for disabled or pending keys.
The usage format is:
pgp --keyserver-recv <input> [<input2> ...] --keyserver <ks>
[--keyserver <ks2> ...] [options]
Where:
<input> is the user ID, portion of the user ID, or key ID of the key you want to get
onto your keyring.
To get a specific key, use the key ID. To get one or more keys, use the user ID or
portion of the user ID.
<ks> is the name of the keyserver you want to search.
You can enter more than one keyserver to search, separated by a space. Only results
from the first keyserver where there is a match will be returned.
PGP Command Line User’s Guide 8: Working with Keyservers
83
[options] let you modify the command. Options are:
--keyserver-timeout sets the number of seconds until the keyserver operation
times out. The default setting is 120 seconds.
--halt-on-error stops if an error occurs, if more than one keyserver is specified,
or the operation stops.
For example:
pgp --keyserver-recv 0xABCD1234 --keyserver
ldap://keyserver.pgp.com
The key with the key ID shown would be imported if it were on the specified
keyserver.
pgp --keyserver-recv Jim --keyserver http://keyserver.pgp.com
All keys that have "Jim" in their user IDs would be found and imported.
--keyserver-remove
Removes a key from a keyserver. Note that this command only works with the legacy
PGP Keyserver product.
Requests for removal must be signed. If no signer is supplied, the default signing key is
used. Key removal requires an exact match on the key to be removed.
If a keyserver is specified on the command line, any keyservers listed in the PGP
Command Line configuration file will not be used.
The usage format is:
pgp --keyserver-remove <input> [--keyserver <ks1> ...]
[--signer <signer>] [--passphrase <pass>] [options]
Where:
<input> is the user ID, portion of the user ID, or key ID of the key you want
removed from the keyserver. Key removal requires an exact match on the key to be
removed.
<ks> is the name of the keyserver from which you want the key removed.
You can enter more than one keyserver, separated by a space.
[options] let you modify the command. Options are:
--signer the user ID of the signer.
--passphrase the passphrase of the signer.
--keyserver-timeout sets the number of seconds until the keyserver operation
times out. The default setting is 120 seconds.
--halt-on-error stops if an error occurs, if more than one keyserver is specified,
or the operation stops.
PGP Command Line User’s Guide 8: Working with Keyservers
84
Example:
pgp --keyserver-remove 0x12345678 --keyserver ldap://
keyserver.pgp.com --signer "bob@example.com" --passphrase
sm1t4
Removes the specified key from the specified keyserver.
--keyserver-search
Searches a keyserver for keys and lists those that it finds that match the criteria; it does
not import them.
Keyservers are searched in the order provided on the command line. As soon as a match
is made on a keyserver, the operation finishes; all other keyservers in the list after the one
that made the match will be ignored.
If a keyserver is specified on the command line, any keyservers listed in the PGP
Command Line configuration file will not be used. Preferred keyservers are not used. You
cannot search for disabled or pending keys.
The usage format is:
pgp --keyserver-search <input> [<input2> ...] --keyserver <ks>
[--keyserver <ks2> ...] [options]
Where:
<input> is the user ID, portion of the user ID, or key ID of the key for which you are
searching.
To find a specific key, use the key ID. To find one or more keys, use the user ID or
portion of the user ID.
<ks> is the name of the keyserver you want to search.
You can enter more than one keyserver to search, separated by a space. Only results
from the first keyserver where there is a match will be returned.
[options] let you modify the command. Options are:
--keyserver-timeout sets the number of seconds until the keyserver operation
times out. The default setting is 120 seconds.
--halt-on-error stops if an error occurs, if more than one keyserver is specified,
or the operation stops.
Example:
pgp --keyserver-search example.com --keyserver
ldap://keyserver.pgp.com
This search would return keys that have example.com in the user ID and are on
keyserver.pgp.com, a public keyserver.
PGP Command Line User’s Guide 8: Working with Keyservers
85
--keyserver-send
Posts a public key to a keyserver. If multiple keyservers are specified, in most cases only
the first keyserver specified will be used. If a keyserver is specified on the command line,
any keyservers listed in the PGP Command Line configuration file will not be used.
Preferred keyservers are not used.
The usage format is:
pgp --keyserver-send <input> [<input2> ...] --keyserver <ks>
[--keyserver <ks2> ...] [options]
Where:
<input> is the user ID, portion of the user ID, or key ID of the public key you are
posting. You can list one or more users, with their names/IDs separated by a space.
<ks> is the name of the keyserver to which you are posting.
[options] let you modify the command. Options are:
--keyserver-timeout sets the number of seconds until the keyserver operation
times out. The default setting is 120 seconds.
--halt-on-error moves to the next keyserver if an error occurs, if more than one
keyserver is specified, or the operation stops.
Example:
pgp --keyserver-send alice@example.com --keyserver
ldap://keyserver.example.com
If there are multiple keys on the keyring with user IDs that match the input, all of
them will be posted. To make sure only a specific key is posted, use the key ID as
the input.
pgp --keyserver-send 0x12345678 --keyserver
ldap://keyserver.pgp.com
Only the specified key (if it is on the keyring) will be posted to
ldap://keyserver.pgp.com, a public keyserver.
PGP Command Line User’s Guide 8: Working with Keyservers
86
--keyserver-update
Updates keys that have already been uploaded to a keyserver. This ensures that the most
up-to-date versions of the keys are on the keyserver.
An update consists of finding the key on the keyserver; merging that key onto the local
keyring; and sending the merged key back to the keyserver on which it was found. A key
must be on the local keyring to be updated.
If no keys are specified on the command line, all of the keys on the local keyring are
updated, one at a time. When multiple keys are specified, they are updated one key at a
time.
If a key has a preferred keyserver established, that keyserver is used for the update (only
RSA and DH/DSS v4 keys can have a preferred keyserver); keyservers specified on the
command line or in the configuration file are ignored. If the key being updated is not
found, it is sent to the preferred keyserver; if it is found, it is updated.
If a key does not have a valid preferred keyserver established, PGP Command Line will
search the keyserver specified on the command line, followed by keyservers specified in
the configuration file. If the key cannot be found, an error is returned; if it is found, it is
updated.
The usage format is:
pgp --keyserver-update <input> [<input2> ...] [--keyserver
<ks1> ...] [options]
Where:
<input> is the user ID, portion of the user ID, or key ID of the key for which you are
searching. To find a specific key, use the key ID. To find one or more keys, use the
user ID or portion of the user ID.
<ks> is the name of the keyserver you want to search. You can enter more than one
keyserver to search, separated by a space. Only results from the first keyserver
where there is a match will be returned.
--keyserver-timeout sets the number of seconds until the keyserver operation
times out. The default setting is 120 seconds.
--halt-on-error stops if an error occurs, if more than one keyserver is specified,
or the operation stops.
Examples:
1 pgp --keyserver-update 0x12345678 --keyserver
ldap://keyserver.pgp.com
Updates the key with key ID 0x12345678 on keyserver.pgp.com if that key is on the
local keyring and has already been uploaded to the keyserver. If either is not true, the
operation returns with an error.
2 pgp --keyserver-update 0x12345678
Key 0x12345678 has a preferred keyserver set, and that keyserver is used for the
update.
87
9Managing Keys
Descriptions and Examples of Key Commands
This chapter describes those commands used to manage keys with PGP Command Line.
These commands are:
--add-adk, which adds an ADK to a key (page 89).
--add-photoid, which adds a photo ID to a key (page 90.)
--add-preferred-cipher, which adds the preferred cipher to a key (page 90.
--add-preferred-compression-algorithm, which adds the preferred
compression algorithms to a key (page 91).
--add-preferred-email-encoding, which adds a preferred email encoding to a
key (page 91).
--add-preferred-hash, which adds the preferred hash encryption algorithm to a
key (page 92).
--add-revoker, which adds a revoker to a key (page 92).
--add-userid, which adds a user ID to a key (page 93).
--cache-passphrase, which specifically caches a passphrase (page 93).
--change-passphrase, which changes the passphrase (page 95).
--clear-key-flag, which clears one of the preferences flags (page 95).
--disable, which disables a key (page 96).
--enable, which enables a key (page 96).
--export and --export-key-pair, which export keys or key pairs (page 97).
--export-photoid, which exports a photo ID to a file (page 99).
--gen-key, which generates a new key pair (page 100).
--gen-revocation, which generates a revoked version of a key without actually
revoking the key. The revoked version of the key is stored securely in the event the
passphrase is lost, so the key can still be revoked (page 102).
--gen-subkey, which generates a subkey (page 103).
--import, which imports keys (page 104).
--join-key, which reconstitutes a split key (page 104).
--join-key-cache-only, which temporarily joins a key on the local machine
(page 108).
--key-recon-send, which sends PGP key reconstruction data to a PGP Universal
Server (page 109).
PGP Command Line User’s Guide 9: Managing Keys
88
--key-recon-recv-questions, which retrieves the PGP key reconstruction
questions for a specified key (page 110).
--key-recon-recv, which reconstructs a key (page 111).
--remove, which removes a key (page 112.)
--remove-adk, which removes an ADK from a key (page 112).
--remove-all-adks, which remove all ADKs from a key (page 112).
--remove-all-photoids, which removes all photo IDs (page 113).
--remove-all-revokers, which removes all revokers (page 113).
--remove-expiration-date, which removes the expiration date from a key
(page 114).
--remove-key-pair, which removes a key pair (page 114).
--remove-photoid, which removes a photo ID from a key (page 114).
--remove-preferred-cipher, which removes a preferred cipher from a key
(page 115).
--remove-preferred-compression-algorithm, which removes a preferred
compression algorithm from a key (page 115).
--remove-preferred-email-encoding, which removes a preferred email
encoding from a key (page 116).
--remove-preferred-hash, which removes the preferred hash from a key (page
116).
--remove-preferred-keyserver, which removes a preferred keyserver from a
key (page 117).
--remove-revoker, which removes a revoker from a key (page 117).
--remove-sig, which removes a signature (page 118).
--remove-subkey, which removes a subkey (page 118).
--remove-userid, which removes a user ID from a key (page 119).
--revoke, which revokes a key pair (page 119).
--revoke-sig, which revokes a signature (page 120).
--revoke-subkey, which revokes a subkey (page 120).
--send-shares, which sends shares to the server joining a key (page 121).
--set-expiration-date, which sets the expiration date (page 121).
--set-key-flag, which sets one of the preference flags for a key (page 122).
--set-preferred-ciphers, which sets the list of preferred ciphers on a key
(page 122).
PGP Command Line User’s Guide 9: Managing Keys
89
--set-preferred-compression-algorithms, which sets the list of preferred
compression algorithms on a key (page 123).
--set-preferred-email-encodings, which sets preferred email encodings for
a key (page 124).
--set-preferred-hashes, which sets the entire list of hashes for a key (page
124).
--set-preferred-keyserver, which adds a preferred keyserver to a key (page
125).
--set-primary-userid, which sets a user ID as primary for a key (page 125).
--set-trust, which sets the trust on a key (page 126).
--sign-key, which signs all user IDs on a key (page 126).
--sign-userid, which signs a single user ID on a key (page 127).
--split-key, which splits a specified key into multiple shares (page 128).
Overview
The PGP keys that you create and those you obtain from others are stored in digital
keyrings; private keys are stored on your private keyring in a file named secring.skr
and public keys are stored on your public keyring in a file called pubring.pkr.
PGP Command Line provides great flexibility in what your keys can be used for.
Commands that you can use to manage your keys are described in this chapter.
Commands
--add-adk
Adds an ADK to a key. Keys can support multiple ADKs, if desired.
An Additional Decryption Key (ADK) is a key that allows an authorized person, generally in
an organization, to decrypt data this is from or was sent to someone in the organization if
that person is unable or unwilling to do it themselves.
Only RSA and DH/DSS v4 keys can have ADKs.
The usage format is:
pgp --add-adk <user> --adk <adk> --passphrase <pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key to which the
ADK is being added.
PGP Command Line User’s Guide 9: Managing Keys
90
<adk> is the specific ADK to be added to the key.
<pass> is the passphrase of the key to which the ADK is being added.
Example:
pgp --add-adk "Bob Smith" --adk Alice --passphrase sm1t4
0x6245273E:add ADK (0:ADKs successfully updated)
Adds the specified ADK to the specified key.
--add-photoid
Adds a photo ID to a key. You can add just one photo ID to a key using PGP Command
Line. Other programs that are compatible with PGP Command Line support allow more
than one photo ID added to a file; PGP Command Line can work with these extra photo
IDs.
Only JPEG files can be added. For maximum picture quality, crop the picture to 120 by
144 pixels before adding it.
The usage format is:
pgp --add-photoid <user> --image <photo.jpg> --passphrase
<pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key to which the
photo ID is being added.
<photo.jpg> is the filename of the image being added.
<pass> is the passphrase of the key to which the photo ID is being added.
Example:
pgp --add-photoid Alice --image alice.jpg --passphrase cam3r0n
0x3E439B98:add photo ID (0:photo ID added successfully)
Adds the image alice.jpg to the specified key.
--add-preferred-cipher
Adds a preferred cipher to a key.
If the preferred cipher is already on the key, it is moved to the top of the list. Only RSA v4
and DH/DSS v4 keys can have a preferred cipher.
The usage format is:
pgp --add-preferred-cipher <user> --cipher <cipher>
--passphrase <pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key to which the
preferred cipher is being added.
PGP Command Line User’s Guide 9: Managing Keys
91
<cipher> is the preferred cipher being added.
<pass> is the passphrase of the key.
Example:
pgp --add-preferred-cipher "Bob Smith" --cipher aes256
--passphrase sm1t4
0x6245273E:add preferred cipher (0:preferred ciphers updated)
Adds the cipher AES256 to the specified key.
--add-preferred-compression-algorithm
Adds a preferred compression algorithm to a key.
If the preferred compression algorithm is already on the key, it is moved to the top of the
list. Only RSA v4 and DH/DSS v4 keys can have a preferred compression algorithm.
The usage format is:
pgp --add-preferred-compression-algorithm <user>
--compression-algorithm <algo> --passphrase <pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key to which the
preferred compression algorithm is being added.
<algo> is the preferred compression algorithm being added.
<pass> is the passphrase of the key.
Example:
pgp --add-preferred-compression-algorithm "bob@example.com"
--compression-algorithm bzip2 --passphrase sm1t4
0x6245273E:add preferred compression algorithm (0:preferred
compression algorithms updated)
Adds the compression algorithm Bzip2 to the specified key.
--add-preferred-email-encoding
Adds a preferred email encoding to a key.
If the preferred email encoding is already on the key, it is moved to the top of the list.
Only RSA v4 and DH/DSS v4 keys can have a preferred email encoding.
The usage format is:
pgp --add-preferred-email-encoding <user> --email-encoding
<encoding> --passphrase <pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key to which the
preferred email encoding is being added.
PGP Command Line User’s Guide 9: Managing Keys
92
<encoding> is the preferred email-encoding being added.
<pass> is the passphrase of the key.
Example:
pgp --add-preferred-email-encoding "Bob Smith"
--email-encoding pgpmime --passphrase sm1t4
Adds the email encoding pgpmime to the specified key.
--add-preferred-hash
Adds the preferred hash encryption algorithm to a key and lists it on the top of the hash
list. Note that a key must be at least v4 to have preferred hashes.
The usage format is:
pgp --add-preferred-hash <user> --hash <hash> --passphrase
<pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key to which the
preferred hash is being added.
<hash> is the preferred hash being added to a key. You can add several preferred
hashes to a key, one at a time. The newly added preferred hash will appear on top of
the hash list.
<pass> is the passphrase of the key to which the preferred hashes are being added.
Example:
pgp --add-preferred-hash "Bob Smith" --hash sha512
--passphrase sm1t4
Adds the preferred hash SHA-512 and displays it on top of the hash list.
Hash: SHA-512
--add-revoker
Adds a revoker to a key. It is possible that you might forget your passphrase or lose your
private key, which would mean that you could never use it again and you would have no
way of revoking it. To safeguard against this latter possibility, you can add a key to your
keyring as a revoker, which could be used to revoke your key if you could not do it.
Only RSA and DH/DSS v4 keys can have revokers.
The usage format is:
pgp --add-revoker <user> --revoker <revoker> --passphrase
<pass>
PGP Command Line User’s Guide 9: Managing Keys
93
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key to which the
revoker is being added.
<revoker> is the specific revoker to be added to the key.
<pass> is the passphrase of the key to which the revoker is being added.
Example:
pgp --add-revoker "Bob Smith" --revoker Alice --passphrase
sm1t4
0x6245273E:add revoker (0:revokers successfully updated)
Adds the specified revoker to the specified key:
Revoker: 0x3E439B98 (0xA9B1D2723E439B98)
User ID: Alice Cameron <alice@example.com>
--add-userid
Adds a user ID to a key. You can add as many user IDs as you want to a key. To add a
photo ID, use --add-photoid.
The usage format is:
pgp --add-userid <user> --user <newID> --passphrase <pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key to which the
user ID is being added.
<newID> is the user ID being added to the key.
<pass> is the passphrase of the key to which the user ID is being added.
Example:
pgp --add-userid "bob@example.com" --user Alice --passphrase
sm1t4
Adds the specified user ID to the specified key.
--cache-passphrase
Caches the passphrase for a key for the current session. Caching your passphrase can
save you time in that you do not have to enter it for those operations that require it.
Passphrase caching must be enabled (using the option --passphrase-cache) for this
command to work.
Make sure to log out at the end of your session (which purges the passphrase cache) or
purge the passphrase cache manually using the command
--purge-passphrase-cache.
The number of cached passphrases can be checked with --version in verbose mode.
PGP Command Line User’s Guide 9: Managing Keys
94
The usage format is:
pgp --cache-passphrase <user> --passphrase <pass> [options]
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key whose
passphrase is being cached.
<pass> is the passphrase of the key.
[options] change the behavior of the command. Options are:
--passphrase-cache enables passphrase caching. This is optional, since you can
enable passphrase caching by changing the passphrase cache settings in the
configuration file PGPprefs.xml from false to true.
--passphrase-cache-timeout sets the amount of time a passphrase can be
cached, in seconds. The default is 120. If you enter 0 (zero), the passphrase cache
will not timeout; it must be specifically purged.
Examples:
1 pgp --cache-passphrase "Bob Smith" --passphrase sm1t4
--passphrase-cache
0x6245273E:cache passphrase (0:key passphrase cached)
Caches the passphrase of the specified key. Since no timeout is specified, the
default of 120 seconds will be used.
2 pgp --cache-passphrase "Bob Smith" --passphrase sm1t4
--passphrase-cache --passphrase-cache-timeout 0
0x6245273E:cache passphrase (0:key passphrase cached)
Caches the passphrase of the specified key and establishes a timeout of 0, which
means the passphrase cache must be specifically purged to remove the passphrase
from memory.
PGP Command Line User’s Guide 9: Managing Keys
95
--change-passphrase
Changes the passphrase for a key and all subkeys (if the key has any).
The usage format is:
pgp --change-passphrase <user> --new-passphrase <newpass>
[--passphrase <oldpass>]
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key whose
passphrase is being changed.
<newpass> is the new passphrase of the key.
<oldpass> is the old passphrase of the key.It is not needed if the key has no
passphrase.
Example:
pgp --change-passphrase "Bob Smith" --passphrase sm1t4
--new-passphrase b0bsm1t4
0x6245273E:change passphrase (3135:master passphrase changed)
0x894BA6DC:change passphrase (3136:subkey passphrase changed)
0x6245273E:change passphrase (0:key passphrase changed)
Replaces the old passphrase sm1t4 with the new passphrase b0bsm1t4 for the
specified key and its subkey.
--clear-key-flag
Clears one of the key's preferences flags.
The usage format is:
pgp --clear-key-flag <user> [--subkey <subkeyID>] --key-flag
<flag> [--passphrase <pass>]
Where:
<user> is the user ID, portion of the user ID, or the key ID of the user whose key
preferences flag is being cleared.
<flag> is the key preferences flag to be cleared. See --key-flag for more
details.
<subkeyID> is the subkey ID of the key whose key preferences flag is being
cleared.
<pass> is the passphrase of the key for which the preferences flag is being cleared.
Example:
pgp --clear-key-flag Bob --key-flag encrypt --passphrase sm1t4
Clear the key preference flag "encrypt" from Bob’s key.
PGP Command Line User’s Guide 9: Managing Keys
96
--disable
Disables a key or keypair.
Disabling a key or key pair prevents it from being used without deleting it. Note that you
cannot disable an axiomatic key.
The usage format is:
pgp --disable <user>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key being disabled.
Examples:
1 pgp --disable "Jose Medina"
0xF6EFC4D9:disable key (3067:key is axiomatic)
You cannot disable Joses key since it is axiomatic.
2 pgp --disable "Maria Fuentes"
0x136259CB:disable key (0:key successfully disabled)
Maria’s public key is disabled.
--enable
Enables a key or keypair that has been disabled.
Once enabled, you can use the key or keypair again.
The usage format is:
pgp --enable <user>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key being enabled.
Example:
pgp --enable "Maria Fuentes"
0x136259CB:enable key (0:key successfully enabled)
Maria’s public key is enabled.
PGP Command Line User’s Guide 9: Managing Keys
97
--export, --export-key-pair
Exports keys or key pairs. You will export a key so that you can send a public key to your
correspondents and/or to a public keyserver. Keys are exported as ASCII armor files
(.asc), or in other supported export formats. Note that when you are exporting a key pair,
the operation will be successful when there is only one key pair that contains the string
you specify as input (see examples).
At least one key must be specified for export. Keys are exported as ASCII armor (.asc)
files into the current directory. Keys can also be exported in other formats; refer to
“Export Format” on page 98 for detailed information.
The command --export exports only public keys, while the command
--export-key-pair exports private keys.
The usage format is:
pgp --export/--export-key-pair <input> [options]
Where:
<input> is the user ID, portion of the user ID, or the key ID of the key you want to
export.
[options] change the behavior of the command. Options are:
--output lets you specify a different name for the exported file.
--export-format lets you specify an export format from the following list of
supported formats. For more information, refer to --export-format.
--cert. This option is the X.509 issuer long name or the 32-bit or 64-bit key ID, if
the signing key is available.
--export-passphrase specifies the passphrase to use when exporting PKCS8
and PKCS12 data. If only --export-passphrase is supplied, PGP Command Line
does the following depending on the used argument:
valid. Exports with the export passphrase.
invalid. Gives an error.
--passphrase belongs to the key that has a certificate. If only --passphrase is
supplied, PGP Command Line does the following depending on the used argument:
valid. Exports the key with no passphrase.
invalid. Gives an error.
To specify no passphrase, use the empty string " ".
Examples:
1 pgp --export Bob
0x6245273E:export key (0:key exported to Bob Smith.asc)
0xF6F83318:export key (0:key exported to Bob Reynolds.asc)
All public keys that contain the string "Bob" were exported.
PGP Command Line User’s Guide 9: Managing Keys
98
2 pgp --export-key-pair "bob@example.com"
0x6245273E:export key pair (0:key exported to Bob Smith.asc)
Bob's key pair was exported to the ASCII-armored file "Bob Smith.asc".
3 pgp --export-key-pair Bob
Bob:export key pair (2003:too many matches for key to edit)
The operation cannot be completed because there is more than one key pair that
contains the string: "Bob".
4 pgp --export-key-pair Medina
0xF6EFC4D9:export key pair (0:key exported to Jose Medina.asc)
This operation was successful because there is only one key pair with the string
"Medina".
Export Format
PGP Command Line supports several export formats:
Complete (default): Only ASCII-armored files are output; the default file extension is
.asc. Use Complete to export keys in a newer format that supports all PGP
features.
Compatible: Only ASCII-armored files are output; the default file extension is .asc.
Use Compatible to export keys in a format compatible with older versions of PGP
software; that is, PGP software versions 7.0 and prior. Some newer PGP features
are not supported when using Compatible.
X.509-cert: Only ASCII-armored files are output; the default file extension is .crt.
The <input> must match exactly one key, and --cert is required.
PKCS8: Only ASCII-armored files are output; the default file extension is .p8. A
signed key must be paired. The <input> must match exactly one key, --cert is
required as well as --passphrase.
The passphrase options change the passphrase of the exported key and certificate.
They do not change the passphrase of the local key.
– If only --passphrase is supplied, and the passphrase is valid, the key/
certificate is exported with no passphrase. If the supplied passphrase is invalid,
an error is generated.
– If only --export-passphrase is supplied, and the passphrase is valid, the
key/certificate is exported with the export passphrase. If the supplied
passphrase is invalid, an error is generated.
– If no --passphrase is supplied, the cache and an empty passphrase is tried.
PKCS12: Only binary blocks are output; the default file extension is .p12. A signed
key must be paired. The <input> must match exactly one key, --cert is required
as well as --passphrase.
The passphrase options change the passphrase of the exported key and certificate.
They do not change the passphrase of the local key.
PGP Command Line User’s Guide 9: Managing Keys
99
– If only --passphrase is supplied, and the passphrase is valid, the key is
exported with no passphrase. If the supplied passphrase is invalid, an error is
generated.
– If only --export-passphrase is supplied, and the passphrase is valid, the key
is exported with the export passphrase. If the supplied passphrase is invalid, an
error is generated.
If no passphrase is supplied, the cache and an empty passphrase is tried.
Certificate signature request (CSR): Only ASCII-armored blocks are output. The
default file extension is .csr. Key must be paired. The input must match exactly one
key.
Example:
pgp --export "Bob Smith" --export-format pkcs12 --passphrase
sm1t4 --cert 0x6245273E
0x6245273E:export key (0:key exported to Bob Smith.p12)
Bob's key pair is exported to a file "Bob Smith.p12".
--export-photoid
Exports a photo ID from a key to a file. There must be a photo ID on the key for it to be
exported. Only JPEG files are supported. Resulting files are saved to the current
directory.
The usage format is:
pgp --export-photoid <user> [options]
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key from which the
photo ID is being exported.
[options] change the behavior of a command. Options are:
--index specifies which photo ID on the key should be exported. 1 indicates the
first photo ID, 2 the second photo, and so on.
--output is a desired filename.
Examples:
1 pgp --export-photoid "Alice C"
Exports the photo ID to filename "alice c.jpg".
2 pgp --export-photoid "Alice C" --output photoid.jpg
Exports the photo ID to filename "photoid.jpg".
3 pgp --export-photoid "Alice C" --index 2
Exports the second photo ID on the key to filename "alice c.jpg".
PGP Command Line User’s Guide 9: Managing Keys
100
--gen-key
Creates a new key. It also creates a keyring pair if no keyrings exist.
The usage format is:
pgp --gen-key <user> --key-type <type> --encryption-bits <bits>
--passphrase <pass> [--signing-bits <bits>] [options]
Where:
<user>. This is a user for whom the key is being generated. A common user ID is
your name and email address in the format: "Alice Cameron <alice@example.com>".
If your user ID contains spaces, you must enclose it in quotation marks.
<type> is the key type: rsa, rsa-legacy, rsa-sign-only, dh, or dh-sign-only.
--encryption-bits. This is the length of the encryption subkey in bits (1024 -
4096). When generating sign-only keys (keys without a subkey), you can specify
--bits only to define the signing key size.
<pass> is a passphrase of your choice. This flag is not optional: to generate a key
without a passphrase, use --passphrase " ".
--signing-bits defines the length of the signing key in bits. The valid sizes in bits
for signing keys are as follows: for RSA legacy 1024 to 2048 bits; for RSA v4 1024 to
4096 bits; and for DH the size is only 1024 bits. For RSA v4 keys, this option can be
set independently from --bits.
[options] modify the behavior of the command. Options are:
--adk specifies an ADK (Additional Decryption Key). See --adk for more
information.
--compression-algorithm sets the compression algorithm. Note that this
option does not work with public-key encryption, because in this case the recipient’s
key preferences are used. The default for this option is zip. See
--compression-algorithm for more information.
--creation-date changes the date of creation. The format is yyyy-mm-dd and
it cannot be used together with --creation-days. Month and day do not have to
be two digits if the first digit is zero.
--creation-days changes the number of days until creation ("1" equals next day,
"2" equals day after next, etc.)
--expiration-date changes the date of expiration. The format is yyyy-mm-dd.
This option cannot be used at the same time as
--expiration-days. Month and day do not have to be two digits if the first digit is
zero.
--expiration-days changes the number of days until expiration. The default is
not set (no expiration).
--fast-key-gen enables fast key generation. The default is on.
--preferred-keyserver specifies a preferred keyserver. The keyserver must
have the correct prefix: http://, ldap://, ldaps://, or hkp://.
PGP Command Line User’s Guide 9: Managing Keys
101
--revoker specifies a revoker for a key. See --revoker for more information.
Any cipher lets you specify which ciphers can be used with the key being
generated; see “--set-preferred-ciphers” on page 123 for more information.
Any compression algorithm lets you specify which compression algorithms can be
used with the key being generated; see “--set-preferred-compression-algorithms” on
page 123 for more information.
Any preferred hash lets you specify which hashes can be used with the key being
generated; see “--set-preferred-hashes” on page 124 for more information.
Any preferred email encoding lets you specify which email encodings can be used
with the key being generated; see “--set-preferred-email-encodings” on page 124 for
more information.
Examples:
1 pgp --gen-key "Alice Cameron <alice@example.com>" --key-type
rsa --encryption-bits 2048 --signing-bits 2048 --passphrase
cam3r0n --expiration-date 2007-06-01
Creates a key pair for Alice with the expiration date June 1, 2007.
2 pgp --gen-key "Fumiko Asako <fumiko@example.com>"
--encryption-bits 2048 --signing-bits 2048 --key-type rsa
--passphrase asak0 --preferred-keyserver
"ldap://keys.example.com"
Creates a key pair for Fumiko with the preferred keyserver "ldap://
keys.example.com".
3 pgp --gen-key ... --aes256 1 --3des 2 --preferred-keyserver
ldap://aes.pgp.com
Creates a key pair with aes256 as the preferred cipher and 3des as the secondary
cipher.
Key Types
PGP Command Line gives you several key types to choose from: RSA, RSA-legacy,
RSA-sign-only, DH, DH-sign-only. Each is described below:
RSA. RSA v4 keys support all PGP key features, such as ADKs, designated revoker,
preferred ciphers, multiple encryption subkeys, or photo IDs. Their size is 1024 bits
to 4096 bits.
RSA-legacy. This is a RSA v3 (legacy) key, for which either --bits or
--signing-bits can be supplied. These keys are used only for communicating
with people who are using older versions of PGP applications. Note that RSA v4 and
RSA v3 (legacy) keys are not compatible. Unlike v4 keys, v3 keys do not support
many features such as ADKs, designated revoker, multiple encryption subkeys, or
photo IDs. RSA v3 keys can have a length of maximum 2048 bits.
PGP Command Line User’s Guide 9: Managing Keys
102
RSA-sign-only. These are RSA v4 keys with no automatically generated subkey.
You can generate a subkey for this key later by using --gen-subkey. Like any other
v4 keys, they support all PGP key features, such as ADKs, designated revoker,
preferred ciphers, and so on.
DH. Diffie-Hellman (DH/DSA) signing keys can only be 1024 bits long. Their subkeys
(the encryption keys) can be longer; therefore, specifying longer bit sizes for this key
type only affects the subkey size. Version 4 keys support all PGP key features, such
as ADKs, designated revoker, preferred ciphers. This is a DH/DSA key with no
automatically generated subkey. Since only the signing key is generated, the size
cannot be larger than 1024 bits: if you enter a larger size, the key will not be
generated. Version 4 keys support all PGP key features, such as ADKs, designated
revoker, preferred ciphers, and so on.
DH-sign-only. This is a DH/DSS key without an encryption subkey. Maximum size is
1024 bits.
--gen-revocation
Generates a revocation certificate for a key, but it doesn't revoke the key on the key ring.
By default, the revocation certificate is exported as if you have used the command
--export.
The usage format is:
pgp --gen-revocation <user> --passphrase <pass> --force [--revoker
<revoker>][--output <output>]
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key being revoked.
<pass> is the passphrase of the key being revoked.
--force is required to revoke a key.
<revoker> is the user ID, portion of the user ID, or the key ID of the designated
revoker key. When this option is used, the passphrase belongs to the revoker key.
This option is not needed if you use a designated revoker or if you are doing self
revocation.
<output> is used to change the location of the exported certificate.
Example:
pgp --gen-revocation "Jose Medina" --passphrase med1na --force
0xF6EFC4D9:generate revocation (0:key exported to Jose
Medina.asc)
0xF6EFC4D9:generate revocation (2094:this key has NOT been
permanently revoked)
Generates the revocation certificate "Jose Medina.asc".
PGP Command Line User’s Guide 9: Managing Keys
103
--gen-subkey
Generates a subkey on an existing key. The key must be allowed to have subkeys or this
operation fails. The subkey is always of the same type as the key to which it is being
added.
The usage format is:
pgp --gen-subkey <user> --bits <bits> --passphrase <pass>
[options]
Where:
<user> is the user ID, portion of the user ID, or key ID of the key that is getting the
subkey.
<bits> specifies the length of the encryption subkey in bits. Values are 1024 to
4096.
<pass> is the passphrase of the key that is getting a subkey.
[options] change the behavior of the command. Options are:
--creation-date specifies the date on which the key becomes valid. You cannot
use --creation-date and --creation-days for the same operation.
--creation-days specifies the number of days until creation.
--expiration-date specifies the date the key expires. You cannot use
--expiration-date and --expiration-days in one operation.
--expiration-days specifies the number of days until expiration.
Example:
pgp --gen-subkey "bob@example.com" --bits 2048 --passphrase
b0bsm1t4
0x3D58AE31:generate subkey (0:subkey successfully generated)
Generates a subkey of the specified number of bits on Bob’s key:
Subkey ID: 0x3D58AE31 (0xAEE6484D3D58AE31)
Type: RSA (v4)
Size: 2048
Created: 2005-11-18
Expires: Never
Status: Active
Revocable: Yes
Prop Flags: Encrypt communications
Prop Flags: Encrypt storage
PGP Command Line User’s Guide 9: Managing Keys
104
--import
Imports keys to the local keyring.
The file containing the key(s) to be imported should be in the current directory, or you
must specify the fully qualified path to the file containing the keys. Note that both private
and public keys will be imported, if they exist in the file. If a key being imported already
exists in the local keyring, the keys are merged.
The usage format is:
pgp --import <input> [<input2> ...] [options]
Where:
<input> is the filename of the key being imported. Multiple keys can also be
imported by listing them, separated by a space.
[options] modify the behavior of the command. Options are:
--import-format specifies the import format for the current operation. See
--import-format for more information.
--manual-import-keys changes the behavior of PGP Command Line when keys
are found during import operations. The default is all.
--manual-import-key-pairs changes the behavior of PGP Command Line
when key pairs are found during an import operation.
--passphrase is the passphrase of the key being imported.
Example:
pgp --import "Bob Smith.asc"
Bob Smith.asc:import key (0:key imported as 0x6245273E Bob
Smith <bob@example.com>)
Imports Bob’s key ’Bob Smith.asc".
--join-key
This command joins the shares of a key that was previously split.
The minimum number of share files must be on the computer where the key is being
joined. The passphrase cache must be enabled for this command to work with public
keys that have passphrases; no passphrase caching is required for public keys with no
passphrases.
Since PGP Command Line currently cannot cache symmetrical passphrases, you need to
enter all necessary symmetrical passphrases onto the command line during key joining.
The symmetrical passphrases are added together with corresponding share files onto the
command line.
You can also turn on automatic passphrase caching by changing the value for
CLpassphraseCache from false/ to true/ in the preference file
PGPprefs.xml, which is located in your Data directory.
PGP Command Line User’s Guide 9: Managing Keys
105
Following is an overview of how PGP Command Line handles key joining:
Local shares are always assembled before PGP Command Line begins listening on
the network for remote shares.
If the local shares are based on keys with passphrases, the passphrases must be
cached.
If the local shares are conventionally encrypted, the passphrase must be supplied on
the command line.
If there are enough local shares for reconstruction of the key, PGP Command Line
does not listen on the network for remote shares.
If you are experiencing problems with your local shares, perform the --join-key
command without --force; PGP Command Line will return all of the information about
each local file share that it has found, including whether or not the passphrases are
correct. If you find problems without --force, fix them. Once all problems with the local
shares are fixed, add --force and --skep to have PGP Command Line listen on the
network for remote shares after collecting the local shares.
The usage format is:
pgp --join-key <user> --passphrase <new pass> --share <share1> --share
<share2> [--share <shareN> ...] [--force] [options]
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key you want to
join. You must make an exact match, as you can only join one key at a time.
<new pass> This is the passphrase of the newly joined key. It is given to the new
key after the threshold requirement is removed: there were enough shares put
together for the key to be joined.
<share1> <share2> are share files given to a specific user when the key was split.
When you join the key using these shares, you need to reach the threshold: the
minimum number of shares needed for joining operation to succeed.
You need to supply the symmetrical passphrases incorporated with the shares for
any share users who have such passphrases.
The share file format for users with symmetric passphrases (that cannot be cached
for this operation) is as follows:
--share "<share user>-2-<split key ID>.shf:<share user's
symmetric passphrase>" --share "Alice Cameron-2-Jill
Johnson.shf:ji11"
The share file format for users with asymmetric passphrases (that must be cached
for this operation) is as follows:
--share "<share user>-1-<split key ID>.shf" --share "Alice
Cameron-1-Bob Smith.shf"
PGP Command Line User’s Guide 9: Managing Keys
106
--force. If you run the --join command without the --force option, PGP
Command Line will not join the key: it will only list the state of the shares in the
preview mode. The output will not be displayed if there are parse errors, or if a key is
missing or unable to decrypt.
The key shares preview will report if there are enough shares to join the key and if
there are invalid (or not cached) passphrases.
--skep. PGP Command Line uses this option when joining split keys over the
network. It looks for split files on the network and if it doesn't find enough of them, it
continues to listen using the timeout defined by the option --skep-timeout.
--skep-timeout changes the timeout for joining keys over the network. There is
no value reserved to indicate no timeout. Default is 120 seconds
-v|--verbose will give a detailed overview of the operation.
Examples:
1In this example, the original key was split in 50 shares with a threshold of 40.
Therefore, you need only 40 shares in order to join the key: you can take shares from
two share users who together have 40 shares.
In order to join a key, you need first to cache passphrases of the users whose shares
you are joining:
pgp --cache-passphrase "Bob Smith" --passphrase sm1t4
--passphrase-cache 0x2B65A65E:cache passphrase
(0:key passphrase cached)
You will enter the symmetrical passphrase together with the shares onto the
command line (Jill's passphrase in this example):
pgp --join-key "Alice Cameron" --passphrase testkey --share
"Alice Cameron-1-Bob Smith.shf" --share "Alice Cameron-2-Jill
Johnson.shf:ji11"
2 pgp --join-key "Alice Cameron" --passphrase testkey --share
"Alice Cameron-1-Bob Smith.shf" --share "Alice Cameron-2-Jill
Johnson.shf:ji11" --force --skep --skep-timeout 300
Tells the key joining operation to wait 5 minutes before it times out.
Command output for --join-key
Row 1: Split Key User Name
Name: "Split Key User"
Value: Primary user ID of the key being split, in this case "Alice Cameron".
Row 2: Split Key ID
Name: "Split Key ID"
Value: The 32-bit key ID followed by the 64-bit key ID in the format:
0xEB778BFA (0xEF20715FEB778BFA)
PGP Command Line User’s Guide 9: Managing Keys
107
Row 3: Empty
Row 4: Threshold
Name: "Threshold"
Value: This is the threshold for the key being split (minimum number of shares to put the
key back together).
If threshold cannot be determined when joining a key, the character "?" is displayed. This
can happen when PGP Command Line displays this information before it listens for
network shares.
Row 5: Total Shares
Name: "Total Shares"
Value: Join. This is the number of shares being collected from the file shares.
Row 6: Total Users
Name: "Total Users"
Value: Join. This is the total number of users from whom PGP Command Line has
collected file shares. When joining a key using --skep, network shares will not show
here because they are collected after this information is displayed.
Row 7: Empty
Row 8-N: Share User
Name: Share User
Value: The parsed value of each share in the following format:
Share User: 20 0xB910E083 Bob Smith
Number of shares assigned to a specific user (3 characters, left justified).
Key ID of the share recipient. For public key encryption, this is a key ID in standard
format, while for symmetric encryption, this is the string "symmetric".
The name of the share recipient. For public key encryption, this is the primary user ID
string; for symmetric encryption, this is the name provided in the --share option.
If there are no share users specified, "N/A" is displayed. This can only happen when
joining a key with the --skep option enabled.
pgp --join-key "Alice Cameron" --passphrase testkey --share
"Alice Cameron-1-Bob Smith.shf" --share "Alice Cameron-2-Jill
Johnson.shf:ji11" --force
The key is joined:
0xEB778BFA:join key (3134:reconstructed split key passphrase is
valid)
0xEB778BFA:join key (0:key joined successfully)
PGP Command Line User’s Guide 9: Managing Keys
108
--join-key-cache-only
Use this command to temporarily join a key on the local machine. After the key is joined,
it is not saved to the disk: instead, the key remains split and the newly joined key is
cached for later use.
The passphrase cache must be enabled for this command to work with public keys that
have passphrases; no passphrase caching is required for public keys with no
passphrases.
The usage format is:
pgp --join-key-cache-only <user> --share <share1> --share
<share2> [--share <shareN> ...] --force [-v|--verbose][--skep]
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key being joined.
<share1> and <share2> are the share files given to specific users when the key
was split. When you join the key using these shares, you need to reach the
threshold: the minimum number of shares needed for joining operation to succeed.
The minimum number of shares is two.
For more information, refer to the command --join-key.
--force. If you run the --join-key-cache-only command without this
option, PGP Command Line will not join the key: it will only list the state of the
shares in the preview mode. The output will not be displayed if there are parse
errors, if a key is missing, or PGP Command Line was unable to decrypt.
The key shares preview will report if there are enough shares to join the key. and if
there are invalid (or not cached) passphrases.
-v|--verbose. This option will give a detailed overview of the operation.
--skep. PGP Command Line uses this option when joining split keys: it looks for
split files on the network. If it doesn't find enough of split files, it will continue to
listen on the network using the timeout defined by the option --skep-timeout.
Example:
Before you run --join-key-cache-only, refer to --passphrase-cache for
more explanation on enabling passphrase caching.
pgp --join-key-cache-only "Alice Cameron" --passphrase newkey
--share "Alice Cameron-1-Alice Cameron.shf:brapa1" --share
"Alice Cameron-2-Jose Medina.shf:med1na" --force
Split Key User: Alice Cameron
Split Key ID: 0xB910E083 (0xBCC87BD2B910E083)
Threshold: 20
Total Shares: 20
Total Users: 2
Share User: 10 symmetric Alice Cameron
PGP Command Line User’s Guide 9: Managing Keys
109
Share User: 10 symmetric Jose Medina
0xB910E083:join key cache only (3134:reconstructed split key
passphrase is valid)
0xB910E083:join key cache only (0:key passphrase cached)
After the key is joined, it is not saved to the disk: instead, the key remains split and
the passkey is cached for later use.
--key-recon-send
Sends PGP key reconstruction data to a PGP Universal Server.
Key reconstruction works with PGP Universal Version 2.0 or greater (it is not supported by
Version 1.x PGP Universal, nor does it work with PGP Keyserver Version 7.0).
Key reconstruction lets you store your private key and passphrase so that only you can
retrieve it. It is a safety net in case you lose your private key or its passphrase.
Key reconstruction requires a PGP Universal Server that is getting user data from an
account on an Active Directory server. If no reconstruction server is specified, the
preferred server on the key will be used.
When setting up key reconstruction, you create five questions and answers. To
reconstruct the key, you must answer three or more of the five questions correctly (the
threshold of three correct answers is not configurable).
The usage format is:
pgp --key-recon-send <key> [--question <q1> ... --question
<q5>] [--answer <a1> ... --answer <a5>] --passphrase <pass>
--auth-username <auth user> --auth-passphrase <auth pass>
[--recon-server <recon server>]
Where:
<key> is the user ID, portion of the user ID, or the key ID of the key whose
reconstruction data you want to send to a PGP Universal Server.
<q1> is a first of five questions that only you can answer.
<a1> is the answer to the first question. Answers must be at least six characters
long.
<pass> is the passphrase to your private key.
<auth user> is your username on an Active Directory server. This username will
be authenticated by the PGP Universal Server.
<auth pass> is your passphrase on an Active Directory server. This passphrase
will be authenticated by the PGP Universal Server.
<recon server> is the PGP Universal Server on which your key reconstruction
information is stored.
PGP Command Line User’s Guide 9: Managing Keys
110
Examples:
pgp --key-recon-send 0xEB778BFA --question "First question?"
--answer "First answer" ... --auth-username myuser
--auth-passphrase mypass
The specified key (0xEB778BFA)is sent to the preferred server on the key
accompanied by the five questions and answers and the authorization username and
passphrase for the Active Directory server.
pgp --key-recon-send 0xEB778BFA --question "First question?"
--answer "First answer" ... --question "Fifth question?"
--answer "Fifth answer" --auth-username myuser
--auth-passphrase mypass --recon-server 10.1.1.45
The specified key (0xEB778BFA)is sent to the PGP Universal Server with IP address
of 10.1.1.45 accompanied by the five questions and answers and the authorization
username and passphrase for the Active Directory server.
--key-recon-recv-questions
Retrieves PGP key reconstruction questions for a specified key.
In order to be retrieved, the key reconstruction questions must already reside on the PGP
Universal Server.
PGP Command Line responds to a successful request in the following format:
User ID: <user>
Key ID: <keyID>
Question 1: <question1>
...
Question 5: <question5>
Where:
<user> is the user ID of the key being reconstructed.
<keyID> is key ID of the key being reconstructed.
<question1> is the first of the five stored questions, <question2> is the second of
the five stored questions, and so on through <question5>, the last of the second of
the five stored questions.
The usage format is:
pgp --key-recon-recv-questions <key> --auth-username <auth
user> --auth-passphrase <auth pass> [--recon-server <recon
server>]
Where:
<key> is the user ID, portion of the user ID, or the key ID of the key whose
reconstruction data you want to send to a PGP Universal Server.
<auth user> is your username on an Active Directory server. This username will
be authenticated by the PGP Universal Server.
PGP Command Line User’s Guide 9: Managing Keys
111
<auth pass> is your passphrase on an Active Directory server. This passphrase
will be authenticated by the PGP Universal Server.
<recon server> is the PGP Universal Server on which your key reconstruction
information is stored.
Example:
pgp --key-recon-recv-questions 0x3D58AE31 --auth-username
myuser --auth-passphrase mypass --recon-server 10.1.1.45
The PGP key reconstruction questions for the specified key (0x3D58AE31)are
retrieved from the specified PGP Universal Server.
--key-recon-recv
Reconstructs a private key locally, on successful completion of the five key reconstruction
questions.
A new passphrase must be specified, even if it is blank (" ").
The usage format is:
pgp --key-recon-recv <key> [--answer <a1> ... --answer <a5>]
--new-passphrase <newpass> --auth-username <auth user>
--auth-passphrase <auth pass> [--recon-server <recon server>]
--force
Where:
<key> is the user ID, portion of the user ID, or the key ID of the key being
reconstructed.
<a1> is the answer to the first question of the five questions that only you can
answer. Answers must be at least six characters long.
<newpass> is the new passphrase for your reconstructed private key.
<auth user> is your username on an Active Directory server. This username will
be authenticated by the PGP Universal Server.
<auth pass> is your passphrase on an Active Directory server. This passphrase
will be authenticated by the PGP Universal Server.
<recon server> is the PGP Universal Server on which your key reconstruction
information is stored.
<force> is required.
Example:
pgp --key-recon-recv 0x3D58AE31 --answer "Answer 1" ...
--answer "Answer 5" --new-passphrase cam3r0n-Alic&
--auth-username myuser --auth-passphrase mypass
--recon-server 10.1.1.45
The answers to the questions stored for the specified key (0x3D58AE31) on the
specified PGP Universal Server are provided and the key is reconstructed.
PGP Command Line User’s Guide 9: Managing Keys
112
--remove
Removes a public key (not private keys) from the local keyring.
The usage format is:
pgp --remove <input>
Where:
<input> is the user ID, portion of the user ID, or the key ID of the key that is being
removed from the keyring.
Example:
pgp --remove 0x12345678
Removes the specified key from the keyring.
--remove-adk
Removes a specific ADK from a key.
You can remove an ADK by name if the ADK is present on the local keyring. Otherwise,
you must use the key ID.
The usage format is:
pgp --remove-adk <user> --adk <adk> --passphrase <pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key from which the
ADK is being removed.
<adk> is the specific ADK to be removed from the key.
<pass> is the passphrase of the key from which the ADK is being removed.
Example:
pgp --remove-adk "Bob Smith" --adk Alice --passphrase b0bsm1t4
0x6245273E:remove ADK (0:ADKs successfully updated)
Removes the specified ADK from Bob’s key.
--remove-all-adks
Removes all ADKs from a key.
The usage format is:
pgp --remove-adks <user> --passphrase <pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key whose ADKs
are being removed.
<pass> is the passphrase of the key.
PGP Command Line User’s Guide 9: Managing Keys
113
Example:
pgp --remove-all-adks alice@example.com --passphrase cam3r0n
0x3E439B98:remove all ADKs (0:ADKs successfully updated)
Removes all ADKs from Alice’s key.
--remove-all-photoids
Removes all photo IDs from a key. PGP Command Line can add only one photo ID, but it
can remove multiple photo IDs that exist on a key.
The usage format is:
pgp --remove-all-photoids <user>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the user whose photo
IDs are being removed.
Example:
pgp --remove-all-photoids Alice
0xD0EA20A7:remove all photo IDs (0:removed photo IDs, 1)
All photo IDs are removed from Alice's key.
--remove-all-revokers
Removes all revokers from a key.
The usage format is:
pgp --remove-all-revokers <user> --passphrase <pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key whose
revokers are being removed.
<pass> is the passphrase of the key.
Example:
pgp --remove-all-revokers alice@example.com --passphrase
cam3r0n
0x3E439B98:remove all revokers (0:revokers successfully
updated)
Removes all revokers from Alice’s key.
PGP Command Line User’s Guide 9: Managing Keys
114
--remove-expiration-date
Removes the expiration date from a key.
The usage format is:
pgp --remove-expiration-date <user> --passphrase <pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key whose
expiration date is being removed.
<pass> is the passphrase of the key.
Example:
pgp --remove-expiration-date Cameron --passphrase cam3r0n
0x3E439B98:remove expire date (0:expiration date successfully
updated)
Removes the expiration date from Alices key.
--remove-key-pair
Removes a key pair from the local keyring. The option --force is required to make it
more difficult to accidentally remove a key pair.
The usage format is:
pgp --remove-key-pair <input> --force
Where:
<input> is the user ID, portion of the user ID, or the key ID of the key pair that is
being removed from the keyring.
Example:
pgp --remove-key-pair "Jose Medina" --force
0xF6EFC4D9:remove key pair (0:key successfully removed)
Removes Jose’s key pair from the keyring.
--remove-photoid
Removes a photo ID from a key. There must be a photo ID on the key for it to be removed.
The usage format is:
pgp --remove-photoid <user> [options]
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key from which the
photo ID is being removed.
--index specifies which photo ID on the key should be exported. 1 indicates the
first photo ID, 2 the second photo, and so on.
PGP Command Line User’s Guide 9: Managing Keys
115
Examples:
1 pgp --remove-photoid "Bob Smith"
0x6245273E:remove photo ID (0:successfully removed photo ID)
Removes the photo ID from Bob’s key.
2 pgp --remove-photoid 0x12345678 --index 2
Removes only the second photo ID from the specified key.
--remove-preferred-cipher
Removes a preferred cipher from a key.
The usage format is:
pgp --remove-preferred-cipher <user> --cipher <cipher>
--passphrase <pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key from which the
preferred cipher is being removed.
<cipher> is the preferred cipher being removed.
<pass> is the passphrase of the key.
Example:
pgp --remove-preferred-cipher "Bob Smith" --cipher blowfish
--passphrase b0bsm1t4
0x6245273E:remove preferred cipher (0:preferred ciphers
updated)
Removes the cipher Blowfish from Bob’s key.
--remove-preferred-compression-algorithm
Removes a preferred compression algorithm from a key.
The usage format is:
pgp --remove-preferred-compression-algorithm <user>
--compression-algorithm <algo> --passphrase <pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key from which the
preferred compression algorithm is being removed.
<algo> is the preferred compression algorithm being removed.
<pass> is the passphrase of the key.
PGP Command Line User’s Guide 9: Managing Keys
116
Example:
pgp --remove-preferred-compression-algorithm "Bob Smith"
--compression-algorithm bzip2 --passphrase b0bsm1t4
0x6245273E:remove preferred compression algorithm (0:preferred
compression algorithms updated)
Removes the compression algorithm Bzip2 from Bob’s key.
--remove-preferred-email-encoding
Removes the preferred email encoding from a key.
A key must be at least v4 to have a preferred email encoding.
The usage format is:
pgp --remove-preferred-email-encoding <user> --email-encoding
<encoding> --passphrase <pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key from which the
preferred email encoding is being removed.
<encoding> is the preferred email encoding being removed from a key. You can
remove several preferred email encodings from a key, one at a time.
<pass> is the passphrase of the key from which the preferred email encodings are
being removed.
Example:
pgp --remove-preferred-hash "Bob Smith" --email-encoding
pgpmime --passphrase sm1t4
Removes the preferred email encoding pgpmime from Bob’s key.
--remove-preferred-hash
Removes the preferred hash from a key. Note that a key must be at least v4 to have
preferred hashes.
The usage format is:
pgp --remove-preferred-hash <user> --hash <hash> --passphrase
<pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key from which the
preferred hash is being removed.
<hash> is the preferred hash being removed from a key. You can remove several
preferred hashes from a key, one at a time.
<pass> is the passphrase of the key from which the preferred hashes are being
removed.
PGP Command Line User’s Guide 9: Managing Keys
117
Example:
pgp --remove-preferred-hash "Bob Smith" --hash md5
--passphrase sm1t4
Removes the preferred hash MD5 from Bob’s key.
--remove-preferred-keyserver
Removes the preferred keyserver from a key.
The usage format is:
pgp --remove-preferred-keyserver <user> --passphrase <pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key from which the
preferred keyserver is being removed.
<pass> is the passphrase of the key.
Example:
pgp --remove-preferred-keyserver "Bob Smith" --passphrase
b0bsm1t4
0x6245273E:remove preferred keyserver (0:preferred keyserver
removed)
The preferred keyserver is removed from Bob’s key.
--remove-revoker
Removes a specific revoker from a key. You can remove a revoker by name if the revoker
is present on the local keyring; otherwise use the key ID.
The usage format is:
pgp --remove-revoker <user> --revoker <revoker> --passphrase
<pass>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key from which the
revoker is being removed.
<revoker> is the specific revoker to be removed from the key.
<pass> is the passphrase of the key from which the revoker is being removed.
Examples:
pgp --remove-revoker Smith --revoker Alice --passphrase sm1t4
0x6245273E:remove revoker (0:revokers successfully updated)
Removes the specified revoker from Bob’s key.
PGP Command Line User’s Guide 9: Managing Keys
118
--remove-sig
Removes a signature from your public key.
You can remove a signature from any key on the local keyring. The signature will be
merged back into the key when it is updated from the keyserver.
If you have posted your public key to a keyserver with the signature you are removing,
first remove your public key from the keyserver, remove the signature on your local public
key, and then post your key back to the keyserver. This will prevent the signature from
being merged back in on update.
The usage format is:
pgp --remove-sig <user> --sig <signature>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the public key that
holds the signature you want to remove. Be specific since there can be multiple
signatures from the same user on different user IDs of the same key.
<sig> is the user ID or key ID of the key of the signature you are removing from your
public key. You must match this ID exactly.
Example:
pgp --remove-sig "Bob Smith" --sig 0x3E439B98
0x6245273E:remove signature (0:removed signature by user Alice
Cameron <alice@example.com>)
Removes a specific signature (0x3E439B98) from Bob’s key.
--remove-subkey
Removes a subkey from a key on the local keyring.
The only way to specify the subkey is by its key ID. The --force option is required to make
it more difficult to accidentally remove a subkey. No passphrase is required.
The usage format is:
pgp --remove-subkey <user> --subkey <subkey> --force
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key from which the
subkey is being removed.
<subkey> is the key ID of the subkey being removed.
Example:
pgp --remove-subkey bob@example.com --subkey 0x3D58AE31
--force
0x3D58AE31:remove subkey (0:subkey successfully removed)
The specified subkey (0x3D58AE31)is removed from Bob’s key.
PGP Command Line User’s Guide 9: Managing Keys
119
--remove-userid
Removes a user ID from a key. If a key has only one user ID, you cannot remove it; also,
when removing user IDs, you cannot remove the last user ID. You cannot have a key with
only a photo ID. This command does not remove photo IDs; refer to the
--remove-photoid command.
If you remove the primary user ID on a key, the next one below it becomes primary; to
establish a different primary user ID, use --set-primary-userid.
The usage format is:
pgp --remove-userid <user> --user <userID>
Where:
<user> is the user ID, portion of the user ID, or the key ID of the key from which the
user ID is being removed.
<userID> is the user ID being removed from the key.
Examples:
pgp --remove-userid "Bob Smith" --user Alice
0x6245273E:remove user ID (0:successfully removed Alice)
Removes the user ID "Alice" from Bob’s key.
--revoke
Revokes a key on the local keyring.
If for some reason you cannot trust a key pair, you can revoke it, which tells the world to
stop using your public key to encrypt data to you. The best way to circulate a revoked key
is to put it onto a public keyserver after you have revoked it.
--force is required to make it more difficult to accidentally revoke a key.
The usage format is:
pgp --revoke <user> [--revoker <revoker>] --passphrase <pass>
--force
Where:
<user> is the user ID, portion of user ID, or the key ID of the key being revoked.
<pass> is the passphrase to the key being revoked.
<revoker> is the user ID, portion of the user ID, or the key ID of the designated
revoker key. When this option is used, the passphrase belongs to the revoker key.
This option is not needed if you use a designated revoker or if you are doing self
revocation.
Examples:
1 pgp --revoke "Bob Smith"